CommandLineParser Class

The CommandLineParser class can parse a set of command line arguments into values. Which arguments are accepted is determined from the constructor parameters and properties of the type passed to the CommandLineParser(Type) constructor. The result of a parsing operation is an instance of that type that was constructed using the constructor parameters and property values from their respective command line arguments.

The CommandLineParser class can parse a command line and can generate usage help for arguments defined by the type passed to its constructor. This usage help can be presented to the user to provide information about how to invoke your application from the command line.

The command line arguments are parsed using the parsing rules described below. A command line consists of a series of argument values; each value is assigned to the appropriate argument based on either the name or the position of the argument.

Every argument has a name, and can have its value specified by name. To specify an argument name on the command line it must be preceded by a special prefix. On Windows, the argument name prefix is typically a forward slash (/), while on Unix platforms it is usually a single dash (-) or double dash (--). Which prefixes are accepted by the CommandLineParser class can be specified by using the CommandLineParser(Type, IEnumerableString) constructor. By default, it will accept both "/" and "-" on Windows, and only a "-" on all other platforms (other platforms are supported via Mono).

Note

Although almost any argument name is allowed as long as it isn't empty and doesn't contain a colon (:), certain argument names may not be advisable. Particularly, avoid argument names that start with a number, as they it will not be possible to specify them by name if the argument name prefix is a single dash; arguments starting with a single dash followed by a digit are always considered values during parsing, even if there is an argument with that name.

The name of the argument must be followed by its value. The value can be either in the next argument (separated from the name by white space), or separated by a colon (:). For example, to assign the value "foo" to the argument "sample", you can use either -sample foo or -sample:foo.

If an argument has a type of Boolean (and is not a positional argument as described below), it is a switch argument, and doesn't require a value. Its value is determined by its presence on the command line; if it is absent the value is ; if it is present the value is . For example, to set a switch argument named "verbose" to true, you can simply use the command line -verbose. You can still explicitly specify the value of a switch argument, for example -verbose:true. Note that you cannot use white space to separate a switch argument name and value; you must use a colon.

If the type of the argument is NullableT of Boolean, its value will be if it is not supplied, if it is supplied without an explicit value (or with an explicit value of ), and only if its value was explicitly specified as .

An argument value can also refer to an argument by position. A positional argument is an argument that can be set both by name and position. When specified by name, it can appear in any position on the command line, but when specified by position, it must appear in the correct position.

For example, if you have two arguments named "foo" and "bar" which have positions 0 and 1 respectively, you could specify their values using value1 value2, which assigns "value1" to "foo" and "value2" to "bar". However, you could also use -bar value2 -foo value1 to achieve the same effect.

If a positional argument was already specified by name, it is no longer considered as a target for positional argument values. In the previous example, if the command line -foo value1 value2 is used, "value2" is the first positional argument value, but is assigned to "bar", the second positional argument, because "foo" had already been assigned a value by name.

Arguments can either be required or optional. If an argument is required, the Parse(String) method will throw a CommandLineArgumentException if it is not supplied on the command line. For positional arguments, it is not allowed to have a required argument following a positional argument.

If an argument has a type other than String, the CommandLineParser class will use the TypeDescriptor class to get a TypeConverter for that type to convert the supplied string value to the correct type. You can also use the TypeConverterAttribute on the property or constructor parameter that defines the attribute to specify a custom type converter.

If an argument has an array type, it can be specified more than once, and the value for each time is it specified is added to the array. Given an array argument named "sample", the command line -sample 1 -sample 2 -sample 3 would set the value of "sample" to an array holding the values 1, 2 and 3. A required array argument must have at least one value. A positional array argument must be the last positional argument.

To specify which arguments are accepted by the CommandLineParser class, you can use either constructor parameters or properties on the type holding the argument values.

If the arguments type has only one constructor, its parameters are automatically used. If it has more than one constructor, one of the constructors must be marked using the CommandLineConstructorAttribute attribute.

Arguments for constructor parameters are always positional arguments, so can be specified by both name and position. The position of the command line argument will match the position of the constructor parameter. By default, the name of the argument matches the name of the parameter, but this can be overridden using the ArgumentNameAttribute attribute. The argument is optional if the parameter has the OptionalAttribute attribute applied, and its default value can be specified using the DefaultParameterValueAttribute attribute. With Visual Basic and C# 4.0, you can use the built-in syntax for optional parameters to create an optional command line argument and specify the default value.

A property defines a command line argument if it is public, not , and has the CommandLineArgumentAttribute attibute defined. The argument will only be positional if the Position property is set to a non-negative value, and will be required only if the IsRequired property is set to .

Reference