Guide pratique pour personnaliser l’aide dans les applications générées avec la bibliothèque System.Commandline
Vous pouvez personnaliser l’aide d’une commande, d’une option ou d’un argument spécifique, et vous pouvez ajouter ou remplacer des sections d’aide entières.
Les exemples de cet article fonctionnent avec l’application en ligne de commande suivante :
Ce code nécessite une directive using :
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);
Sans personnalisation, la sortie d’aide suivante est générée :
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
Personnaliser l’aide pour une seule option ou un seul argument
Important
System.CommandLine est actuellement une PRÉVERSION et cette documentation concerne la version 2.0 beta 4.
Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.
Pour personnaliser le nom de l’argument d’une option, utilisez la propriété ArgumentHelpName de l’option. De plus, HelpBuilder.CustomizeSymbol vous permet de personnaliser plusieurs parties de la sortie de l’aide pour une commande, une option ou un argument (Symbol est la classe de base des trois types). Avec CustomizeSymbol, vous pouvez spécifier :
- Le texte de la première colonne.
- Le texte de la deuxième colonne.
- La façon dont une valeur par défaut est décrite.
Dans l’exemple d’application, --light-mode est expliqué de manière appropriée, mais les changements apportés aux descriptions des options --file et --color seront utiles. Pour --file, l’argument peut être identifié en tant que <FILEPATH> au lieu de <file>. Pour l’option --color, vous pouvez raccourcir la liste des couleurs disponibles dans la première colonne. Dans la deuxième colonne, vous pouvez ajouter un avertissement indiquant que certaines couleurs ne sont pas compatibles avec certains arrière-plans.
Pour apporter ces changements, supprimez la ligne await rootCommand.InvokeAsync(args); indiquée dans le code précédent, puis ajoutez à la place le code suivant :
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);
Le code mis à jour nécessite des directives using supplémentaires :
using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;
L’application produit désormais la sortie d’aide suivante :
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
Cette sortie montre que les paramètres firstColumnText et secondColumnText prennent en charge le retour automatique à la ligne dans leurs colonnes.
Ajouter ou remplacer des sections d’aide
Vous pouvez ajouter ou remplacer une section entière de la sortie d’aide. Par exemple, supposons que vous souhaitiez ajouter une illustration ASCII à la section de description en utilisant le package NuGet Spectre.Console.
Changez la disposition en ajoutant un appel à HelpBuilder.CustomizeLayout dans le lambda passé à la méthode 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);
Le code précédent nécessite une directive using supplémentaire :
using Spectre.Console;
La classe System.CommandLine.Help.HelpBuilder.Default vous permet de réutiliser des éléments de la fonctionnalité de mise en forme de l’aide existante, et de les composer pour produire votre aide personnalisée.
La sortie de l’aide ressemble désormais à ceci :
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
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 vous souhaitez utiliser uniquement une chaîne en tant que texte de section de remplacement au lieu de lui appliquer une mise en forme avec Spectre.Console, remplacez le code Prepend dans l’exemple précédent par le code suivant :
.Prepend(
_ => _.Output.WriteLine("**New command description section**")
