DotMake.CommandLine Namespace

This is the root namespace of this library, it includes the CLI attributes and CLI parser/runner.

The main classes in this namespace are:

  • CliCommandAttribute is the attribute which specifies a class that represents a command which is a specific action that the command line application performs.
  • CliOptionAttribute is the attribute which specifies a class property that represents an option which is a named parameter and a value for that parameter, that is used on the command line.
  • CliArgumentAttribute is the attribute which specifies a class property that represents an argument which is a value that can be passed on the command line to a command or an option.
  • Cli is the class which provides methods for parsing command line input and running an indicated command.

Classes

Cli Provides methods for parsing command line input and running an indicated command.
CliArgumentAttribute Specifies a class property that represents an argument which is a value that can be passed on the command line to a command or an option.
C#
[CliArgument]
public string SomeCliArgument { get; set; }

Note that an argument is required if the decorated property does not have a default value (set via a property initializer), see Required property for details.

Arguments: An argument is a value passed to an option or a command. The following examples show an argument for the verbosity option and an argument for the build command.

console
dotnet tool update dotnet-suggest --verbosity quiet --global
                                              ^---^
console
dotnet build myapp.csproj
             ^----------^
Arguments can have default values that apply if no argument is explicitly provided. For example, many options are implicitly Boolean parameters with a default of true when the option name is in the command line.

CliCommandAsDelegate Represents a definition class generated by the source generator for a command as delegate.
CliCommandAttribute Specifies a class that represents a command which is a specific action that the command line application performs.
C#
[CliCommand]
public class SomeCliCommand
The class that this attribute is applied to,
  • will be a root command if the class is not a nested class and other's Children property and self's Parent property is not set.
  • will be a sub command if the class is a nested class or other's Children property or self's Parent property is set.

Commands: A command in command-line input is a token that specifies an action or defines a group of related actions. For example:

  • In dotnet run, run is a command that specifies an action.
  • In dotnet tool install, install is a command that specifies an action, and tool is a command that specifies a
    group of related commands. There are other tool-related commands, such as tool uninstall, tool list,
    and tool update.

Root commands: The root command is the one that specifies the name of the app's executable. For example, the dotnet command specifies the dotnet.exe executable.

Subcommands: Most command-line apps support subcommands, also known as verbs. For example, the dotnet command has a run subcommand that you invoke by entering dotnet run. Subcommands can have their own subcommands. In dotnet tool install, install is a subcommand of tool.

Inheritance: When you have repeating/common options and arguments for your commands, you can define them once in a base class and then share them by inheriting that base class in other command classes.Interfaces are also supported !

Handler: 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 CliContext parameter in case you need to access it:
  • Run(CliContext context)
  • RunAsync(CliContext context)

We also provide interfaces ICliRun, ICliRunWithReturn, ICliRunWithContext, ICliRunWithContextAndReturn and async versions ICliRunAsync, ICliRunAsyncWithReturn, ICliRunAsyncWithContext, ICliRunAsyncWithContextAndReturn that you can inherit in your command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interfaces can be used to prevent your IDE complain about unused method in class.

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. Other extension methods IsEmptyCommand, ShowValues and ShowHierarchy(Boolean) are also useful.

CliCommandBuilder Represents a command builder generated by the source generator.
CliContext Supports command invocation by providing access to parse results and other services.
CliExtensions Provides extension methods for Cli. These are usually automatically generated by the source generator when current project supports a specific feature through a dependency, e.g. when you add package Microsoft.Extensions.DependencyInjection, dependency injection related extension methods will be available here.
CliHelpBuilder Formats output to be shown to users to describe how to use a command line tool.

HelpBuilder is weirdly designed, i.e. it's hard to derive from that class due to static methods. CliHelpBuilder solves this problem by providing overridable methods, and it also adds color support.

CliHelpBuilderDefault Provides default formatting for help output.
CliOptionAttribute Specifies a class property that represents an option which is a named parameter and a value for that parameter, that is used on the command line.
C#
[CliOption]
public string SomeCliOption { get; set; }

Note that an option is required if the decorated property does not have a default value (set via a property initializer), see Required property for details.

Options: An option is a named parameter that can be passed to a command. The POSIX convention is to prefix the option name with two hyphens (--). The following example shows two options:

console
dotnet tool update dotnet-suggest --verbosity quiet --global
                                  ^---------^       ^------^
As this example illustrates, the value of the option may be explicit (quiet for --verbosity) or implicit (nothing follows --global). Options that have no value specified are typically Boolean parameters that default to true if the option is specified on the command line.

For some Windows command-line apps, you identify an option by using a leading slash (/) with the option name. For example:

console
msbuild /version
        ^------^
Both POSIX and Windows prefix conventions are supported. When manually setting a name (overriding decorated property's name), you should specify the option name including the prefix (e.g. `--option`, `-o`, `-option` or `/option`).

Bundling of single-character options are supported, also known as stacking. Bundled options are single-character option aliases specified together after a single hyphen prefix. For example if you have options "-a", "-b" and "-c", you can bundle them like "-abc". Only the last option can specify an argument. Note that if you have an explicit option named "-abc" then it will win over bundled options.

CliSettings Represents the settings used by the Cli.
CliTheme Represents the theme used by the Cli. These color and formatting option are mainly used by the help output.
CliValidationExtensions Provides extension methods related to validation for Argument and Option.
ParseResultExtensions Provides extension methods for ParseResult.
StringExtensions Provides extension methods for String.

Interfaces

ICliAddCompletions An interface to add custom completions for options and arguments in a command class.
ICliRun An interface to add a command handler with void Run() signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunAsync An interface to add an async command handler with Task RunAsync() signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunAsyncWithContext An interface to add an async command handler with Task RunAsync(CliContext) signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunAsyncWithContextAndReturn An interface to add an async command handler with Task<int> RunAsync(CliContext) signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunAsyncWithReturn An interface to add an async command handler with Task<int> RunAsync() signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunWithContext An interface to add a command handler with void Run(CliContext) signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunWithContextAndReturn An interface to add a command handler with int Run(CliContext) signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunWithReturn An interface to add a command handler with int Run() signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.

Enumerations

CliArgumentArity Defines the arity of an option or argument. The arity refers to the number of values that can be passed on the command line.
CliNameCasingConvention Defines the character casing conventions to use for command, option and argument names.
CliNamePrefixConvention Defines the prefix conventions to use for option names and aliases.
CliValidationRules Defines validation rules for a CLI argument and a CLI option's argument.