You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<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.
17
+
<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> or <xref:System.CommandLine.Parsing.CommandLineParser.Parse>. When it is not provided, the default configuration is used.
18
18
19
19
Every <xref:System.CommandLine.ParseResult> instance has a <xref:System.CommandLine.ParseResult.Configuration> property that returns the configuration used for parsing.
20
20
21
21
## Standard output and error
22
22
23
-
<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.
23
+
<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`. These can be set to any `TextWriter` instance, such as a `StringWriter`, which can be used to capture output for testing.
24
24
25
25
Let's define a simple command that writes to standard output:
@@ -44,12 +44,12 @@ And let's use `CommandLineConfiguration` to capture the output:
44
44
45
45
## EnableDefaultExceptionHandler
46
46
47
-
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.
47
+
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 <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.
48
48
49
49
## Derived classes
50
50
51
51
<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.
Copy file name to clipboardExpand all lines: docs/standard/commandline/design-guidance.md
+14-14Lines changed: 14 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,21 +13,21 @@ ms.topic: conceptual
13
13
14
14
The following sections present guidance that we recommend you follow when designing a CLI. Think of what your app expects on the command line as similar to what a REST API server expects in the URL. Consistent rules for REST APIs are what make them readily usable to client app developers. In the same way, users of your command-line apps will have a better experience if the CLI design follows common patterns.
15
15
16
-
Once you create a CLI it is hard to change, especially if your users have used your CLI in scripts they expect to keep running. The guidelines here were developed after the .NET CLI, and it doesn't always follow these guidelines. We are updating the .NET CLI where we can do it without introducing breaking changes. An example of this work is the new design for `dotnet new` in .NET 7.
16
+
Once you create a CLI, it is hard to change, especially if your users have used your CLI in scripts they expect to keep running. The guidelines here were developed after the .NET CLI, and it doesn't always follow these guidelines. We are updating the .NET CLI where we can do so without introducing breaking changes. An example of this work is the new design for `dotnet new` in .NET 7.
17
17
18
18
## Symbols
19
19
20
20
### Commands and subcommands
21
21
22
-
If a command has subcommands, the command should function as an area, or a grouping identifier for the subcommands, rather than specify an action. When you invoke the app, you specify the grouping command and one of its subcommands. For example, try to run `dotnet tool`, and you get an error message because the `tool` command only identifies a group of tool-related subcommands, such as `install` and `list`. You can run `dotnet tool install`, but `dotnet tool` by itself would be incomplete.
22
+
If a command has subcommands, the command should function as an area or a grouping identifier for the subcommands, rather than specify an action. When you invoke the app, you specify the grouping command and one of its subcommands. For example, try to run `dotnet tool`, and you get an error message because the `tool` command only identifies a group of tool-related subcommands, such as `install` and `list`. You can run `dotnet tool install`, but `dotnet tool` by itself would be incomplete.
23
23
24
24
One of the ways that defining areas helps your users is that it organizes the help output.
25
25
26
-
Within a CLI there is often an implicit area. For example, in the .NET CLI, the implicit area is the project and in the Docker CLI it is the image. As a result, you can use `dotnet build` without including an area. Consider whether your CLI has an implicit area. If it does, consider whether to allow the user to optionally include or omit it as in `docker build` and `docker image build`. If you optionally allow the implicit area to be typed by your user, you also automatically have help and tab completion for this grouping of commands. Supply the optional use of the implicit group by defining two commands that perform the same operation.
26
+
Within a CLI, there is often an implicit area. For example, in the .NET CLI, the implicit area is the project, and in the Docker CLI, it is the image. As a result, you can use `dotnet build` without including an area. Consider whether your CLI has an implicit area. If it does, consider whether to allow the user to optionally include or omit it, as in `docker build` and `docker image build`. If you optionally allow the implicit area to be typed by your user, you also automatically have help and tab completion for this grouping of commands. Supply the optional use of the implicit group by defining two commands that perform the same operation.
27
27
28
28
### Options as parameters
29
29
30
-
Options should provide parameters to commands, rather than specifying actions themselves. This is a recommended design principle although it isn't always followed by `System.CommandLine` (`--help` displays help information).
30
+
Options should provide parameters to commands, rather than specifying actions themselves. This is a recommended design principle, although it isn't always followed by `System.CommandLine` (`--help` displays help information).
31
31
32
32
## Naming
33
33
@@ -39,7 +39,7 @@ In particular, avoid using any of the following aliases differently than their c
39
39
40
40
*`-i` for `--interactive`.
41
41
42
-
This option signals to the user that they may be prompted for inputs to questions that the command needs answered. For example, prompting for a username. Your CLI may be used in scripts, so use caution in prompting users that have not specified this switch.
42
+
This option signals to the user that they may be prompted for inputs to questions that the command needs answered. For example, prompting for a username. Your CLI may be used in scripts, so use caution in prompting users who have not specified this switch.
43
43
44
44
*`-o` for `--output`.
45
45
@@ -69,11 +69,11 @@ There are also some aliases with common usage limited to the .NET CLI. You can u
69
69
70
70
### Short names
71
71
72
-
Make names for commands, options, and arguments as short and easy to spell as possible. For example, if `class` is clear enough don't make the command `classification`.
72
+
Make names for commands, options, and arguments as short and easy to spell as possible. For example, if `class` is clear enough, don't make the command `classification`.
73
73
74
74
### Lowercase names
75
75
76
-
Define names in lowercase only, except you can make uppercase aliases to make commands or options caseinsensitive.
76
+
Define names in lowercase only, except you can make uppercase aliases to make commands or options case-insensitive.
77
77
78
78
### Kebab case names
79
79
@@ -85,10 +85,10 @@ Within an app, be consistent in pluralization. For example, don't mix plural and
|`--additional-probing-paths` and `--sources`| ✔️ |
89
-
|`--additional-probing-path` and `--source`| ✔️ |
90
-
|`--additional-probing-paths` and `--source`| ❌ |
91
-
|`--additional-probing-path` and `--sources`| ❌ |
88
+
|`--additional-probing-paths` and `--sources`| ✔️ |
89
+
|`--additional-probing-path` and `--source`| ✔️ |
90
+
|`--additional-probing-paths` and `--source`| ❌ |
91
+
|`--additional-probing-path` and `--sources`| ❌ |
92
92
93
93
### Verbs vs. nouns
94
94
@@ -106,20 +106,20 @@ Use verbs rather than nouns for commands that refer to actions (those without su
106
106
107
107
These are the standard names, but existing apps sometimes use `Silent` in place of `Quiet`, and `Trace`, `Debug`, or `Verbose` in place of `Diagnostic`.
108
108
109
-
Each app defines its own criteria that determine what gets displayed at each level. Typically an app only needs three levels:
109
+
Each app defines its own criteria that determine what gets displayed at each level. Typically, an app only needs three levels:
110
110
111
111
* Quiet
112
112
* Normal
113
113
* Diagnostic
114
114
115
115
If an app doesn't need five different levels, the option should still define the same five settings. In that case, `Minimal` and `Normal` will produce the same output, and `Detailed` and `Diagnostic` will likewise be the same. This allows your users to just type what they are familiar with, and the best fit will be used.
116
116
117
-
The expectation for `Quiet` is that no output is displayed on the console. However, if an app offers an interactive mode, the app should do one of the following alternatives:
117
+
The expectation for `Quiet` is that no output is displayed on the console. However, if an app offers an interactive mode, the app should do one of the following:
118
118
119
119
* Display prompts for input when `--interactive` is specified, even if `--verbosity` is `Quiet`.
120
120
* Disallow the use of `--verbosity Quiet` and `--interactive` together.
121
121
122
-
Otherwise the app will wait for input without telling the user what it's waiting for. It will appear that your application froze and the user will have no idea the application is waiting for input.
122
+
Otherwise, the app will wait for input without telling the user what it's waiting for. It will appear that your application froze, and the user will have no idea the application is waiting for input.
123
123
124
124
If you define aliases, use `-v` for `--verbosity` and make `-v` without an argument an alias for `--verbosity Diagnostic`. Use `-q` for `--verbosity Quiet`.
This tutorial shows how to create a .NET command-line app that uses the [`System.CommandLine` library](index.md). You'll begin by creating a simple root command that has one option. Then you'll add to that base, creating a more complex app that contains multiple subcommands and different options for each command.
16
+
This tutorial shows how to create a .NET command-line app that uses the [`System.CommandLine` library](index.md). You'll begin by creating a simple root command that has one option. Then you'll build on that base, creating a more complex app that contains multiple subcommands and different options for each command.
17
17
18
18
In this tutorial, you learn how to:
19
19
@@ -25,7 +25,7 @@ In this tutorial, you learn how to:
25
25
> * Assign an option recursively to all subcommands under a command.
26
26
> * Work with multiple levels of nested subcommands.
27
27
> * Create aliases for commands and options.
28
-
> * Work with `string`, `string[]`, `int`, `bool`, `FileInfo` and enum option types.
28
+
> * Work with `string`, `string[]`, `int`, `bool`, `FileInfo`, and enum option types.
29
29
> * Read option values in command action code.
30
30
> * Use custom code for parsing and validating options.
The `System.CommandLine` library provides functionality that is commonly needed by command-line apps, such as parsing the command-line input and displaying help text.
17
+
The `System.CommandLine` library provides functionality commonly needed by command-line apps, such as parsing command-line input and displaying help text.
18
18
19
19
Apps that use `System.CommandLine` include the [.NET CLI](../../core/tools/index.md), [additional tools](../../core/additional-tools/index.md), and many [global and local tools](../../core/tools/global-tools.md).
20
20
21
21
For app developers, the library:
22
22
23
-
* Lets you focus on writing your app code, since you don't have to write code to parse command-line input or produce a help page.
24
-
* Lets you test app code independently of input parsing code.
25
-
* Is [trim-friendly](../../core/deploying/trimming/trim-self-contained.md), making it a good choice for developing a fast, lightweight, AOT-capable CLI app.
23
+
- Lets you focus on writing your app code, since you don't have to write code to parse command-line input or produce a help page.
24
+
- Lets you test app code independently of input parsing code.
25
+
- Is [trim-friendly](../../core/deploying/trimming/trim-self-contained.md), making it a good choice for developing fast, lightweight, AOT-capable CLI apps.
26
26
27
27
Use of the library also benefits app users:
28
28
29
-
* It ensures that command-line input is parsed consistently according to [POSIX](https://en.wikipedia.org/wiki/POSIX) or Windows conventions.
30
-
* It automatically supports [tab completion](tab-completion.md) and [response files](syntax.md#response-files).
29
+
- It ensures that command-line input is parsed consistently according to [POSIX](https://en.wikipedia.org/wiki/POSIX) or Windows conventions.
30
+
- It automatically supports [tab completion](tab-completion.md) and [response files](syntax.md#response-files).
0 commit comments