Настройка справки

Приложения командной строки обычно предоставляют возможность отображения краткого описания доступных команд, параметров и аргументов. 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.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]

Добавьте разделы для улучшения выходных данных

Вы можете добавить первые или последние части в вывод справки. Например, предположим, что вы хотите добавить в раздел описания ASCII-арт, используя пакет NuGet Spectre.Console.

Определите пользовательское действие, которое выполняет дополнительную логику до и после вызова по умолчанию 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 Обзор