CliDirectiveAttribute Class

Definition

Namespace

DotMake.CommandLine

Assembly

DotMake.CommandLine.dll

Specifies a class property that represents a directive which is a syntactic element, that is used on the command line.

[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:

dotnet [diagram] build --no-restore --output ./build-output/
       ^-------^

Output:

[ 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 (:):

myapp [directive:value]

myapp [directive:value1] [directive:value2]

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

[AttributeUsage(AttributeTargets.Property|AttributeTargets.Parameter)]
public class CliDirectiveAttribute : Attribute

Inheritance

object

Attribute

CliDirectiveAttribute

Examples

// 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)}' = {CliStringUtil.FormatValue(Debug)}");
            Console.WriteLine($"Directive '{nameof(Directive2)}' = {CliStringUtil.FormatValue(Directive2)}");
            Console.WriteLine($"Directive '{nameof(Vars)}' = {CliStringUtil.FormatValue(Vars)}");
        }
    }

    [CliCommand(Description = "A sub cli command with directives")]
    public class Level1CliCommand
    {
        public DirectiveCliCommand Parent { get; set; }

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

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.
Order	Gets or sets the order of the directive. The order is used when printing the symbols in help and for arguments additionally effects the parsing order. When not set (or is 0 - the default value), the symbol order is determined based on source code ordering.