Class CommandLineApplication

Describes a set of command line arguments, options, and execution behavior. CommandLineApplication can be nested to support subcommands.

Inheritance
System.Object
CommandLineApplication
CommandLineApplication<TModel>
Implements
System.IServiceProvider
Namespace: McMaster.Extensions.CommandLineUtils
Assembly: McMaster.Extensions.CommandLineUtils.dll
Syntax
public class CommandLineApplication : IServiceProvider

Constructors

| Improve this Doc View Source

CommandLineApplication(IHelpTextGenerator, IConsole, String, Boolean)

Initializes a new instance of CommandLineApplication.

Declaration
public CommandLineApplication(IHelpTextGenerator helpTextGenerator, IConsole console, string workingDirectory, bool throwOnUnexpectedArg)
Parameters
Type Name Description
IHelpTextGenerator helpTextGenerator

The help text generator to use.
IConsole console

The console implementation to use.
System.String workingDirectory

The current working directory.
System.Boolean throwOnUnexpectedArg

Initial value for ThrowOnUnexpectedArgument.
| Improve this Doc View Source

CommandLineApplication(IConsole)

Initializes a new instance of CommandLineApplication.

Declaration
public CommandLineApplication(IConsole console)
Parameters
Type Name Description
IConsole console

The console implementation to use.
| Improve this Doc View Source

CommandLineApplication(IConsole, String, Boolean)

Initializes a new instance of CommandLineApplication.

Declaration
public CommandLineApplication(IConsole console, string workingDirectory, bool throwOnUnexpectedArg)
Parameters
Type Name Description
IConsole console

The console implementation to use.
System.String workingDirectory

The current working directory.
System.Boolean throwOnUnexpectedArg

Initial value for ThrowOnUnexpectedArgument.
| Improve this Doc View Source

CommandLineApplication(Boolean)

Initializes a new instance of CommandLineApplication.

Declaration
public CommandLineApplication(bool throwOnUnexpectedArg = true)
Parameters
Type Name Description
System.Boolean throwOnUnexpectedArg

Initial value for ThrowOnUnexpectedArgument.

Properties

| Improve this Doc View Source

AllowArgumentSeparator

Determines if '--' can be used to separate known arguments and options from additional content passed to RemainingArguments.

Declaration
public bool AllowArgumentSeparator { get; set; }
Property Value
Type Description
System.Boolean
| Improve this Doc View Source

Arguments

Required command-line arguments.

Declaration
public List<CommandArgument> Arguments { get; }
Property Value
Type Description
System.Collections.Generic.List<CommandArgument>
| Improve this Doc View Source

Commands

Subcommands.

Declaration
public List<CommandLineApplication> Commands { get; }
Property Value
Type Description
System.Collections.Generic.List<CommandLineApplication>
| Improve this Doc View Source

Conventions

Gets a builder that can be used to apply conventions to

Declaration
public IConventionBuilder Conventions { get; }
Property Value
Type Description
IConventionBuilder
| Improve this Doc View Source

Description

A description of the command.

Declaration
public string Description { get; set; }
Property Value
Type Description
System.String
| Improve this Doc View Source

Error

The writer used to display generated error messages.

Declaration
public TextWriter Error { get; set; }
Property Value
Type Description
System.IO.TextWriter
| Improve this Doc View Source

ExtendedHelpText

Additional text that appears at the bottom of generated help text.

Declaration
public string ExtendedHelpText { get; set; }
Property Value
Type Description
System.String
| Improve this Doc View Source

FullName

The full name of the command to show in the help text.

Declaration
public string FullName { get; set; }
Property Value
Type Description
System.String
| Improve this Doc View Source

HelpTextGenerator

The help text generator to use.

Declaration
public IHelpTextGenerator HelpTextGenerator { get; set; }
Property Value
Type Description
IHelpTextGenerator
| Improve this Doc View Source

Invoke

The action to call when this command is matched and IsShowingInformation is false.

