Så här anpassar du hjälp i appar som har skapats med System.Commandline-biblioteket
Du kan anpassa hjälpen för ett specifikt kommando, alternativ eller argument och du kan lägga till eller ersätta hela hjälpavsnitt.
Exemplen i den här artikeln fungerar med följande kommandoradsprogram:
Den här koden kräver ett using direktiv:
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);
Utan anpassning skapas följande hjälputdata:
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
Anpassa hjälpen för ett enda alternativ eller argument
Viktigt!
System.CommandLine är för närvarande i förhandsversion och den här dokumentationen är för version 2.0 beta 4.
Viss information gäller förhandsversionsprodukt som kan ändras avsevärt innan den släpps. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, avseende informationen som visas här.
Om du vill anpassa namnet på ett alternativs argument använder du alternativets ArgumentHelpName egenskap. Och HelpBuilder.CustomizeSymbol låter dig anpassa flera delar av hjälputdata för ett kommando, alternativ eller argument (Symbol är basklassen för alla tre typerna). Med CustomizeSymbolkan du ange:
- Den första kolumntexten.
- Den andra kolumntexten.
- Hur ett standardvärde beskrivs.
I exempelappen --light-mode förklaras korrekt, men ändringar i --file alternativbeskrivningarna och --color kommer att vara till hjälp. För --filekan argumentet identifieras som en <FILEPATH> i stället för <file>. För alternativet --color kan du förkorta listan över tillgängliga färger i kolumn ett, och i kolumn två kan du lägga till en varning om att vissa färger inte fungerar med vissa bakgrunder.
Om du vill göra dessa ändringar tar du bort raden await rootCommand.InvokeAsync(args); som visas i föregående kod och lägger till följande kod på plats:
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);
Den uppdaterade koden kräver ytterligare using direktiv:
using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;
Appen genererar nu följande hjälputdata:
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
Dessa utdata visar att parametrarna firstColumnText och secondColumnText stöder ordomslutning i sina kolumner.
Lägga till eller ersätta hjälpavsnitt
Du kan lägga till eller ersätta en hel del av hjälputdata. Anta till exempel att du vill lägga till lite ASCII-konst i beskrivningsavsnittet med hjälp av NuGet-paketet Spectre.Console .
Ändra layouten genom att lägga till ett anrop till HelpBuilder.CustomizeLayout i lambda som skickas UseHelp till metoden:
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);
Föregående kod kräver ytterligare ett using direktiv:
using Spectre.Console;
Med System.CommandLine.Help.HelpBuilder.Default klassen kan du återanvända delar av befintliga hjälpformateringsfunktioner och skapa dem i din anpassade hjälp.
Hjälputdata ser nu ut så här:
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
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
Om du bara vill använda en sträng som ersättningsavsnittstext i stället för att formatera den med Spectre.Consoleersätter Prepend du koden i föregående exempel med följande kod:
.Prepend(
_ => _.Output.WriteLine("**New command description section**")
