Anpassen der Hilfeausgabe

Befehlszeilen-Apps bieten in der Regel eine Möglichkeit, eine kurze Beschreibung der verfügbaren Befehle, Optionen und Argumente anzuzeigen. System.CommandLine stellt System.CommandLine.Help.HelpOption bereit, dass standardmäßig in den RootCommand-Optionen enthalten ist. System.CommandLine.Help.HelpOption generiert Hilfeausgaben für definierte Symbole unter Verwendung der Informationen, die durch System.CommandLine.Symbol.Name, System.CommandLine.Symbol.HelpName, System.CommandLine.Symbol.Description und andere Eigenschaften wie Standardwert oder Vervollständigungsquellen zur Verfügung gestellt werden.

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>

App-Benutzer sind möglicherweise daran gewöhnt, auf verschiedenen Plattformen unterschiedliche Möglichkeiten zur Anforderung von Hilfe zu nutzen, sodass Apps, die auf System.CommandLine basieren, auf viele verschiedene Arten von Hilfsanfragen reagieren. Die folgenden Befehle sind alle gleichwertig:

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

Die Hilfeausgabe zeigt nicht unbedingt alle verfügbaren Befehle, Argumente und Optionen an. Einige von ihnen können über die -Eigenschaft System.CommandLine.Symbol.Hidden sein, d.h. sie erscheinen nicht in der Hilfeausgabe (und den Vervollständigungen), können aber in der Kommandozeile angegeben werden.

Anpassen der Hilfe

Sie können die Hilfeausgabe für Befehle anpassen, indem Sie spezifischen Hilfetext für jedes Symbol definieren und Benutzern weitere Klarheit hinsichtlich ihrer Verwendung bieten.

Verwenden Sie die Eigenschaften der Option System.CommandLine.Option.HelpName, um den Namen des Arguments einer Option anzupassen.

In der Beispiel-App wird --light-mode angemessen erläutert, aber Änderungen an den Optionen und Beschreibungen von --file und --color sind hilfreich. Das Argument kann für --file als <FILEPATH> identifiziert werden. Für die --color Option können Sie die Liste der verfügbaren Farben kürzen.

Um diese Änderungen vorzunehmen, erweitern Sie den vorherigen Code mit dem folgenden Code:

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

Die App erzeugt jetzt die folgende Hilfeausgabe:

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]

Hinzufügen von Abschnitten zur Unterstützung der Ausgabe

Sie können der Hilfeausgabe erste oder letzte Abschnitte hinzufügen. Angenommen, Sie möchten dem Beschreibungsbereich mithilfe des NuGet-Pakets Spectre.Console einige ASCII-Grafiken hinzufügen.

Definieren Sie eine benutzerdefinierte Aktion, die vor und nach dem Aufrufen des Standardwerts HelpActioneine zusätzliche Logik ausführt:

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;

    }
}

Aktualisieren Sie das durch HelpAction definierte RootCommand, um die angepasste Aktion zu verwenden:

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

Die Hilfeausgabe sieht nun wie folgt aus:

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

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

Siehe auch

System.CommandLine Überblick