CliDirectiveAttribute Class

Specifies a class property that represents a directive which is a syntactic element, that is used on the command line.
C#
[CliDirective]
public bool SomeCliDirective { get; set; }

Currently only bool, string and string[] types are supported for [CliDirective] properties.

Directives:System.CommandLine introduces a syntactic element called a directive. The [diagram] directive is an example. When you include [diagram] after the app's name, System.CommandLine displays a diagram of the parse result instead of invoking the command-line app:

console
dotnet [diagram] build --no-restore --output ./build-output/
       ^-------^
Output:
console
[ dotnet [ build [ --no-restore <True> ] [ --output <./build-output/> ] ] ]
The purpose of directives is to provide cross-cutting functionality that can apply across command-line apps. Because directives are syntactically distinct from the app's own syntax, they can provide functionality that applies across apps.

A directive must conform to the following syntax rules:

  • It's a token on the command line that comes after the app's name but before any subcommands or options.
  • It's enclosed in square brackets.
  • It doesn't contain spaces.

An unrecognized directive is ignored without causing a parsing error.

A directive can include an argument, separated from the directive name by a colon (:):

console
myapp [directive:value]
console
myapp [directive:value1] [directive:value2]

The following directives are built in (can be enabled/disabled via CliSettings): [diagram], [suggest], [env]

Definition

Namespace: DotMake.CommandLine
Assembly: DotMake.CommandLine (in DotMake.CommandLine.dll) Version: 2.5.0
C#
public class CliDirectiveAttribute : Attribute
Inheritance
Object    Attribute    CliDirectiveAttribute

Example

C#
// A root cli command to test directives
// Currently only `bool`, `string` and `string[]` types are supported for `[CliDirective]` properties.

[CliCommand(Description = "A root cli command with directives")]
public class DirectiveCliCommand
{
    [CliDirective]
    public bool Debug { get; set; }

    [CliDirective]
    public string Directive2 { get; set; }

    [CliDirective]
    public string[] Vars { get; set; }

    public void Run(CliContext context)
    {
        if (context.IsEmpty())
            context.ShowHelp();
        else
        {
            Console.WriteLine($"Directive '{nameof(Debug)}' = {StringExtensions.FormatValue(Debug)}");
            Console.WriteLine($"Directive '{nameof(Directive2)}' = {StringExtensions.FormatValue(Directive2)}");
            Console.WriteLine($"Directive '{nameof(Vars)}' = {StringExtensions.FormatValue(Vars)}");
        }
    }
}

Constructors

CliDirectiveAttributeInitializes a new instance of the CliDirectiveAttribute class

Properties

Description Gets or sets the description of the directive. This will be displayed in usage help of the command line application.

This is not used for directives currently, but it's reserved for future use.

Hidden Gets or sets a value indicating whether the directive is hidden.

You might want to support a command, option, or argument, but avoid making it easy to discover. For example, it might be a deprecated or administrative or preview feature. Use the Hidden property to prevent users from discovering such features by using tab completion or help.

This is not used for directives currently, but it's reserved for future use.

Name Gets or sets the name of the directive that will be used on the command line to specify the directive.

If not set (or is empty/whitespace), the name of the property that this attribute is applied to, will be used to generate directive name automatically: These suffixes will be stripped from the property name: RootCliCommandDirective, RootCommandDirective, SubCliCommandDirective, SubCommandDirective, CliCommandDirective, CommandDirective, CliDirective, Directive. Then the name will be converted to kebab-case, for example:

  • If property name is Debug or DebugDirective or DebugCliDirective -> directive name will be debug
  • If property name is NoRestore or NoRestoreDirective or NoRestoreCliDirective -> directive name will be no-restore

Default conventions can be changed via parent command's NameCasingConvention and NamePrefixConvention properties.

See Also