Arguments#
Arguments are defined as parameters of a method or properties of a class (see Argument Models)
As discussed in Terminology, Option and Operand are the two concrete types of IArgument
- Option: named argument
- Operand: positional argument
By default, arguments are operands. Change the default by assigning AppSettings.DefaultArgumentMode = ArgumentMode.Option
Use the [Operand]
and [Option]
attributes to explicity denote which argument type and to configure the arguments.
Tip
See Option vs Operand for recommendations on when to use one vs the other.
Operand Attribute#
The operand attribute has the following properties:
- Name: Used in help documentation only. Defaults to the parameter or property name.
- Description: Used in help documentation.
Option Attribute#
The option attribute has the following properties:
- LongName: Used in help documentation and on the command line. Defaults to the parameter or property name.
- Set to
null
to remove the default long name and have only a short name.
- Set to
- ShortName: Used in help documentation and on the command line. Defaults to null.
- Description: Used in help documentation.
- BooleanMode: When the option is a
bool
, this determines if the presence of the option indicatestrue
(Implicit) or if the user must specifytrue
orfalse
(Explicit).- The default is Implicit and can be changed with
AppSettings.BooleanMode = BooleanMode.Explicit
- Implicit boolean options are also called Flags
- The default is Implicit and can be changed with
- AssignToExecutableSubcommands: only valid when used in Interceptor methods.
Example#
public void LaunchRocket(
[Operand(Name = "planet",
Description = "Name of the planet you wish the rocket to go")]
string planetName,
[Option(LongName = "turbo", ShortName = "t",
Description = "Name of the planet you wish the rocket to go")]
bool turbo,
[Option(ShortName="a",
Description="Abort the launch before takeoff",
BooleanMode=BooleanMode.Explicit)]
bool abort)
and help looks like:
Usage: dotnet CommandDotNet.Example.dll launch-rocket [options] [arguments]
Arguments:
planet <TEXT>
Name of the planet you wish the rocket to go
Options:
-t | --turbo
Name of the planet you wish the rocket to go
-a <BOOLEAN>
Abort the launch before takeoff
Allowed values: true, false
and called any of these ways:
dotnet example.dll LaunchRocket -t -a true mars
dotnet example.dll LaunchRocket --turbo -a true mars
dotnet example.dll LaunchRocket mars -t -a true
dotnet example.dll LaunchRocket mars --turbo -a true
Options are not positional so they can appear in any order within the command.
Configuring a ShortName nullifies the default long name so LongName must also be configured if you need both.
Parameter name | Longname | Shortname | Generated template |
---|---|---|---|
turbo | --turbo |
||
turbo | turbo | --turbo |
|
turbo | t | -t |
|
turbo | turbo | t | -t | --turbo |
t | -t |
Flags#
Flags are boolean options with a default value of false. The presence of the flag indicates true. This simplifies the user experience by allowing them to specifiy -b
instead of -b true
. This also enables clubbing.
Define them as Options with BooleanMode = BooleanMode.Implicit. Implicit is the default defined for AppSettings.DefaultBooleanMode
or OptionAttribute.BooleanMode
.
Flag Clubbing#
Clubbing (aka bundling) is when several flags are specified together using their short names.
For example: -abc
is the same as -a -b -c
Clubbing is only available for flags by short name.
Option assignments#
When assigning option values, the following are the same
--time tomorrow
--time=tomorrow
--time:tomorrow