simplify parsing and validation doc, add config doc, polish other docs

Author: adamsitnik

docs/standard/commandline/command-line-configuration.md

@@ -0,0 +1,55 @@
+---
+title: How to configure the parser in System.CommandLine
+description: "Learn how to configure the parser in System.CommandLine."
+ms.date: 16/06/2025
+no-loc: [System.CommandLine]
+helpviewer_keywords:
+  - "command line interface"
+  - "command line"
+  - "System.CommandLine"
+ms.topic: how-to
+---
+
+# How to configure the parser in System.CommandLine
+
+[!INCLUDE [scl-preview](../../../includes/scl-preview.md)]
+
+<xref:System.CommandLine.CommandLineConfiguration> is a class that provides properties to configure the parser. It's an optional argument for every `Parse` method such as <xref:System.CommandLine.Command.Parse> or <xref:System.CommandLine.Parsing.CommandLineParser.Parse>. When it's not provided, default configuration is used. 
+
+Every <xref:System.CommandLine.ParseResult> instance has a <xref:System.CommandLine.ParseResult.Configuration> property that returns the configuration used for parsing.
+
+## Standard output and error
+
+<xref:System.CommandLine.CommandLineConfiguration> makes testing as well as many extensibility scenarios easier than using `System.Console`. It exposes two `TextWriter` properties: `Output` and `Error`. They 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:
+
+:::code language="csharp" source="snippets/configuration/csharp/Program.cs" id="setaction" :::
+
+And let's use `CommandLineConfiguration` to capture the output:
+
+:::code language="csharp" source="snippets/configuration/csharp/Program.cs" id="captureoutput" :::
+
+## EnablePosixBundling
+
+[Bundling](syntax.md#bundling-options) of single-character options is enabled by default, but you can disable it by setting the <xref:System.CommandLine.CommandLineConfiguration.EnablePosixBundling> property to `false`.
+
+## ProcessTerminationTimeout
+
+[Process termination timeout](parse-and-invoke.md#process-termination-timeout) can be configured via the <xref:System.CommandLine.CommandLineConfiguration.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 <xref: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 invocation of a command are caught and reported to the user. This behavior can be disabled by setting the <xref: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
+
+<xref: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.
+
+## See also
+
+[System.CommandLine overview](index.md)

docs/standard/commandline/dependency-injection.md

@@ -45,9 +45,9 @@ To get started with System.CommandLine, see the following resources:
 To learn more, see the following resources:
 
 * [How to parse and invoke the result](parse-and-invoke.md)
-* [How to bind arguments to handlers](model-binding.md)
-* [How to configure help in System.CommandLine](help.md)
+* [How to customize parsing and validation](parsing-and-validation.md)
+* [How to configure the parser](command-line-configuration.md)
+* [How to customize help](help.md)
 * [How to enable and customize tab completion](tab-completion.md)
-* [How to configure dependency injection](dependency-injection.md)
 * [Command-line design guidance](design-guidance.md)
 * [System.CommandLine API reference](xref:System.CommandLine)

docs/standard/commandline/index.md

@@ -1,15 +1,15 @@
 ---
 title: "How to parse and invoke the result"
 description: "Learn how to get parsed values and define actions for your commands."
-ms.date: 04/07/2022
+ms.date: 16/06/2025
 no-loc: [System.CommandLine]
 helpviewer_keywords:
   - "command line interface"
   - "command line"
   - "System.CommandLine"
 ---
 
-# Parsing and invocation
+# Parsing and invocation in System.CommandLine
 
 [!INCLUDE [scl-preview](../../../includes/scl-preview.md)]
 
@@ -37,9 +37,17 @@ The <xref:System.CommandLine.Parsing.ParseResult.GetValue%2A> method allows you
 
 :::code language="csharp" source="snippets/model-binding/csharp/Program.cs" id="getvalue" :::
 
-You can also get values by name, but this requires you to specify the type of the value you want to get:
+You can also get values by name, but this requires you to specify the type of the value you want to get.
 
-:::code language="csharp" source="snippets/model-binding/csharp/Program.cs" id="getvaluebyname" :::
+The following example uses C# collection initializers to create a root command:
+
+:::code language="csharp" source="snippets/model-binding/csharp/Program.cs" id="collectioninitializersyntax" :::
+
+And then it uses the `GetValue` method to get the values by name:
+
+:::code language="csharp" source="snippets/model-binding/csharp/Program.cs" id="lambdanames" :::
+
+This overload of `GetValue` gets the parsed or default value for the specified symbol name, in the context of parsed command (not entire symbol tree). It accepts the symbol name, not an [alias](syntax.md#aliases).
 
 ### Parse errors
 
@@ -108,3 +116,8 @@ The exit code is an integer value returned by an action indicating its success o
 Every `SetAction` method has an overload that accepts a delegate returning an `int` exit code where the exit code needs to be provided in explicit way and an overload that returns `0`.
 
 :::code language="csharp" source="snippets/model-binding/csharp/ReturnExitCode.cs" id="returnexitcode" :::
+
+## See also
+
+[How to customize parsing and validation in System.CommandLine](parsing-and-validation.md)
+[System.CommandLine overview](index.md)

docs/standard/commandline/model-binding.md

@@ -0,0 +1,78 @@
+---
+title: How to customize parsing and validation in System.CommandLine
+description: "Learn how to customize parsing and validation with the System.Commandline library."
+ms.date: 06/16/2025
+no-loc: [System.CommandLine]
+helpviewer_keywords:
+  - "command line interface"
+  - "command line"
+  - "System.CommandLine"
+ms.topic: how-to
+---
+# How to customize parsing and validation in System.CommandLine
+
+[!INCLUDE [scl-preview](../../../includes/scl-preview.md)]
+
+By default, System.CommandLine provides a set of built-in parsers that can parse many common types:
+
+* `bool`
+* `byte` and `sbyte`
+* `short` and `ushort`
+* `int` and `uint`
+* `long` and `ulong`
+* `float` and `double`
+* `decimal`
+* `DateTime` and `DateTimeOffset`
+* `DateOnly`and `TimeOnly`
+* `Guid`,
+* <xref:System.IO.FileSystemInfo>, <xref:System.IO.FileInfo>, and <xref:System.IO.DirectoryInfo>
+* enums
+* **arrays and lists** of the above types
+
+Other types are not supported, but you can create custom parsers for them. You can also validate the parsed values, which is useful when you want to ensure that the input meets certain criteria.
+
+## Validators
+
+Every option, argument, and command can have one or more validators. Validators are used to ensure that the parsed value meets certain criteria. For example, you can validate that a number is positive, or that a string is not empty. You can also create complex validators that check against multiple conditions.
+
+Every symbol type in System.CommandLine has a `Validators` property that contains a list of validators. The validators are executed after the input is parsed, and they can report an error if the validation fails.
+
+To provide custom validation code, call <xref:System.CommandLine.Option.Validators.Add%2A> on your option or argument (or command), as shown in the following example:
+
+:::code language="csharp" source="snippets/model-binding/csharp/AddValidator.cs" id="delayOption" :::
+
+System.CommandLine provides a set of built-in validators that can be used to validate common types:
+- `AcceptExistingOnly` - configures given option or argument to accept only values corresponding to an existing file or directory.
+- `AcceptLegalFileNamesOnly` - configures given option or argument to accept only values representing legal file names.
+- `AcceptOnlyFromAmong` - configures given option or argument to accept only values from a specified set of values.
+
+## Custom parsers
+
+Custom parsers are required to parse types with no default parser, such as complex types. They can also be used to parse supported types in a different way than the built-in parsers.
+
+Suppose you have a `Person` type:
+
+:::code language="csharp" source="snippets/model-binding/csharp/ComplexType.cs" id="persontype" :::
+
+You can just read the values and create an instance of `Person` in the command action:
+
+:::code language="csharp" source="snippets/model-binding/csharp/ComplexType.cs" id="setaction" :::
+
+With the custom parser, you can get a custom type the same way you get primitive values:
+
+:::code language="csharp" source="snippets/model-binding/csharp/ParseArgument.cs" id="personoption" :::
+
+If you want to parse as well as validate the input, use the `CustomParser` delegate, as shown in the following example:
+
+:::code language="csharp" source="snippets/model-binding/csharp/ParseArgument.cs" id="delayOption" :::
+
+Here are some examples of what you can do with `CustomParser` that you can't do with a validator:
+
+* Parsing of other kinds of input strings (for example, parse "1,2,3" into `int[]`).
+
+* Dynamic arity. For example, you have two arguments that are defined as string arrays, and you have to handle a sequence of strings in the command line input. The <xref:System.CommandLine.Parsing.ArgumentResult.OnlyTake%2A?displayProperty=nameWithType> method enables you to dynamically divide up the input strings between the arguments.
+
+## See also
+
+[How to parse and invoke the result](parse-and-invoke.md)
+[System.CommandLine overview](index.md)