From 812fcd1c62caf9541ba9d2342c87f1a643fe9e3e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 5 Dec 2025 19:25:01 -0800 Subject: [PATCH 1/2] fix option construction --- docs/standard/commandline/how-to-parse-and-invoke.md | 10 +++++----- .../snippets/handle-termination/csharp/Program.cs | 5 ++++- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/standard/commandline/how-to-parse-and-invoke.md b/docs/standard/commandline/how-to-parse-and-invoke.md index 8e40bf7d6fe08..9b975b8b3381b 100644 --- a/docs/standard/commandline/how-to-parse-and-invoke.md +++ b/docs/standard/commandline/how-to-parse-and-invoke.md @@ -17,17 +17,17 @@ In the following example from the [Get started with System.CommandLine](get-star :::code language="csharp" source="snippets/get-started-tutorial/csharp/Stage0/Program.cs" id="all" ::: -An action is invoked when a given command (or directive, or option) is parsed successfully. The action is a delegate that takes a `ParseResult` argument and returns an `int` exit code ([async actions](#asynchronous-actions) are also available). The exit code is returned by the `System.CommandLine.Parsing.ParseResult.Invoke` method and can be used to indicate whether the command was executed successfully or not. +An action is invoked when a given command (or directive, or option) is parsed successfully. The action is a delegate that takes a `ParseResult` argument and returns an `int` exit code ([async actions](#asynchronous-actions) are also available). The exit code is returned by the method and can be used to indicate whether the command was executed successfully or not. In the following example from the [Get started with System.CommandLine](get-started-tutorial.md) tutorial, the action is defined for the root command and invoked after parsing the command-line input: :::code language="csharp" source="snippets/get-started-tutorial/csharp/Stage1/Program.cs" id="all" ::: -Some built-in symbols, such as `System.CommandLine.Help.HelpOption`, `System.CommandLine.VersionOption`, and `System.CommandLine.Completions.SuggestDirective`, come with predefined actions. These symbols are automatically added to the root command when you create it, and when you invoke the `System.CommandLine.Parsing.ParseResult`, they "just work." Using actions allows you to focus on your app logic, while the library takes care of parsing and invoking actions for built-in symbols. If you prefer, you can stick to the parsing process and not define any actions (as in the first example above). +Some built-in symbols, such as , , and , come with predefined actions. These symbols are automatically added to the root command when you create it, and when you invoke the , they "just work." Using actions allows you to focus on your app logic, while the library takes care of parsing and invoking actions for built-in symbols. If you prefer, you can stick to the parsing process and not define any actions (as in the first example in this article). -## ParseResult +## `ParseResult` -The class represents the results of parsing the command-line input. You need to use it to get the parsed values for options and arguments (no matter if you're using actions or not). You can also check if there were any parse errors or unmatched [tokens](syntax.md#tokens). +The class represents the results of parsing the command-line input. You need to use it to get the parsed values for options and arguments (no matter if you're using actions or not). You can also check if there were any parse errors or unmatched [tokens](syntax.md#tokens). ### GetValue @@ -81,7 +81,7 @@ You don't need to create a derived type to define an action. You can use the ` exit code. Moreover, the 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. +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 `SetAction` method that accepts a delegate returning a `Task` exit code. Moreover, the 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 method is used instead of `Invoke`. This method is asynchronous and returns a `Task` exit code. It also accepts an optional parameter that can be used to cancel the action. diff --git a/docs/standard/commandline/snippets/handle-termination/csharp/Program.cs b/docs/standard/commandline/snippets/handle-termination/csharp/Program.cs index b7e22c6e02efd..e027d52a4357c 100644 --- a/docs/standard/commandline/snippets/handle-termination/csharp/Program.cs +++ b/docs/standard/commandline/snippets/handle-termination/csharp/Program.cs @@ -5,7 +5,10 @@ class Program // static Task Main(string[] args) { - Option urlOption = new("--url", "A URL."); + Option urlOption = new("--url") + { + Description = "A URL." + }; RootCommand rootCommand = new("Handle termination example") { urlOption }; rootCommand.SetAction((ParseResult parseResult, CancellationToken cancellationToken) => From 938a21732b00b7c21f3721075c69668faa1e29ca Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 5 Dec 2025 21:34:24 -0800 Subject: [PATCH 2/2] Update docs/standard/commandline/how-to-parse-and-invoke.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/standard/commandline/how-to-parse-and-invoke.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/commandline/how-to-parse-and-invoke.md b/docs/standard/commandline/how-to-parse-and-invoke.md index 9b975b8b3381b..6fb8472f398cc 100644 --- a/docs/standard/commandline/how-to-parse-and-invoke.md +++ b/docs/standard/commandline/how-to-parse-and-invoke.md @@ -23,7 +23,7 @@ In the following example from the [Get started with System.CommandLine](get-star :::code language="csharp" source="snippets/get-started-tutorial/csharp/Stage1/Program.cs" id="all" ::: -Some built-in symbols, such as , , and , come with predefined actions. These symbols are automatically added to the root command when you create it, and when you invoke the , they "just work." Using actions allows you to focus on your app logic, while the library takes care of parsing and invoking actions for built-in symbols. If you prefer, you can stick to the parsing process and not define any actions (as in the first example in this article). +Some built-in symbols, such as , , and , come with predefined actions. These symbols are automatically added to the root command when you create it, and when you invoke the , they "just work." Using actions allows you to focus on your app logic, while the library takes care of parsing and invoking actions for built-in symbols. If you prefer, you can stick to the parsing process and not define any actions (as in the first example in this article). ## `ParseResult`