How to configure the parser in System.CommandLine

2025-06-19

Important

System.CommandLine is currently in PREVIEW, and this documentation is for version 2.0 beta 5. Some information relates to prerelease product that may be substantially modified before it's released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

System.CommandLine.CommandLineConfiguration is a class that provides properties to configure the parser. It is an optional argument for every Parse method, such as System.CommandLine.Command.Parse or System.CommandLine.Parsing.CommandLineParser.Parse. When it is not provided, the default configuration is used.

Every System.CommandLine.ParseResult instance has a System.CommandLine.ParseResult.Configuration property that returns the configuration used for parsing.

Standard output and error

System.CommandLine.CommandLineConfiguration makes testing, as well as many extensibility scenarios, easier than using System.Console. It exposes two TextWriter properties: Output and Error. These can be set to any TextWriter instance, such as a StringWriter, which can be used to capture output for testing.

Let's define a simple command that writes to standard output:

Option<FileInfo?> fileOption = new("--file")
{
    Description = "An option whose argument is parsed as a FileInfo"
};

RootCommand rootCommand = new("Configuration sample")
{
    fileOption
};

rootCommand.SetAction((parseResult) =>
{
    FileInfo? fileOptionValue = parseResult.GetValue(fileOption);
    parseResult.Configuration.Output.WriteLine($"File option value: {fileOptionValue?.FullName}");
});

Now, let's use CommandLineConfiguration to capture the output:

StringWriter output = new();
CommandLineConfiguration configuration = new(rootCommand)
{
    Output = output,
    Error = TextWriter.Null
};

configuration.Parse("-h").Invoke();
Debug.Assert(output.ToString().Contains("Configuration sample"));

EnablePosixBundling

Bundling of single-character options is enabled by default, but you can disable it by setting the System.CommandLine.CommandLineConfiguration.EnablePosixBundling property to false.

ProcessTerminationTimeout

Process termination timeout can be configured via the System.CommandLine.CommandLineConfiguration.ProcessTerminationTimeout property. The default value is 2 seconds.

ResponseFileTokenReplacer

Response files are enabled by default, but you can disable them by setting the System.CommandLine.CommandLineConfiguration.ResponseFileTokenReplacer property to null. You can also provide a custom implementation to customize how response files are processed.

EnableDefaultExceptionHandler

By default, all unhandled exceptions thrown during the invocation of a command are caught and reported to the user. This behavior can be disabled by setting the System.CommandLine.CommandLineConfiguration.EnableDefaultExceptionHandler property to false. This is useful when you want to handle exceptions in a custom way, such as logging them or providing a different user experience.

Derived classes

System.CommandLine.CommandLineConfiguration is not sealed, so you can derive from it to add custom properties or methods. This is useful when you want to provide additional configuration options specific to your application.

Share via