Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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.Description
y 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