ヘルプ出力をカスタマイズする

通常、コマンド ライン アプリには、使用可能なコマンド、オプション、引数の簡単な説明を表示するオプションが用意されています。 System.CommandLineには、System.CommandLine.Help.HelpOption オプションに既定で含まれるが用意されています。 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.Symbol.Hiddenになる可能性があります。つまり、ヘルプ出力 (および入力候補) には表示されませんが、コマンド ラインで指定できます。

ヘルプのカスタマイズ

コマンドのヘルプ出力をカスタマイズするには、シンボルごとに特定のヘルプ テキストを定義し、ユーザーの使用方法をさらにわかりやすくします。

オプションの引数の名前をカスタマイズするには、オプションの 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

こちらも参照ください

System.CommandLine の概要