Declaration
public Func<int> Invoke { get; set; }
Property Value
Type Description
System.Func<System.Int32>
| Improve this Doc View Source

IsShowingInformation

True when OptionHelp or OptionVersion was matched.

Declaration
public bool IsShowingInformation { get; protected set; }
Property Value
Type Description
System.Boolean
| Improve this Doc View Source

LongVersionGetter

The long-form of the version to display in generated help text.

Declaration
public Func<string> LongVersionGetter { get; set; }
Property Value
Type Description
System.Func<System.String>
| Improve this Doc View Source

Name

The short name of the command. When this is a subcommand, it is the name of the word used to invoke the subcommand.

Declaration
public string Name { get; set; }
Property Value
Type Description
System.String
| Improve this Doc View Source

OptionHelp

The option used to determine if help text should be displayed. This is set by calling HelpOption(String).

Declaration
public CommandOption OptionHelp { get; }
Property Value
Type Description
CommandOption
| Improve this Doc View Source

Options

Available command-line options on this command. Use GetOptions() to get all available options, which may include inherited options.

Declaration
public List<CommandOption> Options { get; }
Property Value
Type Description
System.Collections.Generic.List<CommandOption>
| Improve this Doc View Source

OptionsComparison

The way arguments and options are matched.

Declaration
public StringComparison OptionsComparison { get; set; }
Property Value
Type Description
System.StringComparison
| Improve this Doc View Source

OptionVersion

The options used to determine if the command version should be displayed. This is set by calling VersionOption(String, Func<String>, Func<String>).

Declaration
public CommandOption OptionVersion { get; }
Property Value
Type Description
CommandOption
| Improve this Doc View Source

Out

The writer used to display generated help text.

Declaration
public TextWriter Out { get; set; }
Property Value
Type Description
System.IO.TextWriter
| Improve this Doc View Source

Parent

Defaults to null. A link to the parent command if this is instance is a subcommand.

Declaration
public CommandLineApplication Parent { get; set; }
Property Value
Type Description
CommandLineApplication
| Improve this Doc View Source

RemainingArguments

When initialized with ThrowOnUnexpectedArgument to false, this will contain any unrecognized arguments.

Declaration
public List<string> RemainingArguments { get; }
Property Value
Type Description
System.Collections.Generic.List<System.String>
| Improve this Doc View Source

ResponseFileHandling

When enabled, the parser will treat any arguments beginning with &apos;@' as a file path to a response file. A response file contains additional arguments that will be treated as if they were passed in on the command line.

Defaults to Disabled.

Nested response false are not supported.

Declaration
public ResponseFileHandling ResponseFileHandling { get; set; }
Property Value
Type Description
ResponseFileHandling
| Improve this Doc View Source

ShortVersionGetter

The short-form of the version to display in generated help text.

Declaration
public Func<string> ShortVersionGetter { get; set; }
Property Value
Type Description
System.Func<System.String>
| Improve this Doc View Source

ShowInHelpText

Determines if this command appears in generated help text.

Declaration
public bool ShowInHelpText { get; set; }
Property Value
Type Description
System.Boolean
| Improve this Doc View Source

ThrowOnUnexpectedArgument

Indicates whether the parser should throw an exception when it runs into an unexpected argument. If this field is set to false, the parser will stop parsing when it sees an unexpected argument, and all remaining arguments, including the first unexpected argument, will be stored in RemainingArguments property.

Declaration
public bool ThrowOnUnexpectedArgument { get; set; }
Property Value
Type Description
System.Boolean
| Improve this Doc View Source

ValidationErrorHandler

The action to call when the command executes, but there was an error validation options or arguments. The action can return a new validation result.

Declaration
public Func<ValidationResult, int> ValidationErrorHandler { get; set; }
Property Value
Type Description
System.Func<System.ComponentModel.DataAnnotations.ValidationResult, System.Int32>
| Improve this Doc View Source

