Procedimiento para personalizar la ayuda en aplicaciones compiladas con la biblioteca System.Commandline
Puede personalizar la ayuda de un comando, una opción o un argumento específicos, y puede agregar o reemplazar secciones completas de la ayuda.
Los ejemplos de este artículo funcionan con la siguiente aplicación de línea de comandos:
Este código requiere una using directiva:
using System.CommandLine;
var fileOption = new Option<FileInfo>(
"--file",
description: "The file to print out.",
getDefaultValue: () => new FileInfo("scl.runtimeconfig.json"));
var lightModeOption = new Option<bool> (
"--light-mode",
description: "Determines whether the background color will be black or white");
var foregroundColorOption = new Option<ConsoleColor>(
"--color",
description: "Specifies the foreground color of console output",
getDefaultValue: () => ConsoleColor.White);
var rootCommand = new RootCommand("Read a file")
{
fileOption,
lightModeOption,
foregroundColorOption
};
rootCommand.SetHandler((file, lightMode, color) =>
{
Console.BackgroundColor = lightMode ? ConsoleColor.White: ConsoleColor.Black;
Console.ForegroundColor = color;
Console.WriteLine($"--file = {file?.FullName}");
Console.WriteLine($"File contents:\n{file?.OpenText().ReadToEnd()}");
},
fileOption,
lightModeOption,
foregroundColorOption);
await rootCommand.InvokeAsync(args);
Sin personalización, se genera la siguiente salida de ayuda:
Description:
Read a file
Usage:
scl [options]
Options:
--file <file> The file to print out. [default: scl.runtimeconfig.json]
--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|Dark [default: White]
Magenta|DarkRed|DarkYellow|Gray|Green|Magenta|Red|White|Ye
llow>
--version Show version information
-?, -h, --help Show help and usage information
Personalización de la ayuda de una sola opción o argumento
Importante
System.CommandLine se encuentra actualmente en versión preliminar y esta documentación es para la versión 2.0 beta 4.
Parte de la información hace referencia a la versión preliminar del producto, que puede haberse modificado sustancialmente antes de lanzar la versión definitiva. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.
Para personalizar el nombre del argumento de una opción, use la propiedad ArgumentHelpName de la opción. Además, HelpBuilder.CustomizeSymbol permite personalizar varias partes de la salida de ayuda de un comando, una opción o un argumento (Symbol es la clase base de los tres tipos). Con CustomizeSymbol, puede especificar:
- El texto de la primera columna.
- El texto de la segunda columna.
- La forma en que se describe un valor predeterminado.
En la aplicación de ejemplo, --light-mode se explica adecuadamente, pero los cambios en las descripciones de las opciones --file y --color van a ser útiles. En --file, el argumento se puede identificar como <FILEPATH> en lugar de <file>. En la opción --color, puede acortar la lista de colores disponibles en la columna uno y, en la columna dos, puede agregar una advertencia de que algunos colores no funcionan con algunos fondos.
Para realizar estos cambios, elimine la línea await rootCommand.InvokeAsync(args); que se muestra en el código anterior y agregue en su lugar el código siguiente:
fileOption.ArgumentHelpName = "FILEPATH";
var parser = new CommandLineBuilder(rootCommand)
.UseDefaults()
.UseHelp(ctx =>
{
ctx.HelpBuilder.CustomizeSymbol(foregroundColorOption,
firstColumnText: "--color <Black, White, Red, or Yellow>",
secondColumnText: "Specifies the foreground color. " +
"Choose a color that provides enough contrast " +
"with the background color. " +
"For example, a yellow foreground can't be read " +
"against a light mode background.");
})
.Build();
parser.Invoke(args);
El código actualizado requiere directivas using adicionales:
using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;
La aplicación ahora genera la siguiente salida de ayuda:
Description:
Read a file
Usage:
scl [options]
Options:
--file <FILEPATH> The file to print out. [default: CustomHelp.runtimeconfig.json]
--light-mode Determines whether the background color will be black or white
--color <Black, White, Red, or Yellow> Specifies the foreground color. Choose a color that provides enough contrast
with the background color. For example, a yellow foreground can't be read
against a light mode background.
--version Show version information
-?, -h, --help Show help and usage information
Esta salida muestra que los parámetros firstColumnText y secondColumnText admiten el ajuste de línea dentro de sus columnas.
Incorporación o sustitución de secciones de ayuda
Puede agregar o reemplazar una sección completa de la salida de la ayuda. Por ejemplo, imagine que quiere agregar alguna imagen ASCII a la sección de descripción mediante el paquete NuGet Spectre.Console.
Cambie el diseño mediante la incorporación de una llamada a HelpBuilder.CustomizeLayout en la expresión lambda pasada al método UseHelp:
fileOption.ArgumentHelpName = "FILEPATH";
var parser = new CommandLineBuilder(rootCommand)
.UseDefaults()
.UseHelp(ctx =>
{
ctx.HelpBuilder.CustomizeSymbol(foregroundColorOption,
firstColumnText: "--color <Black, White, Red, or Yellow>",
secondColumnText: "Specifies the foreground color. " +
"Choose a color that provides enough contrast " +
"with the background color. " +
"For example, a yellow foreground can't be read " +
"against a light mode background.");
ctx.HelpBuilder.CustomizeLayout(
_ =>
HelpBuilder.Default
.GetLayout()
.Skip(1) // Skip the default command description section.
.Prepend(
_ => Spectre.Console.AnsiConsole.Write(
new FigletText(rootCommand.Description!))
));
})
.Build();
await parser.InvokeAsync(args);
El código anterior requiere una directiva using adicional:
using Spectre.Console;
La clase System.CommandLine.Help.HelpBuilder.Default permite reutilizar partes de la funcionalidad de formato de ayuda existente y componerlas en la ayuda personalizada.
La salida de ayuda ahora tiene este aspecto:
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
Usage:
scl [options]
Options:
--file <FILEPATH> The file to print out. [default: CustomHelp.runtimeconfig.json]
--light-mode Determines whether the background color will be black or white
--color <Black, White, Red, or Yellow> Specifies the foreground color. Choose a color that provides enough contrast
with the background color. For example, a yellow foreground can't be read
against a light mode background.
--version Show version information
-?, -h, --help Show help and usage information
Si desea usar simplemente una cadena como texto de sección de reemplazo en lugar de aplicarle formato con Spectre.Console, reemplace el código de Prepend en el ejemplo anterior por el código siguiente:
.Prepend(
_ => _.Output.WriteLine("**New command description section**")
