Directives

As described in Argument syntax arguments consist of four parts, first of which is for directives:

{directives} {command name} {parameters} {options}

Directives are used to modify the behavior of the whole application. There are few built-in directives, but it's also possible to define custom.

Built-in directives

By default Typin provides 7 directives, i.e., [debug], [preview], [interactive], [!], [>], [.], and [..]. The last 4 directives are only for interactive mode.

In help screen interactive mode only directives and commands are indicated using @.

Directives are used to change the behavior of the whole application, e.g., imagine you have an application that logs everything to a file, then you can add [no-logging] directive to disable logging for a command or whole interactive session.

[debug] aka run debug mode

When troubleshooting issues, you may find it useful to run your app in debug mode. If your application is ran in debug mode (using the [debug] directive), it will wait for debugger to be attached before proceeding. This is useful for debugging apps that were ran outside of the IDE.

> myapp.exe [debug] cmd -o

Attach debugger to PID 3148 to continue.

By default, this directive is disallowed. To add a support of this directive, use AddDirective method in the CliApplicationBuilder:

builder.AddDirective<DebugDirective>();

[preview] aka run preview mode

When troubleshooting issues, you may find it useful to run your app in preview mode. If preview mode is specified (using the [preview] directive), the app will short-circuit by printing consumed command-line arguments as they were parsed. This is useful when troubleshooting issues related to command routing and argument binding.

> myapp.exe [preview] cmd arg1 arg2 -o foo --option bar1 bar2

Parser preview:
cmd <arg1> <arg2> [-o foo] [--option bar1 bar2]

By default this directive is disallowed. To add a support of this directive, use AddDirective method in the CliApplicationBuilder:

builder.AddDirective<PreviewDirective>();

[interactive] aka execute command and start interactive

This directive executs a command, then starts an interactive mode. It is available only when the interactive mode was added to the application with InteractiveModeBuilderExtensions.UseInteractive.

If application runs in interactive mode (using the interactive command or [interactive] directive), it is possible to execute multiple commands in one processes. The application will run in a loop, constantly asking user for command input. This is useful for situations when it is necessary to execute multiple commands (since you don't have to constantly type dotnet ...). Furthermore, application context can be shared, which is useful when you have a db connection or startup takes very long.

[!] aka execute default or scoped command

Normally when application runs in interactive mode, an empty line does nothing; but [!] will override this behavior, executing a root or scoped command. This directive WILL NOT force default command execution when input contains default command parameter values equal to command/subcommand name.

[>] aka scope to command(s)

If application runs in interactive mode, [>] directive followed by command(s) name(s) would scope to the command(s), allowing to omit specified command name(s).

For example, commands:

            > [>] cmd1 sub
    cmd1 sub> list
    cmd1 sub> get
            > [>] cmd1
        cmd1> test
        cmd1> -h

are an equivalent to:

            > cmd1 sub list
            > cmd1 sub get
            > cmd1 test
            > cmd1 -h

[.] aka scope-up

If application runs in interactive mode, [.] directive can be used to remove one command from the scope.

Example:

            > [>] cmd1 sub
    cmd1 sub> list
    cmd1 sub> [.]
        cmd1>

[..] aka scope-reset

If application runs in interactive mode, [..] directive can be used to reset current scope to default (global scope).

Example:

            > [>] cmd1 sub
    cmd1 sub> list
    cmd1 sub> [..]
            >