Skip to content

Token Transformations#

Token transformations are a way to tranform input arguments before they are mapped to commands.

This feature is used internally to expand clubbed options and support Response Files.

See these implementations as examples:

How to implement#

First, create a function with the signature Func<CommandContext, TokenCollection, TokenCollection>. This function will transform a TokenTransformation into a new TokenTransformation.

Next, register the transformation with

appRunner.Configure(c => c.UseTokenTransformation(
    name: "my-transformation", 
    order: 1, 
    transformation: MyFunc));
  • name is used for logging and the Parse Directive
  • order is the order the transformation should run in relation to other transformations.


Tokens are initially parsed from the Program.Main args array. Transformations can modify tokens or expand them into additional tokens.

Tokens contains

  • RawValue: Raw value from the user input. This will contain the punctuation used to denote option and argument names or brackets enclosing directives. (eg. --help, [debug])
  • Value: Can be an Option name or an argument value or a directive(eg. help)
  • TokenType: Directive, Option, Value, Separator
  • OptionTokenType: when TokenType is Option

OptionTokenType contains

  • IsLong: is a long name (--help)
  • IsShort: is a short name (-h)
  • IsClubbed: multiple short names in a single string (-hv).
  • HasValue: the option has a value assignment (--verbosity:trace)


TokenCollections are an immutable collection of tokens with some convenience members to simplify transformations.

  • Directives: The tokens interpreted as directives. This will always be empty when AppSettings.DisableDirectives = false.
  • Arguments: All arguments after the last directive and before the argument separator --
  • Separated: All arguments included after the argument separator --. If there are multiple separators, the remaining separators will be tokens in this collection.


Use TokenCollection.Transform method to apply a func to tokens of specific types. This is an alternative to a foreach loop with a switch statement. See the implementations linked above for examples.

Use TokenCollection.ToArgsArray extension method to convert the tokens into a string array that can be passed to another application.