Přizpůsobení výstupu nápovědy

Aplikace příkazového řádku obvykle poskytují možnost zobrazit stručný popis dostupných příkazů, možností a argumentů. System.CommandLine poskytuje System.CommandLine.Help.HelpOption, která je ve výchozím nastavení zahrnuta v možnostech RootCommand. System.CommandLine.Help.HelpOption generuje výstup nápovědy pro definované symboly pomocí informací zveřejněných System.CommandLine.Symbol.Name, System.CommandLine.Symbol.HelpName, System.CommandLine.Symbol.Description a dalších vlastností, jako jsou výchozí hodnota nebo zdroje dokončení.

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>

Uživatelé aplikací můžou být zvyklí na různé způsoby, jak požádat o pomoc na různých platformách, takže aplikace založené na System.CommandLine mnoha způsobech žádosti o pomoc reagují. Všechny následující příkazy jsou ekvivalentní:

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

Výstup nápovědy nemusí nutně zobrazovat všechny dostupné příkazy, argumenty a možnosti. Některé z nich můžou být skryté prostřednictvím System.CommandLine.Symbol.Hidden vlastnosti, což znamená, že se nezobrazují ve výstupu nápovědy (a dokončení), ale dají se zadat na příkazovém řádku.

Přizpůsobení nápovědy

Výstup nápovědy pro příkazy můžete přizpůsobit definováním konkrétního textu nápovědy pro jednotlivé symboly, což uživatelům poskytne další přehlednost týkající se jejich použití.

Chcete-li přizpůsobit název argumentu možnosti, použijte vlastnost možnosti System.CommandLine.Option.HelpName .

V ukázkové aplikaci je --light-mode vždy patřičně vysvětlen, ale změny popisů možností --file a --color budou užitečné. Pro --file, argument lze identifikovat jako <FILEPATH>. U této --color možnosti můžete zkrátit seznam dostupných barev.

Pokud chcete provést tyto změny, rozšiřte předchozí kód o následující kód:

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

Aplikace teď vytvoří následující výstup nápovědy:

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]

Přidat oddíly pro pomoc s výstupem

Do výstupu nápovědy můžete přidat první nebo poslední oddíly. Předpokládejme například, že chcete do oddílu popisu přidat některé obrázky ASCII pomocí balíčku NuGet Spectre.Console .

Definujte vlastní akci, která provádí určitou logiku před a po volání výchozí HelpAction akce.

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;

    }
}

Aktualizujte definovanou HelpActionRootCommand tak, aby používala vlastní akci:

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

Výstup nápovědy teď vypadá takto:

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

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

Viz také

System.CommandLine přehled