Validators

A collection of validators that execute before invoking OnExecute(Func<Int32>). When validation fails, ValidationErrorHandler is invoked.

Declaration
public ICollection<ICommandValidator> Validators { get; }
Property Value
Type Description
System.Collections.Generic.ICollection<ICommandValidator>
| Improve this Doc View Source

ValueParsers

Gets the default value parser provider.

The value parsers control how argument values are converted from strings to other types. Additional value parsers can be added so that domain specific types can converted. In-built value parsers can also be replaced for precise control of all type conversion.

Value parsers are currently only used by the Attribute API.

Declaration
public ValueParserProvider ValueParsers { get; }
Property Value
Type Description
ValueParserProvider
| Improve this Doc View Source

WorkingDirectory

Defines the working directory of the application. Defaults to System.IO.Directory.GetCurrentDirectory.

This will be used as the base path for opening response files when ResponseFileHandling is true.

Declaration
public string WorkingDirectory { get; }
Property Value
Type Description
System.String

Methods

| Improve this Doc View Source

Argument(String, String, Action<CommandArgument>, Boolean)

Adds a command line argument.

Declaration
public CommandArgument Argument(string name, string description, Action<CommandArgument> configuration, bool multipleValues = false)
Parameters
Type Name Description
System.String name
System.String description
System.Action<CommandArgument> configuration
System.Boolean multipleValues
Returns
Type Description
CommandArgument
| Improve this Doc View Source

Argument(String, String, Boolean)

Adds a command line argument

Declaration
public CommandArgument Argument(string name, string description, bool multipleValues = false)
Parameters
Type Name Description
System.String name
System.String description
System.Boolean multipleValues
Returns
Type Description
CommandArgument
| Improve this Doc View Source

Argument<T>(String, String, Action<CommandArgument>, Boolean)

Adds a command line argument with values that should be parsable into T.

Declaration
public CommandArgument<T> Argument<T>(string name, string description, Action<CommandArgument> configuration, bool multipleValues = false)
Parameters
Type Name Description
System.String name
System.String description
System.Action<CommandArgument> configuration
System.Boolean multipleValues
Returns
Type Description
CommandArgument<T>
Type Parameters
Name Description
T

The type of the values on the option
| Improve this Doc View Source

Command(String, Action<CommandLineApplication>, Boolean)

Adds a subcommand.

Declaration
public CommandLineApplication Command(string name, Action<CommandLineApplication> configuration, bool throwOnUnexpectedArg = true)
Parameters
Type Name Description
System.String name

The word used to invoke the subcommand.
System.Action<CommandLineApplication> configuration
System.Boolean throwOnUnexpectedArg
Returns
Type Description
CommandLineApplication
| Improve this Doc View Source

Command<TModel>(String, Action<CommandLineApplication<TModel>>, Boolean)

Adds a subcommand with model of type TModel.

Declaration
public CommandLineApplication<TModel> Command<TModel>(string name, Action<CommandLineApplication<TModel>> configuration, bool throwOnUnexpectedArg = true)
    where TModel : class
Parameters
Type Name Description
System.String name

The word used to invoke the subcommand.
System.Action<CommandLineApplication<TModel>> configuration
System.Boolean throwOnUnexpectedArg
Returns
Type Description
CommandLineApplication<TModel>
Type Parameters
Name Description
TModel

The model type of the subcommand.
| Improve this Doc View Source

Execute(String[])

Parses an array of strings using Parse(String[]).

If OptionHelp was matched, the generated help text is displayed in command line output.

If OptionVersion was matched, the generated version info is displayed in command line output.

If there were any validation errors produced from McMaster.Extensions.CommandLineUtils.CommandLineApplication.GetValidationResult, ValidationErrorHandler is invoked.

If the parse result matches this command, Invoke will be invoked.

Declaration
public int Execute(params string[] args)
Parameters
Type Name Description
System.String[] args
Returns
Type Description
System.Int32

