Wie Sie Hilfe in Apps anpassen, die mit der System.Commandline-Bibliothek erstellt wurden
Sie können die Hilfe für einen bestimmten Befehl, eine bestimmte Option oder ein Argument anpassen und ganze Hilfeabschnitte hinzufügen oder ersetzen.
Die Beispiele in diesem Artikel funktionieren mit der folgenden Befehlszeilenanwendung:
Für diesen Code ist eine using-Anweisung erforderlich:
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);
Ohne Anpassung wird die folgende Hilfeausgabe erstellt:
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
Anpassen der Hilfe für eine einzelne Option oder ein einzelnes Argument
Wichtig
System.CommandLine befindet sich derzeit in der VORSCHAU, und diese Dokumentation gilt für Version 2.0 Beta 4.
Einige Informationen beziehen sich auf Vorabversionen des Produkts, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.
Um den Namen des Arguments einer Option anzupassen, verwenden Sie die ArgumentHelpName-Eigenschaft der Option. Außerdem können Sie mit HelpBuilder.CustomizeSymbol mehrere Teile der Hilfeausgabe für einen Befehl, eine Option oder ein Argument anpassen (Symbol ist die Basisklasse für alle drei Typen). Mit CustomizeSymbol können Sie Folgendes angeben:
- den Text der ersten Spalte
- den Text der zweiten Spalte
- die Art und Weise, wie ein Standardwert beschrieben wird
In der Beispiel-App wird --light-mode angemessen erläutert, aber Änderungen an den Optionsbeschreibungen --file und --color sind hilfreich. Für --file kann das Argument als <FILEPATH> anstelle von <file> identifiziert werden. Für die --color-Option können Sie die Liste der verfügbaren Farben in Spalte 1 kürzen, und in Spalte 2 können Sie eine Warnung hinzufügen, dass einige Farben mit einigen Hintergründen nicht funktionieren.
Um diese Änderungen vorzunehmen, löschen Sie die im obigen Code gezeigte await rootCommand.InvokeAsync(args);-Zeile, und fügen Sie an ihrer Stelle den folgenden Code hinzu:
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);
Der aktualisierte Code erfordert zusätzliche using-Anweisungen:
using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;
Die App erzeugt nun die folgende Hilfeausgabe:
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
Diese Ausgabe zeigt, dass die Parameter firstColumnText und secondColumnText das Umschließen von Wörtern innerhalb ihrer Spalten unterstützen.
Hinzufügen oder Ersetzen von Hilfeabschnitten
Sie können einen ganzen Abschnitt der Hilfeausgabe hinzufügen oder ersetzen. Angenommen, Sie möchten dem Beschreibungsabschnitt mithilfe des NuGet-Pakets Spectre.Console ASCII Art hinzufügen.
Ändern Sie das Layout, indem Sie einen Aufruf von HelpBuilder.CustomizeLayout im Lambda hinzufügen, das an die UseHelp-Methode übergeben wird:
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);
Der vorangehende Code erfordert eine zusätzliche using-Anweisung:
using Spectre.Console;
Mit der System.CommandLine.Help.HelpBuilder.Default-Klasse können Sie Teile der vorhandenen Hilfeformatierungsfunktionen wiederverwenden und in Ihrer benutzerdefinierten Hilfe zusammenstellen.
Die Hilfeausgabe sieht nun wie folgt aus:
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
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
Wenn Sie nur eine Zeichenfolge als Ersatzabschnittstext verwenden möchten, anstatt ihn mit Spectre.Console zu formatieren, ersetzen Sie den Prepend-Code im vorherigen Beispiel durch den folgenden Code:
.Prepend(
_ => _.Output.WriteLine("**New command description section**")
