Help aanpassen in apps die zijn gebouwd met de System.Commandline-bibliotheek
U kunt hulp aanpassen voor een specifieke opdracht, optie of argument en u kunt hele Help-secties toevoegen of vervangen.
De voorbeelden in dit artikel werken met de volgende opdrachtregeltoepassing:
Voor deze code is een using instructie vereist:
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);
Zonder aanpassing wordt de volgende Help-uitvoer geproduceerd:
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
Hulp aanpassen voor één optie of argument
Belangrijk
System.CommandLine bevindt zich momenteel in PREVIEW en deze documentatie is voor versie 2.0 beta 4.
Sommige informatie heeft betrekking op voorlopige versie van het product dat aanzienlijk kan worden gewijzigd voordat het wordt vrijgegeven. Microsoft biedt geen enkele expliciete of impliciete garanties met betrekking tot de informatie die hier wordt verstrekt.
Als u de naam van het argument van een optie wilt aanpassen, gebruikt u de eigenschap van ArgumentHelpName de optie. En HelpBuilder.CustomizeSymbol hiermee kunt u verschillende onderdelen van de Help-uitvoer aanpassen voor een opdracht, optie of argument (Symbol is de basisklasse voor alle drie de typen). Met CustomizeSymbolkunt u het volgende opgeven:
- De eerste kolomtekst.
- De tweede kolomtekst.
- De manier waarop een standaardwaarde wordt beschreven.
In de voorbeeld-app --light-mode wordt adequaat uitgelegd, maar wijzigingen in de --file beschrijvingen en --color opties zijn handig. Voor --file, het argument kan worden geïdentificeerd als een <FILEPATH> in plaats van <file>. Voor de --color optie kunt u de lijst met beschikbare kleuren in kolom één inkorten en in kolom twee kunt u een waarschuwing toevoegen dat sommige kleuren niet met sommige achtergronden werken.
Als u deze wijzigingen wilt aanbrengen, verwijdert u de await rootCommand.InvokeAsync(args); regel die in de voorgaande code wordt weergegeven en voegt u de volgende code toe:
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);
Voor de bijgewerkte code zijn aanvullende using instructies vereist:
using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;
De app produceert nu de volgende Help-uitvoer:
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
Deze uitvoer laat zien dat de firstColumnText en secondColumnText parameters tekstterugloop in hun kolommen ondersteunen.
Help-secties toevoegen of vervangen
U kunt een hele sectie van de Help-uitvoer toevoegen of vervangen. Stel dat u een aantal ASCII-illustraties wilt toevoegen aan de beschrijvingssectie met behulp van het NuGet-pakket Spectre.Console .
Wijzig de indeling door een aanroep toe te voegen aan HelpBuilder.CustomizeLayout de lambda die is doorgegeven aan de UseHelp methode:
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);
Voor de voorgaande code is een aanvullende using instructie vereist:
using Spectre.Console;
Met System.CommandLine.Help.HelpBuilder.Default de klasse kunt u delen van bestaande help-opmaakfunctionaliteit hergebruiken en deze samenstellen in uw aangepaste Help-informatie.
De Help-uitvoer ziet er nu als volgt uit:
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
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
Als u alleen een tekenreeks wilt gebruiken als de vervangende sectietekst in plaats van deze Spectre.Consoleop te maken, vervangt u de Prepend code in het voorgaande voorbeeld door de volgende code:
.Prepend(
_ => _.Output.WriteLine("**New command description section**")