The return code from Invoke.
| Improve this Doc View Source

Execute<TApp>(CommandLineContext)

Creates an instance of TApp, matching Arguments to all attributes on the type, and then invoking a method named "OnExecute" or "OnExecuteAsync" if it exists. See OptionAttribute, ArgumentAttribute, HelpOptionAttribute, and VersionOptionAttribute.

Declaration
public static int Execute<TApp>(CommandLineContext context)
    where TApp : class
Parameters
Type Name Description
CommandLineContext context

The execution context.
Returns
Type Description
System.Int32

The process exit code
Type Parameters
Name Description
TApp

A type that should be bound to the arguments.
Exceptions
Type Condition
System.InvalidOperationException

Thrown when attributes are incorrectly configured.
| Improve this Doc View Source

Execute<TApp>(IConsole, String[])

Creates an instance of TApp, matching args to all attributes on the type, and then invoking a method named "OnExecute" or "OnExecuteAsync" if it exists. See OptionAttribute, ArgumentAttribute, HelpOptionAttribute, and VersionOptionAttribute.

Declaration
public static int Execute<TApp>(IConsole console, params string[] args)
    where TApp : class
Parameters
Type Name Description
IConsole console

The console to use
System.String[] args

The arguments
Returns
Type Description
System.Int32

The process exit code
Type Parameters
Name Description
TApp

A type that should be bound to the arguments.
Exceptions
Type Condition
System.InvalidOperationException

Thrown when attributes are incorrectly configured.
| Improve this Doc View Source

Execute<TApp>(String[])

Creates an instance of TApp, matching args to all attributes on the type, and then invoking a method named "OnExecute" or "OnExecuteAsync" if it exists. See OptionAttribute, ArgumentAttribute, HelpOptionAttribute, and VersionOptionAttribute.

Declaration
public static int Execute<TApp>(params string[] args)
    where TApp : class
Parameters
Type Name Description
System.String[] args

The arguments
Returns
Type Description
System.Int32

The process exit code
Type Parameters
Name Description
TApp

A type that should be bound to the arguments.
Exceptions
Type Condition
System.InvalidOperationException

Thrown when attributes are incorrectly configured.
| Improve this Doc View Source

ExecuteAsync<TApp>(CommandLineContext)

Creates an instance of TApp, matching Arguments to all attributes on the type, and then invoking a method named "OnExecute" or "OnExecuteAsync" if it exists. See OptionAttribute, ArgumentAttribute, HelpOptionAttribute, and VersionOptionAttribute.

Declaration
public static Task<int> ExecuteAsync<TApp>(CommandLineContext context)
    where TApp : class
Parameters
Type Name Description
CommandLineContext context

The execution context.
Returns
Type Description
System.Threading.Tasks.Task<System.Int32>

The process exit code
Type Parameters
Name Description
TApp

A type that should be bound to the arguments.
Exceptions
Type Condition
System.InvalidOperationException

Thrown when attributes are incorrectly configured.
| Improve this Doc View Source

ExecuteAsync<TApp>(IConsole, String[])

Creates an instance of TApp, matching args to all attributes on the type, and then invoking a method named "OnExecute" or "OnExecuteAsync" if it exists. See OptionAttribute, ArgumentAttribute, HelpOptionAttribute, and VersionOptionAttribute.

Declaration
public static Task<int> ExecuteAsync<TApp>(IConsole console, params string[] args)
    where TApp : class
Parameters
Type Name Description
IConsole console

The console to use
System.String[] args

The arguments
Returns
Type Description
System.Threading.Tasks.Task<System.Int32>

The process exit code
Type Parameters
Name Description
TApp

A type that should be bound to the arguments.
Exceptions
Type Condition
System.InvalidOperationException

Thrown when attributes are incorrectly configured.
| Improve this Doc View Source

ExecuteAsync<TApp>(String[])

