命令行應用程式通常會提供選項來顯示可用命令、選項和自變數的簡短描述。
System.CommandLine 會提供 System.CommandLine.Help.HelpOption ，預設包含在 RootCommand 選項中。
System.CommandLine.Help.HelpOption 使用System.CommandLine.Symbol.Name、System.CommandLine.Symbol.HelpName、System.CommandLine.Symbol.Description和其他屬性（例如預設值或完成來源）所提供的資訊，來產生已定義符號的說明輸出。
Option<FileInfo> fileOption = new("--file")
{
Description = "The file to print out.",
};
Option<bool> lightModeOption = new("--light-mode")
{
Description = "Determines whether the background color will be black or white"
};
Option<ConsoleColor> foregroundColorOption = new("--color")
{
Description = "Specifies the foreground color of console output",
DefaultValueFactory = _ => ConsoleColor.White
};
RootCommand rootCommand = new("Read a file")
{
fileOption,
lightModeOption,
foregroundColorOption
};
rootCommand.Parse("-h").Invoke();
Description:
Read a file
Usage:
scl [options]
Options:
-?, -h, --help Show help and usage information
--version Show version information
--file The file to print out.
--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|Da [default: White]
rkMagenta|DarkRed|DarkYellow|Gray|Green|Magenta|Red|Whit
e|Yellow>
應用程式使用者可能已經習慣在不同平台上以不同方式尋求協助，因此建置在 System.CommandLine 上的應用程式能夠回應多種協助請求的方式。 下列命令全都相等：
dotnet --help
dotnet -h
dotnet /h
dotnet -?
dotnet /?
說明輸出不一定會顯示所有可用的命令、參數和選項。 其中有些可能透過 屬性隱藏，這表示它們不會顯示在說明輸出中或完成時，但可以在指令行上指定。
幫助自定義
您可以為每個符號定義特定的說明文字，以進一步清晰地向用戶說明其使用方式，從而自訂命令的說明輸出。
若要自訂選項自變數的名稱，請使用選項的 System.CommandLine.Option.HelpName 屬性。
在範例應用程式中，--light-mode 已充分說明，但對 --file 和 --color 選項描述的變更會很有幫助。 針對 --file，可以將 自變數識別為 <FILEPATH>。 針對--color選項，您可以縮小可用顏色列表。
若要進行這些變更，請使用下列程式代碼擴充先前的程式代碼：
fileOption.HelpName = "FILEPATH";
foregroundColorOption.AcceptOnlyFromAmong(
ConsoleColor.Black.ToString(),
ConsoleColor.White.ToString(),
ConsoleColor.Red.ToString(),
ConsoleColor.Yellow.ToString()
);
應用程式現在會產生下列說明輸出：
Description:
Read a file
Usage:
scl [options]
Options:
-?, -h, --help Show help and usage information
--version Show version information
--file <FILEPATH> The file to print out.
--light-mode Determines whether the background color will be black or white
--color <Black|Red|White|Yellow> Specifies the foreground color of console output [default: White]
新增區段以協助輸出
您可以將第一個或最後一個區段新增至說明輸出。 例如，假設您想要使用 Spectre.Console NuGet 套件，將一些 ASCII 藝術新增至描述區段。
定義自訂動作，在呼叫預設值 HelpAction之前和之後執行一些額外的邏輯：
internal class CustomHelpAction : SynchronousCommandLineAction
{
private readonly HelpAction _defaultHelp;
public CustomHelpAction(HelpAction action) => _defaultHelp = action;
public override int Invoke(ParseResult parseResult)
{
Spectre.Console.AnsiConsole.Write(new FigletText(parseResult.RootCommandResult.Command.Description!));
int result = _defaultHelp.Invoke(parseResult);
Spectre.Console.AnsiConsole.WriteLine("Sample usage: --file input.txt");
return result;
}
}
更新由HelpAction定義的RootCommand，以使用自訂動作。
for (int i = 0; i < rootCommand.Options.Count; i++)
{
// RootCommand has a default HelpOption, we need to update its Action.
if (rootCommand.Options[i] is HelpOption defaultHelpOption)
{
defaultHelpOption.Action = new CustomHelpAction((HelpAction)defaultHelpOption.Action!);
break;
}
}
說明輸出現在看起來像這樣：
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
Description:
Read a file
Usage:
scl [options]
Options:
-?, -h, --help Show help and usage information
--version Show version information
--file <FILEPATH> The file to print out.
--light-mode Determines whether the background color will be black or white
--color <Black|Red|White|Yellow> Specifies the foreground color of console output [default: White]
Sample usage: --file input.txt
