Interceptors reference
Interceptors wrap command execution after command-line parsing and required-value validation succeed, before the command result is returned.
Interfaces
| Interface | Delegate |
|---|---|
ICommandInterceptor |
Func<CancellationToken, Task<int>> |
ICommandInterceptor<TGlobalOptions> |
Func<CancellationToken, Task<int>> |
ICommandInterceptorWithExitCode<TExitCode> |
Func<CancellationToken, Task<TExitCode>> |
ICommandInterceptorWithExitCode<TGlobalOptions, TExitCode> |
Func<CancellationToken, Task<TExitCode>> |
ICommandInterceptor<TGlobalOptions> receives CommandInterceptorContext<TGlobalOptions> and requires the application to configure global options. ICommandInterceptorWithExitCode<TExitCode> converts the enum result to the integer process exit code through the framework bridge. ICommandInterceptorWithExitCode<TGlobalOptions, TExitCode> combines both: it receives typed global options and a typed exit-code delegate.
Interceptor context
CommandInterceptorContext inherits from CommandContext and adds:
| Property | Type | Meaning |
|---|---|---|
RawCommand |
string |
Display string for the command line, including the application name. |
ParsedArguments |
IReadOnlyDictionary<string, ParsedValue> |
Raw positional values keyed by argument name. |
ParsedOptions |
IReadOnlyDictionary<string, ParsedValue> |
Raw option values keyed by primary option name. |
Name |
string |
The command name. |
CommandPath |
IReadOnlyList<string> |
Full command path. |
Console |
IConsole |
Standard input, output, and error. |
CommandInterceptorContext<TGlobalOptions> adds:
| Property | Type |
|---|---|
GlobalOptions |
TGlobalOptions |
Parsed value shapes
ParsedValue.Flagrepresents a flag supplied without a value.ParsedValue.Scalarrepresents a single supplied value.Valueis a string, ornullwhen an optional argument was not supplied and has no default.ParsedValue.Multiplerepresents a variadic argument or option with multiple supplied values.Valuesis a read-only string list. A repeated option with one value appears as a scalar.- Values remain strings even when the command parameter is an
int, enum, or other parsed type. - Option keys use the primary option name, such as
--priority; aliases are not separate entries. ParsedOptionscontains options supplied to the command. Options that were not supplied are absent, and typed global options are not included.
Use the command's typed parameters for normal command logic. The dictionaries are intended for cross-cutting interceptor concerns.
Registration
Register an interceptor with AddInterceptor<TInterceptor>():
.AddInterceptor<TimingInterceptor>()
When a service provider is configured, interceptors are resolved from it. Otherwise they are created with a public parameterless constructor.
The AnyCli analyzer reports ANYCLI018 when a global-options interceptor does not match the configured global options type, and ANYCLI019 when an exit-code interceptor does not match the configured command exit code type.
For a full builder example, see Write an interceptor.
Execution order
Interceptors run in registration order before the command and in reverse order after it:
first before
second before
command
second after
first after
The first registered interceptor is the outermost wrapper.
Scope
Interceptors run only when a command is selected and command-line parsing succeeds. They do not run for:
- help or version requests
- unknown commands or options
- missing or invalid parameters
- other command-line parsing errors
An interceptor can short-circuit by returning without calling next. Exceptions thrown by an interceptor or command propagate normally.
Cancellation
The cancellation token passed to InterceptAsync is forwarded to next. An interceptor may pass a linked token to add a timeout or other cancellation condition. See Handle Cancellation.