Creates an instance of TApp, matching args to all attributes on the type, and then invoking a method named "OnExecute" or "OnExecuteAsync" if it exists. See OptionAttribute, ArgumentAttribute, HelpOptionAttribute, and VersionOptionAttribute.

Declaration
public static Task<int> ExecuteAsync<TApp>(params string[] args)
    where TApp : class
Parameters
Type Name Description
System.String[] args

The arguments
Returns
Type Description
System.Threading.Tasks.Task<System.Int32>

The process exit code
Type Parameters
Name Description
TApp

A type that should be bound to the arguments.
Exceptions
Type Condition
System.InvalidOperationException

Thrown when attributes are incorrectly configured.
| Improve this Doc View Source

GetFullNameAndVersion()

Gets FullName and ShortVersionGetter.

Declaration
public virtual string GetFullNameAndVersion()
Returns
Type Description
System.String
| Improve this Doc View Source

GetHelpText()

Produces help text describing command usage.

Declaration
public virtual string GetHelpText()
Returns
Type Description
System.String

The help text.
| Improve this Doc View Source

GetHelpText(String)

This method has been marked as obsolete and will be removed in a future version. The recommended replacement is GetHelpText()

Declaration
[Obsolete("This method has been marked as obsolete and will be removed in a future version.The recommended replacement is GetHelpText()")]
public virtual string GetHelpText(string commandName = null)
Parameters
Type Name Description
System.String commandName
Returns
Type Description
System.String
| Improve this Doc View Source

GetOptions()

Gets all command line options available to this command, including any inherited options.

Declaration
public IEnumerable<CommandOption> GetOptions()
Returns
Type Description
System.Collections.Generic.IEnumerable<CommandOption>

Command line options.
| Improve this Doc View Source

GetVersionText()

Produces text describing version of the command.

Declaration
public virtual string GetVersionText()
Returns
Type Description
System.String

The version text.
| Improve this Doc View Source

HandleParseResult(ParseResult)

Handle the result of parsing command line arguments.

Declaration
protected virtual void HandleParseResult(ParseResult parseResult)
Parameters
Type Name Description
ParseResult parseResult

The parse result.
| Improve this Doc View Source

HelpOption(String)

Helper method that adds a help option.

Declaration
public CommandOption HelpOption(string template)
Parameters
Type Name Description
System.String template
Returns
Type Description
CommandOption
| Improve this Doc View Source

HelpOption(String, Boolean)

Helper method that adds a help option.

Declaration
public CommandOption HelpOption(string template, bool inherited)
Parameters
Type Name Description
System.String template
System.Boolean inherited
Returns
Type Description
CommandOption
| Improve this Doc View Source

OnExecute(Func<Int32>)

Defines a callback for when this command is invoked.

Declaration
public void OnExecute(Func<int> invoke)
Parameters
Type Name Description
System.Func<System.Int32> invoke
| Improve this Doc View Source

OnExecute(Func<Task<Int32>>)

Defines an asynchronous callback.

Declaration
public void OnExecute(Func<Task<int>> invoke)
Parameters
Type Name Description
System.Func<System.Threading.Tasks.Task<System.Int32>> invoke
| Improve this Doc View Source

OnParsingComplete(Action<ParseResult>)

Adds an action to be invoked when all command line arguments have been parsed and validated.

Declaration
public void OnParsingComplete(Action<ParseResult> action)
Parameters
Type Name Description
System.Action<ParseResult> action

The action to be invoked
| Improve this Doc View Source

Option(String, String, CommandOptionType)

Adds a command-line option.

Declaration
public CommandOption Option(string template, string description, CommandOptionType optionType)
Parameters
Type Name Description
System.String template
System.String description
CommandOptionType optionType
Returns
Type Description
CommandOption
| Improve this Doc View Source

Option(String, String, CommandOptionType, Action<CommandOption>)

Adds a command-line option.

