Building a Command-Line (CLI) app using System.CommandLine library in C# and .NET

System.CommandLine is a very good parser but you need a lot of boilerplate code to get going and the API is hard to discover.
This becomes complicated to newcomers and also you would have a lot of ugly code in your Program.cs to maintain.
What if you had an easy class-based layer combined with a good parser?

DotMake.CommandLine is a library which provides declarative syntax for
System.CommandLine
via attributes for easy, fast, strongly-typed (no reflection) usage. The library includes includes a source generator
which automagically converts your classes to CLI commands and properties to CLI options or CLI arguments.
Supports
trimming,
AOT compilation and
dependency injection!

Getting started

Install the library to your console app project with NuGet.

In your project directory, via dotnet cli:

dotnet add package DotMake.CommandLine

or in Visual Studio Package Manager Console:

PM> Install-Package DotMake.CommandLine

Prerequisites

• .NET 6.0 and later project or .NET Standard 2.0 and later project (note that .NET Framework 4.7.2+ can reference netstandard2.0 libraries). If your target framework is below net5.0, you also need <LangVersion>9.0</LangVersion> tag (minimum) in your .csproj file.
• Visual Studio 2022 v17.3+ or .NET SDK 6.0.407+ (our incremental source generator requires performance features added first in these versions).
• Usually a console app project but you can also use a class library project which will be consumed later.

Usage

Delegate-based model

Create a CLI App with DotMake.Commandline in seconds!
In Program.cs, add this simple code:

Cli.Run(([CliArgument]string argument1, bool option1) =>
{
    Console.WriteLine($@"Value for {nameof(argument1)} parameter is '{argument1}'");
    Console.WriteLine($@"Value for {nameof(option1)} parameter is '{option1}'");
});

And that's it! You now have a fully working command-line app.

Summary

• Pass a delegate (a parenthesized lambda expression or a method reference) which has parameters that represent your options and arguments, to Cli.Run.
• A parameter is by default considered as a CLI option but you can;
  • Mark a parameter with CliArgument attribute to make it a CLI argument and specify settings (see CliArgumentAttribute docs for more info).
  • Mark a parameter with CliOption attribute to specify CLI option settings (see CliOptionAttribute docs for more info).
  • Mark the delegate itself with CliCommand attribute to specify CLI command settings (see CliCommandAttribute docs for more info).
  • Note that for being able to mark a parameter with an attribute in an anonymous lambda function, if your target framework is below net6.0, you also need <LangVersion>10.0</LangVersion> tag (minimum) in your .csproj file.
• Set a default value for a parameter if you want it to be optional (not required to be specified on the command-line).
• Your delegate can be async.
• Your delegate can have a return type void or int and if it's async Task or Task<int>.

Class-based model

While delegate-based model above is useful for simple apps, for more complex apps, you can use the class-based model.
Create a simple class like this:

using System;
using DotMake.CommandLine;

[CliCommand(Description = "A root cli command")]
public class RootCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; }

    public void Run()
    {
        Console.WriteLine($@"Handler for '{GetType().FullName}' is run:");
        Console.WriteLine($@"Value for {nameof(Option1)} property is '{Option1}'");
        Console.WriteLine($@"Value for {nameof(Argument1)} property is '{Argument1}'");
        Console.WriteLine();
    }
}

In Program.cs, add this single line:

Cli.Run<RootCliCommand>(args);

And that's it! You now have a fully working command-line app. You just specify the name of your class which represents your root command to Cli.Run<> method and everything is wired.

args is the string array typically passed to a program. This is usually
the special variable args available in Program.cs (new style with top-level statements)
or the string array passed to the program's Main method (old style).
We also have method signatures which does not require args,
for example you can also call Cli.Run<RootCliCommand>() and in that case args will be retrieved automatically from the current process via Cli.GetArgs().

If you want to go async, just use this:

await Cli.RunAsync<RootCliCommand>(args);

To handle exceptions, you just use a try-catch block:

try
{
    Cli.Run<RootCliCommand>(args);
}
catch (Exception e)
{
    Console.WriteLine(@"Exception in main: {0}", e.Message);
}

System.CommandLine, by default overtakes your exceptions that are thrown in command handlers (even if you don't set an exception handler explicitly) but DotMake.CommandLine, by default allows the exceptions to pass through. However if you wish, you can easily use an exception handler by using configureBuilder delegate parameter like this:

Cli.Run<RootCliCommand>(args, builder => 
    builder.UseExceptionHandler((e, context) => Console.WriteLine(@"Exception in command handler: {0}", e.Message))
);

If you need to simply parse the command-line arguments without invocation, use this:

var rootCliCommand = Cli.Parse<RootCliCommand>(args);

If you need to examine the parse result, such as errors:

var rootCliCommand = Cli.Parse<RootCliCommand>(args, out var parseResult);
if (parseResult.Errors.Count > 0)
{

}

Summary

• Mark the class with CliCommand attribute to make it a CLI command (see CliCommandAttribute docs for more info).
• Mark a property with CliOption attribute to make it a CLI option (see CliOptionAttribute docs for more info).
• Mark a property with CliArgument attribute to make it a CLI argument (see CliArgumentAttribute docs for more info).
• Add a method with name Run or RunAsync to make it the handler for the CLI command. The method can have one of the following signatures:

-

   void Run()

-

   int Run()

-

   async Task RunAsync()

-

   async Task<int> RunAsync()

Optionally the method signature can have a System.CommandLine.Invocation.InvocationContext parameter in case you need to access it:

-

   Run(InvocationContext context)

-

   RunAsync(InvocationContext context)

The signatures which return int value, sets the ExitCode of the app.
If no handler method is provided, then by default it will show help for the command.
This can be also controlled manually by extension method ShowHelp in InvocationContext.
Other extension methods IsEmptyCommand and ShowValues are also useful.

• Call Cli.Run<> orCli.RunAsync<> method with your class name to run your CLI app (see Cli docs for more info).

Additional documentation

• DotMake Command-Line API docs
• Command-line syntax overview for System.CommandLine