Command Line Parser for C#

I recently came across Command Line Parser. It's a C# library (available on NuGet) that takes care of the boilerplate code often associated with parsing, validating and using options specified as command line arguments.

It uses common conventions for how it assumes the options will appear (similar to C's getopt function).

The GitHub page has pretty comprehensive documentation on how to use it, but I thought I'd share here briefly how it works.

Simple options

Suppose we're creating an application which describes a file in terms of its properties (size, file type etc), and suppose the desired command-line options are:

• <file path> (required)
• -d or --detailed (if present gives as much information as it can find, otherwise gives the most commonly-wanted info)
• -o <file path> or --output <file path> (specifies a file to output the file properties to)

Then we create an Options class with properties for all the possible command-line options, decorated with attributes detailing the expected usage:

class Options
{
    [Value(0)]
    public string FilePath { get; set; }

    [Option('d', "detailed")]
    public bool Detailed { get; set; }

    [Option('o', "output")]
    public string Output { get; set; }
}

The Value attribute defines a positional argument, and the Option attribute defines an argument that is passed in by name.

Then in the Main method, it's as simple as doing the following:

class Program
{
    static void Main(string[] args)
    {
        CommandLine.Parser.Default.ParseArguments<Options>(args)
            .WithParsed<Options>(o => {
                // parsing successful; go ahead and run the app
            })
            .WithNotParsed<Options>(e => {
                // parsing unsuccessful; deal with parsing errors
            });
    }
}

The Options object o will be populated with the parsed options, which you can then use to control the behaviour of your app.

Verbs

It also supports the idea of verbs. For example, Git has a number of different actions you can take (git clone, git commit, git pull etc) which each have their own sets of options.

With Command Line Parser, you create a separate options class for each verb:

[Verb("clone")]
class CloneOptions {
    // ...
}

[Verb("commit")]
class CommitOptions {
    // ...
}

[Verb("pull")]
class PullOptions {
    // ...
}

And then in your Main method you define what to do for each verb, as well as how to handle parsing errors:

class Program
{
    static int Main(string[] args)
    {
        return CommandLine.Parser.Default
            .ParseArguments<AddOptions, CommitOptions, CloneOptions>(args)
            .MapResult(
                (CloneOptions o) => {
                    // clone
                },
                (CommitOptions o) => {
                    // commit
                },
                (PullOptions o) => {
                    // pull
                },
                e => 1);
    }
}

Customisation

The examples I've given here use CommandLine.Parser.Default, but it's possible to customise the parser in a number of different ways. For example, you can set the culture for arguments to be parsed in, or whether to parse values case-sensitively or not.

Help text

One of the really nice things about Command Line Parser is that it can generate help text for your application. All you need to do is add the HelpText property to the attributes, and then if someone passes in the --help switch they'll get the full help text.

For example, our Options class from before could be changed to:

class Options
{
    [Value(0, HelpText = "The file to display information for.")]
    public string FilePath { get; set; }

    [Option('d', "detailed",
        HelpText = "Whether to output detailed information about the file.")]
    public bool Detailed { get; set; }

    [Option('o', "output",
        HelpText = "If specified, a file to output the results to.")]
    public string Output { get; set; }
}

Then running the app with the --help switch gives us the following output:

  -d, --detailed    Whether to output detailed information about the file.

  -o, --output      If specified, a file to output the results to.

  --help            Display this help screen.

  --version         Display version information.

  value pos. 0      The file to display information for.

This text is automatically output if parsing fails.

You can also add an overall summary for your application, along with some examples of how to use it. These are added to the help screen.

Conclusion

Command Line Parser takes away the boilerplate code associated with parsing command-line options. I can see that this would be useful on a small app with a couple of options right up to a hugely complex app with dozens of options.

I've recently used it on a football match simulation app, which may be the subject of a future blog post ...