Súgókimenet testreszabása

A parancssori alkalmazások általában lehetővé teszik az elérhető parancsok, beállítások és argumentumok rövid leírását. System.CommandLine biztosítja a HelpOption szolgáltatást, amely alapértelmezés szerint szerepel a RootCommand opciók között. HelpOption a megadott szimbólumok súgókimenetét hozza létre az Name, HelpName, Description és egyéb tulajdonságok, például az alapértelmezett érték vagy a befejezési források által közzétett információk használatával.

Option<FileInfo> fileOption = new("--file")
{
    Description = "The file to print out.",
};
Option<bool> lightModeOption = new("--light-mode")
{
    Description = "Determines whether the background color will be black or white"
};
Option<ConsoleColor> foregroundColorOption = new("--color")
{
    Description = "Specifies the foreground color of console output",
    DefaultValueFactory = _ => ConsoleColor.White
};

RootCommand rootCommand = new("Read a file")
{
    fileOption,
    lightModeOption,
    foregroundColorOption
};
rootCommand.Parse("-h").Invoke();

Description:
  Read a file

Usage:
  scl [options]

Options:
  -?, -h, --help                                            Show help and usage information
  --version                                                 Show version information
  --file                                                    The file to print out.
  --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|Da  [default: White]
  rkMagenta|DarkRed|DarkYellow|Gray|Green|Magenta|Red|Whit
  e|Yellow>

Az alkalmazásfelhasználók különböző módokon kérhetnek segítséget a különböző platformokon, így a System.CommandLine beépített alkalmazások számos módon válaszolhatnak a segítségkérésre. A következő parancsok mind egyenértékűek:

dotnet --help
dotnet -h
dotnet /h
dotnet -?
dotnet /?

A súgó kimenete nem feltétlenül jeleníti meg az összes elérhető parancsot, argumentumot és beállítást. Előfordulhat, hogy néhányuk rejtve van a Hidden tulajdonságon keresztül, ami azt jelenti, hogy nem jelennek meg a súgó kimenetében (és a befejezésekben), de megadható a parancssorban.

Súgó személyre szabása

A parancsok súgókimenetét úgy szabhatja testre, hogy meghatározott súgószöveget határoz meg az egyes szimbólumokhoz, így a felhasználók könnyebben áttekinthetik a használatukat.

A beállítás argumentumának nevének testreszabásához használja a beállítás tulajdonságát System.CommandLine.Option.HelpName .

A mintaalkalmazásban --light-mode megfelelően ismertetve van, de a --file és a --color opciók leírásainak módosítása hasznos lesz. Az --fileargumentum a következőként <FILEPATH>azonosítható: . --color A beállításhoz lerövidítheti az elérhető színek listáját.

A módosítások végrehajtásához terjessze ki az előző kódot a következő kóddal:

fileOption.HelpName = "FILEPATH";
foregroundColorOption.AcceptOnlyFromAmong(
    ConsoleColor.Black.ToString(),
    ConsoleColor.White.ToString(),
    ConsoleColor.Red.ToString(),
    ConsoleColor.Yellow.ToString()
);

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

Description:
  Read a file

Usage:
  scl [options]

Options:
  -?, -h, --help                    Show help and usage information
  --version                         Show version information
  --file <FILEPATH>                 The file to print out.
  --light-mode                      Determines whether the background color will be black or white
  --color <Black|Red|White|Yellow>  Specifies the foreground color of console output [default: White]

Szakaszok hozzáadása a kimenethez

Első vagy utolsó szakaszokat is hozzáadhat a súgó kimenetéhez. 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.

Adjon meg egy egyéni műveletet, amely extra logikát hajt végre az alapértelmezett HelpActionhívás előtt és után:

internal class CustomHelpAction : SynchronousCommandLineAction
{
    private readonly HelpAction _defaultHelp;

    public CustomHelpAction(HelpAction action) => _defaultHelp = action;

    public override int Invoke(ParseResult parseResult)
    {
        Spectre.Console.AnsiConsole.Write(new FigletText(parseResult.RootCommandResult.Command.Description!));

        int result = _defaultHelp.Invoke(parseResult);

        Spectre.Console.AnsiConsole.WriteLine("Sample usage: --file input.txt");

        return result;

    }
}

Frissítse a HelpAction elemet, amelyet RootCommand definiált, egyéni művelet használatához.

for (int i = 0; i < rootCommand.Options.Count; i++)
{
    // RootCommand has a default HelpOption; update its Action.
    if (rootCommand.Options[i] is HelpOption defaultHelpOption)
    {
        defaultHelpOption.Action = new CustomHelpAction((HelpAction)defaultHelpOption.Action!);
        break;
    }
}

A segítség kimenete most így néz ki:

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

Description:
  Read a file

Usage:
  scl [options]

Options:
  -?, -h, --help                    Show help and usage information
  --version                         Show version information
  --file <FILEPATH>                 The file to print out.
  --light-mode                      Determines whether the background color will be black or white
  --color <Black|Red|White|Yellow>  Specifies the foreground color of console output [default: White]

Sample usage: --file input.txt

Lásd még

System.CommandLine áttekintés