Declaration
public CommandOption Option(string template, string description, CommandOptionType optionType, Action<CommandOption> configuration)
Parameters
Type Name Description
System.String template
System.String description
CommandOptionType optionType
System.Action<CommandOption> configuration
Returns
Type Description
CommandOption
| Improve this Doc View Source

Option(String, String, CommandOptionType, Action<CommandOption>, Boolean)

Adds a command line option.

Declaration
public CommandOption Option(string template, string description, CommandOptionType optionType, Action<CommandOption> configuration, bool inherited)
Parameters
Type Name Description
System.String template
System.String description
CommandOptionType optionType
System.Action<CommandOption> configuration
System.Boolean inherited
Returns
Type Description
CommandOption
| Improve this Doc View Source

Option(String, String, CommandOptionType, Boolean)

Adds a command-line option.

Declaration
public CommandOption Option(string template, string description, CommandOptionType optionType, bool inherited)
Parameters
Type Name Description
System.String template
System.String description
CommandOptionType optionType
System.Boolean inherited
Returns
Type Description
CommandOption
| Improve this Doc View Source

Option<T>(String, String, CommandOptionType, Action<CommandOption>, Boolean)

Adds a command line option with values that should be parsable into T.

Declaration
public CommandOption<T> Option<T>(string template, string description, CommandOptionType optionType, Action<CommandOption> configuration, bool inherited)
Parameters
Type Name Description
System.String template
System.String description
CommandOptionType optionType
System.Action<CommandOption> configuration
System.Boolean inherited
Returns
Type Description
CommandOption<T>

The option
Type Parameters
Name Description
T

The type of the values on the option
| Improve this Doc View Source

Parse(String[])

Parses an array of strings, matching them against Options, Arguments, and Commands.

Declaration
public ParseResult Parse(params string[] args)
Parameters
Type Name Description
System.String[] args

Command line arguments.
Returns
Type Description
ParseResult

The result of parsing.
| Improve this Doc View Source

ShowHelp()

Show full help.

Declaration
public void ShowHelp()
| Improve this Doc View Source

ShowHelp(String)

This method has been marked as obsolete and will be removed in a future version. The recommended replacement is ShowHelp().

Declaration
[Obsolete("This method has been marked as obsolete and will be removed in a future version.The recommended replacement is ShowHelp()")]
public void ShowHelp(string commandName = null)
Parameters
Type Name Description
System.String commandName

The subcommand for which to show help. Leave null to show for the current command.
| Improve this Doc View Source

ShowHint()

Show short hint that reminds users to use help option.

Declaration
public virtual void ShowHint()
| Improve this Doc View Source

ShowRootCommandFullNameAndVersion()

Traverses up Parent and displays the result of GetFullNameAndVersion().

Declaration
public void ShowRootCommandFullNameAndVersion()
| Improve this Doc View Source

ShowVersion()

Displays version information that includes FullName and LongVersionGetter.

Declaration
public void ShowVersion()
| Improve this Doc View Source

VersionOption(String, Func<String>, Func<String>)

Helper method that adds a version option.

Declaration
public CommandOption VersionOption(string template, Func<string> shortFormVersionGetter, Func<string> longFormVersionGetter = null)
Parameters
Type Name Description
System.String template
System.Func<System.String> shortFormVersionGetter
System.Func<System.String> longFormVersionGetter
Returns
Type Description
CommandOption
| Improve this Doc View Source

VersionOption(String, String, String)

Helper method that adds a version option from known versions strings.

Declaration
public CommandOption VersionOption(string template, string shortFormVersion, string longFormVersion = null)
Parameters
Type Name Description
System.String template
System.String shortFormVersion
System.String longFormVersion
Returns
Type Description
CommandOption

Explicit Interface Implementations

| Improve this Doc View Source

IServiceProvider.GetService(Type)

Declaration
object IServiceProvider.GetService(Type serviceType)
Parameters
Type Name Description
System.Type serviceType
Returns
Type Description
System.Object

Implements

System.IServiceProvider

Extension Methods