Súgó testreszabása a System.Commandline könyvtárral létrehozott alkalmazásokban

Testre szabhatja egy adott parancshoz, beállításhoz vagy argumentumhoz tartozó súgót, és egész súgószakaszokat adhat hozzá vagy cserélhet le.

A cikkben szereplő példák a következő parancssori alkalmazással működnek:

Ehhez a kódhoz egy irányelvre using van szükség:

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);

Testreszabás nélkül a következő súgókimenet jön létre:

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

Súgó testreszabása egyetlen beállításhoz vagy argumentumhoz

A beállítás argumentumának nevének testreszabásához használja a beállítás tulajdonságát ArgumentHelpName . És HelpBuilder.CustomizeSymbol lehetővé teszi a súgó kimenetének több részének testreszabását egy parancshoz, beállításhoz vagy argumentumhoz (Symbol ez mindhárom típus alaposztálya). A következővel CustomizeSymboladhatja meg:

• Az első oszlop szövege.
• A második oszlop szövege.
• Az alapértelmezett érték leírása.

A mintaalkalmazásban megfelelően ismertetjük, --light-mode de a beállítások leírásának --color--file módosítása hasznos lesz. Ebben --fileaz esetben az argumentum a következő helyett <FILEPATH><file>azonosítható. --color A beállításhoz lerövidítheti az első oszlopban elérhető színek listáját, a második oszlopban pedig figyelmeztetést adhat hozzá, hogy egyes színek nem fognak működni bizonyos háttérrel.

A módosítások végrehajtásához törölje az await rootCommand.InvokeAsync(args); előző kódban látható sort, és adja hozzá a helyére a következő kódot:

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);

A frissített kódhoz további using irányelvek szükségesek:

using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;

Az alkalmazás most a következő súgókimenetet állítja elő:

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

Ez a kimenet azt mutatja, hogy a paraméterek támogatják secondColumnText a firstColumnText szóburkolást az oszlopaikban.

Súgószakaszok hozzáadása vagy cseréje

A súgó kimenetének egy teljes szakaszát hozzáadhatja vagy lecserélheti. Tegyük fel például, hogy a Spectre.Console NuGet-csomag használatával ascii-művészetet szeretne hozzáadni a leírási szakaszhoz.

Módosítsa az elrendezést úgy, hogy HelpBuilder.CustomizeLayout hozzáad egy hívást a metódusnak átadott lambdában 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);

Az előző kódhoz további using irányelvre van szükség:

using Spectre.Console;

Az System.CommandLine.Help.HelpBuilder.Default osztály segítségével újra felhasználhatja a meglévő súgóformázási funkciók egy részét, és egyéni súgóba írhatja őket.

A súgó kimenete így néz ki:

  ____                       _                __   _   _
 |  _ \    ___    __ _    __| |     __ _     / _| (_) | |   ___
 | |_) |  / _ \  / _` |  / _` |    / _` |   | |_  | | | |  / _ \
 |  _ <  |  __/ | (_| | | (_| |   | (_| |   |  _| | | | | |  __/
 |_| \_\  \___|  \__,_|  \__,_|    \__,_|   |_|   |_| |_|  \___|


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

Ha csak egy sztringet szeretne helyettesítő szakaszszövegként használni a formázás Spectre.Consolehelyett, cserélje le az Prepend előző példában szereplő kódot a következő kódra:

.Prepend(
    _ => _.Output.WriteLine("**New command description section**")

Lásd még

System.CommandLine Áttekintés