Přizpůsobení nápovědy v aplikacích vytvořených pomocí knihovny System.Commandline
Nápovědu pro konkrétní příkaz, možnost nebo argument můžete přizpůsobit a můžete přidat nebo nahradit celé části nápovědy.
Příklady v tomto článku fungují s následující aplikací příkazového řádku:
Tento kód vyžaduje direktivu 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);
Bez přizpůsobení se vytvoří následující výstup nápovědy:
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
Přizpůsobení nápovědy pro jednu možnost nebo argument
Důležité
System.CommandLine je aktuálně ve verzi PREVIEW a tato dokumentace je určená pro verzi 2.0 beta 4.
Některé informace se týkají předběžné verze produktu, který může být podstatně změněn před vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.
Chcete-li přizpůsobit název argumentu možnosti, použijte vlastnost možnosti ArgumentHelpName . A HelpBuilder.CustomizeSymbol umožňuje přizpůsobit několik částí výstupu nápovědy pro příkaz, možnost nebo argument (Symbol je základní třída pro všechny tři typy). Pomocí CustomizeSymbolmožnosti můžete zadat:
- První text sloupce.
- Druhý text sloupce.
- Způsob, jakým je popsána výchozí hodnota.
V ukázkové aplikaci --light-mode je vysvětleno adekvátně, ale změny --file popisů možností --color budou užitečné. Argument --filelze v případě argumentu označit jako místo <FILEPATH><file>. U této --color možnosti můžete zkrátit seznam dostupných barev ve sloupci o jeden a ve sloupci 2 můžete přidat upozornění, že některé barvy nebudou s určitými pozadími fungovat.
Pokud chcete provést tyto změny, odstraňte await rootCommand.InvokeAsync(args); řádek zobrazený v předchozím kódu a přidejte na jeho místo následující kód:
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);
Aktualizovaný kód vyžaduje další using direktivy:
using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;
Aplikace teď vytvoří následující výstup nápovědy:
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
Tento výstup ukazuje, že firstColumnText parametry podporují secondColumnText obtékání slov ve sloupcích.
Přidání nebo nahrazení oddílů nápovědy
Můžete přidat nebo nahradit celý oddíl výstupu nápovědy. Předpokládejme například, že chcete do oddílu popisu přidat některé obrázky ASCII pomocí balíčku NuGet Spectre.Console .
Změňte rozložení přidáním volání HelpBuilder.CustomizeLayout do lambda předaného metodě 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);
Předchozí kód vyžaduje další using direktivu:
using Spectre.Console;
Třída System.CommandLine.Help.HelpBuilder.Default umožňuje opakovaně používat části existující nápovědy k formátování a vytvářet je do vlastní nápovědy.
Výstup nápovědy teď vypadá takto:
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
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
Pokud chcete jenom použít řetězec jako text náhradního oddílu místo jeho formátování Spectre.Console, nahraďte Prepend kód v předchozím příkladu následujícím kódem:
.Prepend(
_ => _.Output.WriteLine("**New command description section**")
