Come personalizzare la Guida nelle app compilate con la libreria System.Commandline
È possibile personalizzare la Guida per un comando, un'opzione o un argomento specifico e aggiungere o sostituire intere sezioni della Guida.
Gli esempi in questo articolo usano l'applicazione da riga di comando seguente:
Questo codice richiede una direttiva 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);
Senza personalizzazione, viene generato l'output della Guida seguente:
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
Personalizzare la Guida per un'unica opzione o argomento
Importante
System.CommandLine è attualmente in ANTEPRIMA e questa documentazione si riferisce alla versione 2.0 beta 4.
Alcune informazioni riguardano il prodotto in versione non definitiva che potrebbe essere modificato in modo sostanziale prima del rilascio. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.
Per personalizzare il nome dell'argomento di un'opzione, usare la proprietà dell'opzione ArgumentHelpName. E HelpBuilder.CustomizeSymbol consente di personalizzare diverse parti dell'output della Guida per un comando, un'opzione o un argomento (Symbol è la classe di base per tutti e tre i tipi). Con CustomizeSymbol, è possibile specificare:
- Testo della prima colonna.
- Testo della seconda colonna.
- Modalità di descrizione di un valore predefinito.
Nell'app di esempio, --light-modeviene spiegato in modo adeguato, ma le modifiche alle descrizioni delle opzioni --file e --color saranno utili. Per --file, l'argomento può essere identificato come un <FILEPATH>invece di un <file>. Per l'opzione --color, è possibile abbreviare l'elenco dei colori disponibili nella prima colonna e aggiungere un avviso che indica che alcuni colori non funzioneranno con alcuni sfondi nella seconda colonna.
Per apportare queste modifiche, eliminare la riga await rootCommand.InvokeAsync(args); mostrata nel codice precedente e aggiungere al suo posto il codice seguente:
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);
Il codice aggiornato richiede direttive using aggiuntive:
using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;
L'app produce ora l'output della Guida seguente:
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
Questo output mostra che i parametri firstColumnText e secondColumnText supportano il ritorno a capo delle parole all'interno delle colonne.
Aggiungere o sostituire sezioni della Guida
È possibile aggiungere o sostituire un'intera sezione dell'output della Guida. Si supponga, ad esempio, di voler aggiungere alcune immagini ASCII alla sezione della descrizione usando il pacchetto NuGet Spectre.Console.
Modificare il layout aggiungendo una chiamata a HelpBuilder.CustomizeLayout nell'espressione lambda passata al metodo 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);
Il codice precedente richiede una direttiva using aggiuntiva:
using Spectre.Console;
La classe System.CommandLine.Help.HelpBuilder.Default consente di riutilizzare parti della funzionalità di formattazione della Guida esistente e di comporle nella Guida personalizzata.
L'output della Guida è ora simile al seguente:
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
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
Se si vuole usare una stringa come testo della sezione di sostituzione invece di formattarla con Spectre.Console, sostituire il codice Prepend dell'esempio precedente con il codice seguente:
.Prepend(
_ => _.Output.WriteLine("**New command description section**")
