Personalizar saída de ajuda

Os aplicativos de linha de comando geralmente fornecem uma opção para exibir uma breve descrição dos comandos, opções e argumentos disponíveis. System.CommandLine fornece HelpOption, que está incluído nas opções RootCommand por padrão. HelpOption Gera saída de ajuda para símbolos definidos usando as informações expostas por Name, HelpName, Descriptione outras propriedades, como valor padrão ou fontes de conclusão.

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>

Os utilizadores de aplicações podem estar habituados a diferentes formas de solicitar ajuda em diferentes plataformas, pelo que as aplicações baseadas em System.CommandLine respondem a muitas formas de solicitar ajuda. Os seguintes comandos são todos equivalentes:

dotnet --help
dotnet -h
dotnet /h
dotnet -?
dotnet /?

A ajuda apresentada não mostra necessariamente todos os comandos, argumentos e opções disponíveis. Alguns deles podem estar ocultos através da propriedade, o que significa que não aparecem na saída de ajuda (e completamentos), mas podem ser especificados na linha de comando.

Personalização da ajuda

Você pode personalizar a saída de ajuda para comandos definindo texto de ajuda específico para cada símbolo, fornecendo mais clareza aos usuários em relação ao seu uso.

Para personalizar o nome do argumento de uma opção, use a propriedade da System.CommandLine.Option.HelpName opção.

No aplicativo de exemplo, --light-mode é explicado adequadamente, mas as alterações nas descrições das opções --file e --color serão úteis. Para --file, o argumento pode ser identificado como um <FILEPATH>. Para a --color opção, você pode encurtar a lista de cores disponíveis.

Para fazer essas alterações, estenda o código anterior com o seguinte código:

fileOption.HelpName = "FILEPATH";
foregroundColorOption.AcceptOnlyFromAmong(
    ConsoleColor.Black.ToString(),
    ConsoleColor.White.ToString(),
    ConsoleColor.Red.ToString(),
    ConsoleColor.Yellow.ToString()
);

A aplicação agora produz a seguinte saída de ajuda:

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]

Adicionar seções para melhorar o resultado

Você pode adicionar a primeira ou a última seção à saída da ajuda. Por exemplo, suponha que você queira adicionar alguma arte ASCII à seção de descrição usando o pacote NuGet do Spectre.Console .

Defina uma ação personalizada que execute alguma lógica extra antes e depois de chamar o padrão 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;

    }
}

Atualize o HelpAction definido por RootCommand para usar a ação personalizada:

for (int i = 0; i < rootCommand.Options.Count; i++)
{
    // RootCommand has a default HelpOption; update its Action.
    if (rootCommand.Options[i] is HelpOption defaultHelpOption)
    {
        defaultHelpOption.Action = new CustomHelpAction((HelpAction)defaultHelpOption.Action!);
        break;
    }
}

A saída da ajuda agora tem esta aparência:

  ____                       _                __   _   _
 |  _ \    ___    __ _    __| |     __ _     / _| (_) | |   ___
 | |_) |  / _ \  / _` |  / _` |    / _` |   | |_  | | | |  / _ \
 |  _ <  |  __/ | (_| | | (_| |   | (_| |   |  _| | | | | |  __/
 |_| \_\  \___|  \__,_|  \__,_|    \__,_|   |_|   |_| |_|  \___|

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

Ver também

System.CommandLine Visão geral