Personalización de la salida de ayuda

Las aplicaciones de línea de comandos suelen proporcionar una opción para mostrar una breve descripción de los comandos, opciones y argumentos disponibles. System.CommandLine proporciona System.CommandLine.Help.HelpOption que se incluye de forma predeterminada en las opciones RootCommand . System.CommandLine. Help.HelpOption genera una salida de ayuda para símbolos definidos mediante la información expuesta por System.CommandLine.Symbol.Name, System.CommandLine.Symbol.HelpName, System.CommandLine.Symbol.Descriptiony otras propiedades, como el valor predeterminado o los orígenes de finalización.

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>

Es posible que los usuarios de la aplicación estén acostumbrados a diferentes formas de solicitar ayuda en distintas plataformas, por lo que las aplicaciones basadas en System.CommandLine responder a muchas formas de solicitar ayuda. Todos los comandos siguientes son equivalentes:

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

La salida de ayuda no muestra necesariamente todos los comandos, argumentos y opciones disponibles. Algunos de ellos pueden estar ocultos a través de la System.CommandLine.Symbol.Hidden propiedad , lo que significa que no aparecen en la salida de ayuda (y finalizaciones), pero se pueden especificar en la línea de comandos.

Personalización de ayuda

Puede personalizar la salida de ayuda para los comandos definiendo texto de ayuda específico para cada símbolo, lo que proporciona mayor claridad a los usuarios con respecto a su uso.

Para personalizar el nombre del argumento de una opción, use la propiedad de la System.CommandLine.Option.HelpName opción.

En la aplicación de ejemplo, --light-mode se explica adecuadamente, pero los cambios en las descripciones de opciones --file y --color serán útiles. Para --file, el argumento se puede identificar como .<FILEPATH> Para la --color opción, puede acortar la lista de colores disponibles.

Para realizar estos cambios, extienda el código anterior con el código siguiente:

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

La aplicación ahora genera la siguiente salida de ayuda:

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]

Añadir secciones para mejorar la salida

Puede agregar secciones iniciales o finales a la salida de ayuda. Por ejemplo, supongamos que desea agregar algunas imágenes ASCII a la sección de descripción mediante el paquete NuGet Spectre.Console .

Defina una acción personalizada que realice alguna lógica adicional antes y después de llamar al valor predeterminado 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;

    }
}

Actualice el HelpAction definido por RootCommand para usar la acción personalizada:

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;
    }
}

La salida de ayuda ahora tiene este aspecto:

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

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

Consulte también

System.CommandLine visión general