Skip to content

Fix broken xrefs in System.CommandLine #47952

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 14, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/standard/commandline/get-started-tutorial.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Tutorial: Get started with System.CommandLine"
description: Learn how to use the System.CommandLine library for command-line apps.
ms.date: 04/07/2022
ms.date: 08/13/2025
ms.topic: tutorial
no-loc: [System.CommandLine]
helpviewer_keywords:
Expand Down Expand Up @@ -166,7 +166,7 @@ Options:
--file The file to read and display on the conso
```

<xref:System.CommandLine.RootCommand> by default provides [Help option](how-to-customize-help.md#customize-help-output), [Version option](syntax.md#version-option), and [Suggest directive](syntax.md#suggest-directive). The <xref:System.CommandLine.ParseResult.Invoke?displayProperty=nameWithType> method is responsible for invoking the action of parsed symbol. It could be the action explicitly defined for the command, or the help action defined by `System.CommandLine` for `System.CommandLine.Help.HelpOption`. Moreover, when it detects any parse errors, it prints them to the standard error, prints help to standard output, and returns `1` as the exit code:
<xref:System.CommandLine.RootCommand> by default provides [Help option](how-to-customize-help.md#customize-help-output), [Version option](syntax.md#version-option), and [Suggest directive](syntax.md#suggest-directive). The <xref:System.CommandLine.ParseResult.Invoke(System.CommandLine.InvocationConfiguration)?displayProperty=nameWithType> method is responsible for invoking the action of parsed symbol. It could be the action explicitly defined for the command, or the help action defined by `System.CommandLine` for `System.CommandLine.Help.HelpOption`. Moreover, when it detects any parse errors, it prints them to the standard error, prints help to standard output, and returns `1` as the exit code:

```console
scl --invalid bla
Expand Down
16 changes: 8 additions & 8 deletions docs/standard/commandline/how-to-configure-the-parser.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,41 +14,41 @@ ms.topic: how-to

[!INCLUDE [scl-preview](./includes/preview.md)]

<xref:System.CommandLine.CommandLineConfiguration> is a class that provides properties to configure the parser. It is an optional argument for every `Parse` method, such as <xref:System.CommandLine.Command.Parse*?displayProperty=nameWithType> and <xref:System.CommandLine.Parsing.CommandLineParser.Parse*?displayProperty=nameWithType>. When it isn't provided, the default configuration is used.
<xref:System.CommandLine.ParserConfiguration> is a class that provides properties to configure the parser. It is an optional argument for every `Parse` method, such as <xref:System.CommandLine.Command.Parse*?displayProperty=nameWithType> and <xref:System.CommandLine.Parsing.CommandLineParser.Parse*?displayProperty=nameWithType>. When it isn't provided, the default configuration is used.

<xref:System.CommandLine.ParseResult> has a <xref:System.CommandLine.ParseResult.Configuration> property that returns the configuration used for parsing.

## Standard output and error

