Option[Attribute]

One of attributes that you'll use most frequently is OptionAttribute. It extends BaseOptionAttribute and it allows you to set the name of a mutually exclusive set (this topic will be discussed later).
Let's define a mandatory switch that can store a string.

C#:

class Options
{
    // ...
    [Option("i", "input", Required = true, HelpText = "Input file to read.")]
    public string InputFile { get; set; };
    // ...
}

After invoking the parser with success, an instance of Options will contain the value from the command line in InputFile property. In this way any alphanumeric string is accepted. You should verify on your own that file exists and/or the field contains a well formed path. (Suggestions on best practices later).
If that target field is a numeric value type (or an enumeration), the parser will reject invalid data.

C#:

class Options
{
    // ...
    [Option("l", "lenght", HelpText = "The maximum number of bytes to process.")]
    public int MaximumLenght { get; set; };
    // ...
}

The following will be accepted.

Console:

GuideApp --lenght=99

GuideApp -l12345

GuideApp -l 555


The following will be rejected.

Console:

GuideApp --lenght=a-string

GuideApp -lsome_text

GuideApp -l text.again


Other attributes derived from CommandLine.Option will inherit its basic features.

The library works without problems with nullable types:

C#:

class Options
{
  // ...
  [Option("s", "some-value", HelpText = "If omitted, will be null.")]
  public int? SomeValue { get; set; };
  // ...
}

Last edited May 20, 2012 at 1:54 PM by gsscoder, version 16

Comments

mbearden Sep 8, 2015 at 4:12 PM 
If this is in the documentation, I haven't yet found it, I just had to infer it from use. (So if I'm wrong, I ask for a correction to the following.)

The parsing behavior is distinct for any option that is a boolean, versus anything not-boolean, as follows:

For boolean properties marked with OptionAttribute, the presence/absence of the given option on a command line is used to set the associated boolean property.

For any other property that is not boolean that is marked with OptionAttribute, then the option, when it appears on a parsed command line, MUST be followed by a parameter that will be parsed as the value to be assigned for that option/property.

Further, multiple instances of the boolean-typed options can be combined into a single command line parameter, but that's not true for non-boolean types. I'll give an example to make this clear, and the example will point out a subtle pitfall (that I fell into when developing unit test cases, since I didn't at first realize all this.)

Consider the following properties used to define options:

[Option('v', "verbose", Required = false, HelpText = "Be chatty.")]
public bool Verbose { get; set; }

[Option('e', "extended", Required = false, HelpText = "Enter extended mode.")]
public bool Extended{ get; set; }

[Option('r', "report", Required = false, HelpText = "Generate reports.")]
public bool Report { get; set; }

Suppose that in like manner, I have defined several boolean options, such that there are "-b", a "-o", and "-s" options defined.

Then consider this command line, which turns "on" the first three options listed above:
MyCommand -v -e -r

This is equivalent to this....
MyCommand --verbose --extended --report

But what does the following line do? Suppose the user running my command forgets to type two dashes when they meant to type "--verbose"...

MyCommand -verbose

As a surprise to me, this is exactly equivalent to the user typing: "-v -e -r -b -o -s". Because, apparently the parsing allows combining multiple boolean options in one single parameter that starts with one dash. (And now back to the documentation....I would have wished I had known that earlier from reading the docs. It's a common enough command line parsing practice, but not necessarily obvious.)

Therefore, it could be risky in practice to define full "--" versions of the parameters that are spelled with characters that happen to be used for defining the "-" version of boolean options.

And since that just happens to have applied to one of my uses of this library, I wish there were an option to turn off the "combining" effect of boolean single-char options into a single dash-option parameter.