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**")

Viz také

System.CommandLine Přehled