`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.
<xref:System.CommandLine.InvocationConfiguration> makes testing, as well as many extensibility scenarios, easier than using `System.Console`. It exposes two `TextWriter` properties: <xref:System.CommandLine.InvocationConfiguration.Output> and <xref:System.CommandLine.InvocationConfiguration.Error>. You can set these properties to any `TextWriter` instance, such as a `StringWriter`, which you can use to capture output for testing.

Define a simple command that writes to standard output:

:::code language="csharp" source="snippets/configuration/csharp/Program.cs" id="rootcommand":::

Now, use `CommandLineConfiguration` to capture the output:
Now, use <xref:System.CommandLine.InvocationConfiguration> to capture the output:

:::code language="csharp" source="snippets/configuration/csharp/Program.cs" id="captureoutput":::

## EnablePosixBundling

[Bundling](syntax.md#option-bundling) of single-character options is enabled by default, but you can disable it by setting the `System.CommandLine.CommandLineConfiguration.EnablePosixBundling` property to `false`.
[Bundling](syntax.md#option-bundling) of single-character options is enabled by default, but you can disable it by setting the <xref:System.CommandLine.ParserConfiguration.EnablePosixBundling?displayProperty=nameWithType> property to `false`.

## ProcessTerminationTimeout

[Process termination timeout](how-to-parse-and-invoke.md#process-termination-timeout) can be configured via the `System.CommandLine.CommandLineConfiguration.ProcessTerminationTimeout` property. The default value is 2 seconds.
[Process termination timeout](how-to-parse-and-invoke.md#process-termination-timeout) can be configured via the <xref:System.CommandLine.InvocationConfiguration.ProcessTerminationTimeout> property. The default value is 2 seconds.

## ResponseFileTokenReplacer

[Response files](syntax.md#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.
[Response files](syntax.md#response-files) are enabled by default, but you can disable them by setting the <xref:System.CommandLine.ParserConfiguration.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.
By default, all unhandled exceptions thrown during the invocation of a command are caught and reported to the user. You can disable this behavior by setting the <xref:System.CommandLine.InvocationConfiguration.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.
<xref:System.CommandLine.InvocationConfiguration> 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.

## See also

Expand Down
6 changes: 3 additions & 3 deletions docs/standard/commandline/how-to-parse-and-invoke.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ This overload of `GetValue` gets the parsed or default value for the specified s

The <xref:System.CommandLine.ParseResult.Errors?displayProperty=nameWithType> property contains a list of parse errors that occurred during the parsing process. Each error is represented by a <xref:System.CommandLine.Parsing.ParseError> object, which contains information about the error, such as the error message and the token that caused the error.

When you call the <xref:System.CommandLine.ParseResult.Invoke?displayProperty=nameWithType> method, it returns an exit code that indicates whether the parsing was successful or not. If there were any parse errors, the exit code is non-zero, and all the parse errors are printed to the standard error.
When you call the <xref:System.CommandLine.ParseResult.Invoke(System.CommandLine.InvocationConfiguration)?displayProperty=nameWithType> method, it returns an exit code that indicates whether the parsing was successful or not. If there were any parse errors, the exit code is non-zero, and all the parse errors are printed to the standard error.

If you don't call the `ParseResult.Invoke` method, you need to handle the errors on your own, for example, by printing them:

Expand Down Expand Up @@ -85,15 +85,15 @@ You don't need to create a derived type to define an action. You can use the <xr

Synchronous and asynchronous actions should not be mixed in the same application. If you want to use asynchronous actions, your application needs to be asynchronous throughout. This means that all actions should be asynchronous, and you should use the `System.CommandLine.Command.SetAction` method that accepts a delegate returning a `Task<int>` exit code. Moreover, the <xref:System.Threading.CancellationToken> that's passed to the action delegate needs to be passed further to all the methods that can be canceled, such as file I/O operations or network requests.

You also need to ensure that the <xref:System.CommandLine.ParseResult.InvokeAsync(System.Threading.CancellationToken)?displayProperty=nameWithType> method is used instead of `Invoke`. This method is asynchronous and returns a `Task<int>` exit code. It also accepts an optional <xref:System.Threading.CancellationToken> parameter that can be used to cancel the action.
You also need to ensure that the <xref:System.CommandLine.ParseResult.InvokeAsync(System.CommandLine.InvocationConfiguration,System.Threading.CancellationToken)?displayProperty=nameWithType> method is used instead of `Invoke`. This method is asynchronous and returns a `Task<int>` exit code. It also accepts an optional <xref:System.Threading.CancellationToken> parameter that can be used to cancel the action.

The following code uses a `SetAction` overload that gets a [ParseResult](#parseresult) and a <xref:System.Threading.CancellationToken> rather than just `ParseResult`:

:::code language="csharp" source="snippets/handle-termination/csharp/Program.cs" id="asyncaction" :::

#### Process termination timeout

<xref:System.CommandLine.CommandLineConfiguration.ProcessTerminationTimeout> enables signaling and handling of process termination (<kbd>Ctrl</kbd>+<kbd>C</kbd>, `SIGINT`, `SIGTERM`) via a <xref:System.Threading.CancellationToken> that's passed to every async action during invocation. It's enabled by default (2 seconds), but you can set it to `null` to disable it.
<xref:System.CommandLine.InvocationConfiguration.ProcessTerminationTimeout> enables signaling and handling of process termination (<kbd>Ctrl</kbd>+<kbd>C</kbd>, `SIGINT`, `SIGTERM`) via a <xref:System.Threading.CancellationToken> that's passed to every async action during invocation. It's enabled by default (2 seconds), but you can set it to `null` to disable it.

When enabled, if the action doesn't complete within the specified timeout, the process will be terminated. This is useful for handling the termination gracefully, for example, by saving the state before the process is terminated.

Expand Down
Loading