Help and error pipeline reference
This page lists the console, help, and command-line error types used by AnyCLI.
Console abstractions
| Type | Purpose |
|---|---|
IConsole |
Standard input, output, and error for a command. |
IConsoleWriter |
Standard output and error without input. |
IConsoleOutputWriter |
Exposes Output as an IOutputWriter. |
IConsoleErrorWriter |
Exposes Error as an IOutputWriter. |
IOutputWriter |
Write-only output: Write, WriteLine(), and WriteLine(string?). |
IInputReader |
Reads a line from standard input with a cancellation token. |
CommandContext.Console is an IConsole. HelpContext.Console and CommandErrorContext.Console expose the narrower writer interfaces they need.
Help pipeline
Types
| Type | Purpose |
|---|---|
IHelpProvider |
Renders root help and command help. |
DefaultHelpProvider |
The built-in plain-text help renderer. |
IHelpTextProvider |
Supplies headings, usage placeholders, and descriptions. |
LocalizedHelpTextProvider |
The built-in resource-based text provider. |
HelpContext |
Shared help data: app name, console, and global options. |
RootHelpContext |
Root help data, including top-level commands. |
CommandHelpContext |
Command help data, including the selected command or group. |
HelpProviderContext |
Inputs for creating a help provider: service provider and text provider. |
HelpDescriptionContext |
Inputs for resolving a command, option, or argument description. |
HelpText |
Literal text, a resource key, or both. |
ResourceDescriptionAttribute |
Associates a parameter property with a resource key. |
Help configuration
| Method | Effect |
|---|---|
UseProvider<TProvider>() |
Replaces the help renderer. |
UseProvider(Func<HelpProviderContext, IHelpProvider>) |
Creates the renderer with access to services and the text provider. |
UseTextProvider<TProvider>() |
Replaces the help text provider. |
UseLocalizedTextProvider(params ResourceManager[]) |
Uses LocalizedHelpTextProvider with description resources. |
UseLocalizedTextProvider(Func<IServiceProvider?, IEnumerable<ResourceManager>>) |
Creates description resources through a factory. |
UseLocalizedTextProvider(string baseName, Assembly assembly) |
Creates a ResourceManager from a base name and assembly. |
When no help provider is configured, DefaultHelpProvider is used. When no help text provider is configured, LocalizedHelpTextProvider is used.
A help provider may be resolved from DI when a service provider is configured. Otherwise it needs a public parameterless constructor.
Resource keys
HelpTextResourceKeys defines the keys used for built-in headings and placeholders:
UsageDescriptionCommandsArgumentsOptionsOptionsPlaceholderCommandPlaceholderHelpOptionDescriptionVersionOptionDescription
Error pipeline
Invalid command-line input is represented by CommandError and thrown as CommandErrorException. ConsoleApp.RunAsync catches that exception and delegates it to an ICommandErrorHandler.
Structured errors
| Error | Data |
|---|---|
NoCommandSpecifiedError |
No additional data. |
UnknownCommandError |
AttemptedCommandPath, AvailableCommands |
MissingSubcommandError |
CommandPath, AvailableCommands |
UnknownOptionError |
OptionName |
MalformedOptionError |
Token |
OptionRequiresSeparateValueError |
OptionName |
MissingOptionValueError |
OptionName |
RepeatedOptionError |
OptionName |
MissingRequiredOptionError |
OptionName, IsGlobal |
MissingRequiredArgumentError |
ArgumentName |
UnexpectedArgumentError |
Value |
TooFewVariadicValuesError |
ArgumentName, Minimum, Actual |
TooManyVariadicValuesError |
ArgumentName, Maximum, Actual |
InvalidParameterValueError |
ParameterName, Value, TargetType, Source |
ParameterSource identifies whether an invalid value came from an argument, option, or global option.
Error types
| Type | Purpose |
|---|---|
CommandError |
Base type for structured command-line errors. |
CommandErrorException |
Carries a CommandError and command path. |
CommandErrorContext |
App name, command path, structured error, and error console. |
ICommandErrorHandler |
Handles the command-line error response. |
DefaultCommandErrorHandler |
Combines a message provider and writer. |
ICommandErrorMessageProvider |
Produces the plain-text message. |
LocalizedCommandErrorMessageProvider |
Built-in resource-based message provider. |
ICommandErrorWriter |
Writes the message to standard error. |
PlainCommandErrorWriter |
Built-in unstyled writer. |
Error configuration
| Method | Effect |
|---|---|
UseHandler<THandler>() |
Replaces the error handler. |
UseMessageProvider<TProvider>() |
Replaces the message provider. |
UseLocalizedMessageProvider(...) |
Uses LocalizedCommandErrorMessageProvider with resources. |
UseWriter<TWriter>() |
Replaces the error writer. |
UseWriter(Func<IServiceProvider?, ICommandErrorWriter>) |
Creates the writer with access to services. |
UseExitCode(int) |
Sets a fixed command-line error exit code. |
UseExitCode<TExitCode>(TExitCode) |
Sets a fixed exit code from an enum. |
UseExitCode(Func<CommandErrorContext, int>) |
Derives the exit code from the error context. |
The default exit code for command-line errors is 2.
CommandErrorResourceKeys defines the keys used by the built-in localized error messages.
Scope
The error pipeline handles command-line input errors. Exceptions thrown by command bodies are not converted into CommandError values. Cancellation is also separate and propagates from RunAsync.