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
Command-line apps typically provide an option to display a brief description of the available commands, options, and arguments. `System.CommandLine` provides <xref:System.CommandLine.Help.HelpOption> that is by default included in the [RootCommand](syntax.md#root-command) options. It generates help output.
16
-
For example:
15
+
Command-line apps typically provide an option to display a brief description of the available commands, options, and arguments. `System.CommandLine` provides <xref:System.CommandLine.Help.HelpOption> that is by default included in the [RootCommand](syntax.md#root-command) options. <xref:System.CommandLine.Help.HelpOption> generates help output for defined symbols by using the information exposed by <xref:System.CommandLine.Symbol.Name>, <xref:System.CommandLine.Symbol.HelpName>, <xref:System.CommandLine.Symbol.Description>, and other properties like default value or completion sources.
App users might be accustomed to different ways to request help on different platforms, so apps built on `System.CommandLine` respond to many ways of requesting help. The following commands are all equivalent:
@@ -49,63 +47,17 @@ dotnet /?
49
47
50
48
Help output doesn't necessarily show all available commands, arguments, and options. Some of them may be *hidden* via the <xref:System.CommandLine.Symbol.Hidden> property, which means they don't show up in help output (and completions) but they can be specified on the command line.
51
49
52
-
## How to customize help in apps that are built with the System.Commandline library
53
-
54
-
You can customize help for a specific command, option, or argument, and you can add or replace whole help sections.
50
+
## Help customization
55
51
56
-
The examples in this article work with the following command-line application:
52
+
You can customize help output for commands by defining specific help text for each symbol, providing further clarity to users regarding their usage.
57
53
58
-
This code requires a `using` directive:
54
+
To customize the name of an option's argument, use the option's <xref:System.CommandLine.Option.HelpName> property.
In the sample app, `--light-mode` is explained adequately, but changes to the `--file` and `--color` option descriptions will be helpful. For `--file`, the argument can be identified as a `<FILEPATH>`. For the `--color` option, you can shorten the list of available colors.
65
57
66
-
Without customization, the following help output is produced:
67
-
68
-
```output
69
-
Description:
70
-
Read a file
58
+
To make these changes, extend the previous code with the following code:
71
59
72
-
Usage:
73
-
scl [options]
74
-
75
-
Options:
76
-
--file <file> The file to print out. [default: scl.runtimeconfig.json]
77
-
--light-mode Determines whether the background color will be black or
78
-
white
79
-
--color Specifies the foreground color of console output
To customize the name of an option's argument, use the option's <xref:System.CommandLine.Option.HelpName> property. And <xref:System.CommandLine.Help.HelpBuilder.CustomizeSymbol%2A?displayProperty=nameWithType> lets you customize several parts of the help output for a command, option, or argument (<xref:System.CommandLine.Symbol> is the base class for all three types). With `CustomizeSymbol`, you can specify:
92
-
93
-
* The first column text.
94
-
* The second column text.
95
-
* The way a default value is described.
96
-
97
-
In the sample app, `--light-mode` is explained adequately, but changes to the `--file` and `--color` option descriptions will be helpful. For `--file`, the argument can be identified as a `<FILEPATH>` instead of `<file>`. For the `--color` option, you can shorten the list of available colors in column one, and in column two you can add a warning that some colors won't work with some backgrounds.
98
-
99
-
To make these changes, delete the `rootCommand.Parse(args).Invoke();` line shown in the preceding code and add in its place the following code:
--file <FILEPATH> The file to print out. [default: CustomHelp.runtimeconfig.json]
121
-
--light-mode Determines whether the background color will be black or white
122
-
--color <Black, White, Red, or Yellow> Specifies the foreground color. Choose a color that provides enough contrast
123
-
with the background color. For example, a yellow foreground can't be read
124
-
against a light mode background.
125
-
--version Show version information
126
-
-?, -h, --help Show help and usage information
72
+
-?, -h, --help Show help and usage information
73
+
--version Show version information
74
+
--file <FILEPATH> The file to print out.
75
+
--light-mode Determines whether the background color will be black or white
76
+
--color <Black|Red|White|Yellow> Specifies the foreground color of console output [default: White]
127
77
```
128
78
129
-
This output shows that the `firstColumnText` and `secondColumnText` parameters support word wrapping within their columns.
130
-
131
-
## Add or replace help sections
79
+
## Add sections to help output
132
80
133
-
You can add or replace a whole section of the help output. For example, suppose you want to add some ASCII art to the description section by using the [Spectre.Console](https://www.nuget.org/packages/Spectre.Console/) NuGet package.
81
+
You can add first or last sections to the help output. For example, suppose you want to add some ASCII art to the description section by using the [Spectre.Console](https://www.nuget.org/packages/Spectre.Console/) NuGet package.
134
82
135
-
Change the layout by adding a call to <xref:System.CommandLine.Help.HelpBuilder.CustomizeLayout%2A?displayProperty=nameWithType>:
83
+
Define a custom action that performs some extra logic before and after calling the default `HelpAction`:
The preceding code requires an additional `using` directive:
140
-
141
-
```csharp
142
-
usingSpectre.Console;
143
-
```
87
+
Update the `HelpAction` defined by `RootCommand` to use the custom action:
144
88
145
-
The <xref:System.CommandLine.Help.HelpBuilder.Default?displayProperty=nameWithType> class lets you reuse pieces of existing help formatting functionality and compose them into your custom help.
--file <FILEPATH> The file to print out. [default: CustomHelp.runtimeconfig.json]
162
-
--light-mode Determines whether the background color will be black or white
163
-
--color <Black, White, Red, or Yellow> Specifies the foreground color. Choose a color that provides enough contrast
164
-
with the background color. For example, a yellow foreground can't be read
165
-
against a light mode background.
166
-
--version Show version information
167
-
-?, -h, --help Show help and usage information
168
-
```
169
-
170
-
If you want to just use a string as the replacement section text instead of formatting it with `Spectre.Console`, replace the `Prepend` code in the preceding example with the following code:
107
+
-?, -h, --help Show help and usage information
108
+
--version Show version information
109
+
--file <FILEPATH> The file to print out.
110
+
--light-mode Determines whether the background color will be black or white
111
+
--color <Black|Red|White|Yellow> Specifies the foreground color of console output [default: White]
0 commit comments