如何在使用 System.Commandline 程式庫建置的應用程式中自訂說明
您可以自訂特定命令、選項或引數的說明，也可以新增或取代整個說明區段。
本文中的範例適用於下列命令列應用程式：
此程式碼需要 using 指示詞：
using System.CommandLine;
var fileOption = new Option<FileInfo>(
"--file",
description: "The file to print out.",
getDefaultValue: () => new FileInfo("scl.runtimeconfig.json"));
var lightModeOption = new Option<bool> (
"--light-mode",
description: "Determines whether the background color will be black or white");
var foregroundColorOption = new Option<ConsoleColor>(
"--color",
description: "Specifies the foreground color of console output",
getDefaultValue: () => ConsoleColor.White);
var rootCommand = new RootCommand("Read a file")
{
fileOption,
lightModeOption,
foregroundColorOption
};
rootCommand.SetHandler((file, lightMode, color) =>
{
Console.BackgroundColor = lightMode ? ConsoleColor.White: ConsoleColor.Black;
Console.ForegroundColor = color;
Console.WriteLine($"--file = {file?.FullName}");
Console.WriteLine($"File contents:\n{file?.OpenText().ReadToEnd()}");
},
fileOption,
lightModeOption,
foregroundColorOption);
await rootCommand.InvokeAsync(args);
若未自訂，會產生下列說明輸出：
Description:
Read a file
Usage:
scl [options]
Options:
--file <file> The file to print out. [default: scl.runtimeconfig.json]
--light-mode Determines whether the background color will be black or
white
--color Specifies the foreground color of console output
<Black|Blue|Cyan|DarkBlue|DarkCyan|DarkGray|DarkGreen|Dark [default: White]
Magenta|DarkRed|DarkYellow|Gray|Green|Magenta|Red|White|Ye
llow>
--version Show version information
-?, -h, --help Show help and usage information
自訂單一選項或引數的說明
重要
System.CommandLine 目前為預覽版，而此文件適用於版本 2.0 搶鮮版 (Beta) 4。
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
若要自訂選項引數的名稱，請使用選項的 ArgumentHelpName 屬性。 而 HelpBuilder.CustomizeSymbol 可讓您自訂命令、選項或引數 (Symbol 是這三種類型的基底類別) 說明輸出的數個部分。 您可以利用 CustomizeSymbol，指定：
- 第一個資料行文字。
- 第二的資料行文字。
- 描述預設值的方式。
在範例應用程式中，--color 已有適當說明，但變更 --light-mode 和 --file 選項描述會很有幫助。 針對 --file，可以將引數識別為 <FILEPATH>，而不是 <file>。 針對 --color 選項，您可以縮短第一資料行的可用色彩清單，並在第二個資料行新增警告，指出某些色彩不適用於某些背景。
若要進行這些變更，請刪除上述程式碼中顯示的 await rootCommand.InvokeAsync(args); 行，並在其位置新增下列程式碼：
fileOption.ArgumentHelpName = "FILEPATH";
var parser = new CommandLineBuilder(rootCommand)
.UseDefaults()
.UseHelp(ctx =>
{
ctx.HelpBuilder.CustomizeSymbol(foregroundColorOption,
firstColumnText: "--color <Black, White, Red, or Yellow>",
secondColumnText: "Specifies the foreground color. " +
"Choose a color that provides enough contrast " +
"with the background color. " +
"For example, a yellow foreground can't be read " +
"against a light mode background.");
})
.Build();
parser.Invoke(args);
更新的程式碼需要額外的 using 指示詞：
using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;
應用程式現在會產生下列說明輸出：
Description:
Read a file
Usage:
scl [options]
Options:
--file <FILEPATH> The file to print out. [default: CustomHelp.runtimeconfig.json]
--light-mode Determines whether the background color will be black or white
--color <Black, White, Red, or Yellow> Specifies the foreground color. Choose a color that provides enough contrast
with the background color. For example, a yellow foreground can't be read
against a light mode background.
--version Show version information
-?, -h, --help Show help and usage information
此輸出顯示 firstColumnText 和 secondColumnText 參數支援在其資料行內自動換行。
新增或取代說明區段
您可以新增或取代說明輸出的整個區段。 例如，假設您想要使用 Spectre.Console NuGet 套件，將一些 ASCII 文字圖新增至描述區段。
在傳遞給 UseHelp 方法的 Lambda 中，新增 對 HelpBuilder.CustomizeLayout 的呼叫，以變更配置：
fileOption.ArgumentHelpName = "FILEPATH";
var parser = new CommandLineBuilder(rootCommand)
.UseDefaults()
.UseHelp(ctx =>
{
ctx.HelpBuilder.CustomizeSymbol(foregroundColorOption,
firstColumnText: "--color <Black, White, Red, or Yellow>",
secondColumnText: "Specifies the foreground color. " +
"Choose a color that provides enough contrast " +
"with the background color. " +
"For example, a yellow foreground can't be read " +
"against a light mode background.");
ctx.HelpBuilder.CustomizeLayout(
_ =>
HelpBuilder.Default
.GetLayout()
.Skip(1) // Skip the default command description section.
.Prepend(
_ => Spectre.Console.AnsiConsole.Write(
new FigletText(rootCommand.Description!))
));
})
.Build();
await parser.InvokeAsync(args);
上述程式碼需要額外的 using 指示詞：
using Spectre.Console;
System.CommandLine.Help.HelpBuilder.Default 類別可讓您重複使用現有的說明格式設定功能片段，並撰寫成您的自訂說明。
說明輸出現在看起來像這樣：
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
Usage:
scl [options]
Options:
--file <FILEPATH> The file to print out. [default: CustomHelp.runtimeconfig.json]
--light-mode Determines whether the background color will be black or white
--color <Black, White, Red, or Yellow> Specifies the foreground color. Choose a color that provides enough contrast
with the background color. For example, a yellow foreground can't be read
against a light mode background.
--version Show version information
-?, -h, --help Show help and usage information
如果您想要只使用字串作為取代區段文字，而不是透過 Spectre.Console 設定格式，請將上述範例中的 Prepend 程式碼取代為下列程式碼：
.Prepend(
_ => _.Output.WriteLine("**New command description section**")
