System.CommandLine beta 4 (#29580)

Author: tdykstra

docs/standard/commandline/define-commands.md

@@ -210,12 +210,12 @@ Options:
 
 ## Option and argument validation
 
-For information about argument validation and how to customize it, see the following sections in the [Model binding](model-binding.md) article:
+For information about argument validation and how to customize it, see the following sections in the [Parameter binding](model-binding.md) article:
 
 * [Built-in type and arity argument validation](model-binding.md#built-in-argument-validation)
 * [Custom validation and binding](model-binding.md#custom-validation-and-binding)
 
 ## See also
 
 * [System.CommandLine overview](index.md)
-* [Model binding](model-binding.md)
+* [Parameter binding](model-binding.md)

docs/standard/commandline/dependency-injection.md

@@ -1,7 +1,7 @@
 ---
 title: How to configure dependency injection in System.CommandLine
 description: "Learn how to configure dependency injection in System.CommandLine."
-ms.date: 04/07/2022
+ms.date: 05/22/2022
 no-loc: [System.CommandLine]
 helpviewer_keywords:
   - "command line interface"
@@ -13,7 +13,7 @@ ms.topic: how-to
 
 [!INCLUDE [scl-preview](../../../includes/scl-preview.md)]
 
-Use a [custom binder](model-binding.md#model-binding-more-than-16-options-and-arguments) to inject custom types into a command handler.
+Use a [custom binder](model-binding.md#parameter-binding-more-than-8-options-and-arguments) to inject custom types into a command handler.
 
 We recommend handler-specific dependency injection (DI) for the following reasons:
 

docs/standard/commandline/handle-termination.md

@@ -1,7 +1,7 @@
 ---
 title: How to handle termination in System.CommandLine
 description: "Learn how to handle termination in apps that are built with the System.Commandline library."
-ms.date: 04/07/2022
+ms.date: 05/24/2022
 no-loc: [System.CommandLine]
 helpviewer_keywords:
   - "command line interface"
@@ -17,6 +17,8 @@ To handle termination, inject a <xref:System.Threading.CancellationToken> instan
 
 :::code language="csharp" source="snippets/handle-termination/csharp/Program.cs" id="mainandhandler" :::
 
+The preceding code uses a `SetHandler` overload that gets an [InvocationContext](model-binding.md#invocationcontext) instance rather than one or more `IValueDescriptor<T>` objects. The `InvocationContext` is used to get the `CancellationToken` and [ParseResult](model-binding.md#parseresult) objects. `ParseResult` can provide argument or option values.
+
 Cancellation actions can also be added directly using the <xref:System.Threading.CancellationToken.Register%2A?displayProperty=nameWithType> method.
 
 For information about an alternative way to set the process exit code, see [Set exit codes](model-binding.md#set-exit-codes).

docs/standard/commandline/model-binding.md

@@ -1,7 +1,7 @@
 ---
 title: How to bind arguments to handlers in System.CommandLine
 description: "Learn how to do model-binding in apps that are built with the System.Commandline library."
-ms.date: 04/07/2022
+ms.date: 05/24/2022
 no-loc: [System.CommandLine]
 helpviewer_keywords:
   - "command line interface"
@@ -13,7 +13,7 @@ ms.topic: how-to
 
 [!INCLUDE [scl-preview](../../../includes/scl-preview.md)]
 
-The process of parsing arguments and providing them to command handler code is called *model binding*. `System.CommandLine` has the ability to bind many argument types built in. For example, integers, enums, and file system objects such as <xref:System.IO.FileInfo> and <xref:System.IO.DirectoryInfo> can be bound. Several `System.CommandLine` types can also be bound.
+The process of parsing arguments and providing them to command handler code is called *parameter binding*. `System.CommandLine` has the ability to bind many argument types built in. For example, integers, enums, and file system objects such as <xref:System.IO.FileInfo> and <xref:System.IO.DirectoryInfo> can be bound. Several `System.CommandLine` types can also be bound.
 
 ## Built-in argument validation
 
@@ -45,7 +45,7 @@ This behavior can be overridden by setting <xref:System.CommandLine.Option.Allow
 myapp --item one --item two --item three
 ```
 
-## Model binding up to 16 options and arguments
+## Parameter binding up to 16 options and arguments
 
 The following example shows how to bind options to command handler parameters, by calling <xref:System.CommandLine.Handler.SetHandler%2A>:
 
@@ -66,11 +66,19 @@ The variables that follow the lambda represent the option and argument objects t
 * If the out-of-order options or arguments are of different types, a run-time exception is thrown. For example, an `int` might appear where a `string` should be in the list of sources.
 * If the out-of-order options or arguments are of the same type, the handler silently gets the wrong values in the parameters provided to it. For example, `string` option `x` might appear where `string` option `y` should be in the list of sources. In that case, the variable for the option `y` value gets the option `x` value.
 
-There are overloads of <xref:System.CommandLine.Handler.SetHandler%2A> that support up to 16 parameters, with both synchronous and asynchronous signatures.
+There are overloads of <xref:System.CommandLine.Handler.SetHandler%2A> that support up to 8 parameters, with both synchronous and asynchronous signatures.
 
-## Model binding more than 16 options and arguments
+## Parameter binding more than 8 options and arguments
 
-To handle more than 16 options, or to construct a custom type from multiple options, create a *custom binder*. The binder lets you combine multiple option or argument values into a complex type and pass that into a single handler parameter. Suppose you have a `Person` type:
+To handle more than 8 options, or to construct a custom type from multiple options, you can use `InvocationContext` or a custom binder.
+
+### Use `InvocationContext`
+
+A <xref:System.CommandLine.Handler.SetHandler%2A> overload provides access to the <xref:System.CommandLine.Invocation.InvocationContext> object, and you can use `InvocationContext` to get any number of option and argument values. For examples, see [Set exit codes](#set-exit-codes) and [Handle termination](handle-termination.md).
+
+### Use a custom binder
+
+A custom binder lets you combine multiple option or argument values into a complex type and pass that into a single handler parameter. Suppose you have a `Person` type:
 
 :::code language="csharp" source="snippets/model-binding/csharp/ComplexType.cs" id="persontype" :::
 
@@ -92,7 +100,7 @@ There are <xref:System.Threading.Tasks.Task>-returning [Func](xref:System.Func%6
 
 :::code language="csharp" source="snippets/model-binding/csharp/ReturnExitCode.cs" id="returnexitcode" :::
 
-However, if the lambda itself needs to be async, you can't return a `Task<int>`. In that case, use <xref:System.CommandLine.Invocation.InvocationContext.ExitCode?displayProperty=nameWithType>. You can get the `InvocationContext` instance injected into your lambda just by including it as one of the parameters, as in the following example:
+However, if the lambda itself needs to be async, you can't return a `Task<int>`. In that case, use <xref:System.CommandLine.Invocation.InvocationContext.ExitCode?displayProperty=nameWithType>. You can get the `InvocationContext` instance injected into your lambda by using a SetHandler overload that specifies the `InvocationContext` as the sole parameter. This `SetHandler` overload doesn't let you specify `IValueDescriptor<T>` objects, but you can get option and argument values from the [ParseResult](#parseresult) property of `InvocationContext`, as shown in the following example:
 
 :::code language="csharp" source="snippets/model-binding/csharp/ContextExitCode.cs" id="contextexitcode" :::
 
@@ -181,32 +189,30 @@ Besides the file system types and `Uri`, the following types are supported:
 * `ulong`
 * `ushort`
 
-## Inject System.CommandLine types
+## Use System.CommandLine objects
 
-`System.CommandLine` allows you to use some types in handlers by adding parameters for them to the handler signature. The available types include:
+There's a `SetHandler` overload that gives you access to the <xref:System.CommandLine.Invocation.InvocationContext> object. That object can then be used to access other `System.CommandLine` objects. For example, you have access to the following objects:
 
+* <xref:System.CommandLine.Invocation.InvocationContext>
 * <xref:System.Threading.CancellationToken>
 * <xref:System.CommandLine.IConsole>
-* <xref:System.CommandLine.Invocation.InvocationContext>
 * <xref:System.CommandLine.Parsing.ParseResult>
 
-Other types can be injected by using custom binders. For more information, see [Dependency injection](dependency-injection.md).
+### `InvocationContext`
+
+For examples, see [Set exit codes](#set-exit-codes) and [Handle termination](handle-termination.md).
 
 ### `CancellationToken`
 
 For information about how to use <xref:System.Threading.CancellationToken>, see [How to handle termination](handle-termination.md).
 
 ### `IConsole`
 
-<xref:System.CommandLine.IConsole> makes testing as well as many extensibility scenarios easier than using `System.Console`.
-
-### `InvocationContext`
-
-For an example, see [Set exit codes](#set-exit-codes).
+<xref:System.CommandLine.IConsole> makes testing as well as many extensibility scenarios easier than using `System.Console`. It's available in the <xref:System.CommandLine.Invocation.InvocationContext.Console?displayProperty=nameWithType> property.
 
 ### `ParseResult`
 
-<xref:System.CommandLine.Parsing.ParseResult> is a singleton structure that represents the results of parsing the command line input. You can use it to check for the presence of options or arguments on the command line or to get the <xref:System.CommandLine.Parsing.ParseResult.UnmatchedTokens?displayProperty=nameWithType> property. This property contains a list of the [tokens](syntax.md#tokens) that were parsed but didn't match any configured command, option, or argument.
+The <xref:System.CommandLine.Parsing.ParseResult> object is available in the <xref:System.CommandLine.Invocation.InvocationContext.ParseResult?displayProperty=nameWithType> property. It's a singleton structure that represents the results of parsing the command line input. You can use it to check for the presence of options or arguments on the command line or to get the <xref:System.CommandLine.Parsing.ParseResult.UnmatchedTokens?displayProperty=nameWithType> property. This property contains a list of the [tokens](syntax.md#tokens) that were parsed but didn't match any configured command, option, or argument.
 
 The list of unmatched tokens is useful in commands that behave like wrappers. A wrapper command takes a set of [tokens](syntax.md#tokens) and forwards them to another command or app.  The `sudo` command in Linux is an example. It takes the name of a user to impersonate followed by a command to run. For example:
 

docs/standard/commandline/snippets/customize-help/csharp/Program.cs

@@ -37,8 +37,7 @@ static async Task Original(string[] args)
             foregroundColorOption
         };
 
-        rootCommand.SetHandler(
-            (FileInfo file, bool lightMode, ConsoleColor color) =>
+        rootCommand.SetHandler((file, lightMode, color) =>
             {
                 Console.BackgroundColor = lightMode ? ConsoleColor.White: ConsoleColor.Black;
                 Console.ForegroundColor = color;
@@ -77,8 +76,7 @@ static async Task First2Columns(string[] args)
             foregroundColorOption
         };
 
-        rootCommand.SetHandler(
-            (FileInfo file, bool lightMode, ConsoleColor color) =>
+        rootCommand.SetHandler((file, lightMode, color) =>
             {
                 Console.BackgroundColor = lightMode ? ConsoleColor.Black : ConsoleColor.White;
                 Console.ForegroundColor = color;
@@ -134,8 +132,7 @@ static async Task DescriptionSection(string[] args)
             foregroundColorOption
         };
 
-        rootCommand.SetHandler(
-            (FileInfo file, bool lightMode, ConsoleColor color) =>
+        rootCommand.SetHandler((file, lightMode, color) =>
             {
                 Console.BackgroundColor = lightMode ? ConsoleColor.Black : ConsoleColor.White;
                 Console.ForegroundColor = color;

docs/standard/commandline/snippets/customize-help/csharp/scl.csproj

@@ -11,7 +11,7 @@
     <PackageReference Include="Microsoft.Extensions.Logging" Version="6.0.0" />
     <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="6.0.0" />
     <PackageReference Include="Spectre.Console" Version="0.43.0" />
-    <PackageReference Include="System.CommandLine" Version="2.0.0-beta3.22114.1" />
+    <PackageReference Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
   </ItemGroup>
 
 </Project>

docs/standard/commandline/snippets/define-commands/csharp/Program2.cs

@@ -27,12 +27,12 @@ static async Task DefineArguments(string[] args)
         rootCommand.Add(delayArgument);
         rootCommand.Add(messageArgument);
 
-        rootCommand.SetHandler((int delayArgumentValue, string messageArgumentValue) =>
-        {
-            Console.WriteLine($"<delay> argument = {delayArgumentValue}");
-            Console.WriteLine($"<message> argument = {messageArgumentValue}");
-        },
-        delayArgument, messageArgument);
+        rootCommand.SetHandler((delayArgumentValue, messageArgumentValue) =>
+            {
+                Console.WriteLine($"<delay> argument = {delayArgumentValue}");
+                Console.WriteLine($"<message> argument = {messageArgumentValue}");
+            },
+            delayArgument, messageArgument);
 
         await rootCommand.InvokeAsync(args);
         // </definearguments>
@@ -51,9 +51,9 @@ static async Task DefineCommands(string[] args)
         // </definecommands>
 
         sub1aCommand.SetHandler(() =>
-        {
-            Console.WriteLine(sub1aCommand.Description);
-        });
+            {
+                Console.WriteLine(sub1aCommand.Description);
+            });
 
         await rootCommand.InvokeAsync(args);
     }
@@ -72,12 +72,12 @@ static async Task DefineOptions(string[] args)
         rootCommand.Add(delayOption);
         rootCommand.Add(messageOption);
 
-        rootCommand.SetHandler((int delayOptionValue, string messageOptionValue) =>
-        {
-            Console.WriteLine($"--delay = {delayOptionValue}");
-            Console.WriteLine($"--message = {messageOptionValue}");
-        },
-        delayOption, messageOption);
+        rootCommand.SetHandler((delayOptionValue, messageOptionValue) =>
+            {
+                Console.WriteLine($"--delay = {delayOptionValue}");
+                Console.WriteLine($"--message = {messageOptionValue}");
+            },
+            delayOption, messageOption);
         // </defineoptions>
 
         await rootCommand.InvokeAsync(args);
@@ -103,11 +103,11 @@ static async Task GlobalOption(string[] args)
         var subCommand1a = new Command("sub1a", "Second level subcommand");
         subCommand1.Add(subCommand1a);
 
-        subCommand1a.SetHandler((int delayOptionValue) =>
-        {
-            Console.WriteLine($"--delay = {delayOptionValue}");
-        },
-        delayOption);
+        subCommand1a.SetHandler((delayOptionValue) =>
+            {
+                Console.WriteLine($"--delay = {delayOptionValue}");
+            },
+            delayOption);
 
         await rootCommand.InvokeAsync(args);
         // </defineglobal>
@@ -125,12 +125,12 @@ static async Task RequiredOption(string[] args)
         var command = new RootCommand();
         command.Add(endpointOption);
 
-        command.SetHandler(
-            (Uri? uri) =>
+        command.SetHandler((uri) =>
             {
                 Console.WriteLine(uri?.GetType());
                 Console.WriteLine(uri?.ToString());
-            }, endpointOption);
+            },
+            endpointOption);
 
         await command.InvokeAsync(args);
         // </requiredoption>
@@ -145,12 +145,12 @@ static async Task HiddenOption(string[] args)
         var command = new RootCommand();
         command.Add(endpointOption);
 
-        command.SetHandler(
-            (Uri? uri) =>
+        command.SetHandler((uri) =>
             {
                 Console.WriteLine(uri?.GetType());
                 Console.WriteLine(uri?.ToString());
-            }, endpointOption);
+            },
+            endpointOption);
 
         await command.InvokeAsync(args);
         // </hiddenoption>
@@ -177,11 +177,11 @@ static async Task FromAmong(string[] args)
         var rootCommand = new RootCommand("Static list example");
         rootCommand.Add(languageOption);
 
-        rootCommand.SetHandler((string languageOptionValue) =>
-        {
-            Console.WriteLine($"--language = {languageOptionValue}");
-        },
-        languageOption);
+        rootCommand.SetHandler((languageOptionValue) =>
+            {
+                Console.WriteLine($"--language = {languageOptionValue}");
+            },
+            languageOption);
 
         await rootCommand.InvokeAsync(args);
         Console.WriteLine("Request help, provide a valid language, provide an invalid language.");

docs/standard/commandline/snippets/define-commands/csharp/scl.csproj

@@ -9,7 +9,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="System.CommandLine" Version="2.0.0-beta3.22114.1" />
+    <PackageReference Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
   </ItemGroup>
 
 </Project>

docs/standard/commandline/snippets/dependency-injection/csharp/Program.cs

@@ -15,11 +15,11 @@ static async Task Main(string[] args)
         rootCommand.Add(fileOption);
 
         // <sethandler>
-        rootCommand.SetHandler(async (FileInfo fileOptionValue, ILogger logger) =>
-        {
-            await DoRootCommand(fileOptionValue, logger);
-        },
-        fileOption, new MyCustomBinder());
+        rootCommand.SetHandler(async (fileOptionValue, logger) =>
+            {
+                await DoRootCommand(fileOptionValue!, logger);
+            },
+            fileOption, new MyCustomBinder());
         // </sethandler>
 
         await rootCommand.InvokeAsync("--file scl.runtimeconfig.json");
@@ -40,7 +40,7 @@ protected override ILogger GetBoundValue(
 
         ILogger GetLogger(BindingContext bindingContext)
         {
-            var loggerFactory = LoggerFactory.Create(
+            ILoggerFactory loggerFactory = LoggerFactory.Create(
                 builder => builder.AddConsole());
             ILogger logger = loggerFactory.CreateLogger("LoggerCategory");
             return logger;

docs/standard/commandline/snippets/dependency-injection/csharp/scl.csproj

@@ -10,7 +10,7 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.Logging" Version="6.0.0" />
     <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="6.0.0" />
-    <PackageReference Include="System.CommandLine" Version="2.0.0-beta3.22114.1" />
+    <PackageReference Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
   </ItemGroup>
 
 </Project>