Dostosowywanie wyjścia pomocy

Aplikacje wiersza polecenia zwykle udostępniają opcję wyświetlania krótkiego opisu dostępnych poleceń, opcji i argumentów. System.CommandLine zapewnia System.CommandLine.Help.HelpOption, który jest domyślnie uwzględniany w opcjach RootCommand. System.CommandLine.Help.HelpOption generuje dane wyjściowe pomocnicze dla zdefiniowanych symboli, korzystając z informacji udostępnianych przez System.CommandLine.Symbol.Name, System.CommandLine.Symbol.HelpName, System.CommandLine.Symbol.Description oraz inne właściwości, takie jak wartość domyślna lub źródła ukończenia.

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żytkownicy aplikacji mogą być przyzwyczajeni do różnych sposobów żądania pomocy na różnych platformach, dlatego aplikacje zbudowane na System.CommandLine odpowiadają na wiele sposobów żądania pomocy. Wszystkie następujące polecenia są równoważne:

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

Dane wyjściowe pomocy nie muszą pokazywać wszystkich dostępnych poleceń, argumentów i opcji. Niektóre z nich mogą być ukryte za pośrednictwem System.CommandLine.Symbol.Hidden właściwości, co oznacza, że nie są wyświetlane w danych wyjściowych pomocy (i zakończenia), ale można je określić w wierszu polecenia.

Pomoc w dostosowywaniu

Wyniki pomocy dla poleceń można dostosować, definiując konkretny tekst pomocy dla każdego symbolu, aby zapewnić użytkownikom lepsze zrozumienie dotyczące ich użycia.

Aby dostosować nazwę argumentu opcji, użyj właściwości opcji System.CommandLine.Option.HelpName .

W przykładowej aplikacji --light-mode jest wyjaśniony wystarczająco, ale zmiany w opisach opcji --file i --color będą pomocne. W przypadku --file elementu argument można zidentyfikować jako <FILEPATH>. W przypadku --color opcji można skrócić listę dostępnych kolorów.

Aby wprowadzić te zmiany, rozszerz poprzedni kod przy użyciu następującego kodu:

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

Teraz program generuje następujący wynik pomocy:

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]

Dodaj sekcje, aby pomóc w uzyskaniu wyniku

Możesz dodać pierwsze lub ostatnie sekcje do wyjścia pomocniczego. Załóżmy na przykład, że chcesz dodać część grafiki ASCII do sekcji opisu przy użyciu pakietu NuGet Spectre.Console .

Zdefiniuj akcję niestandardową, która wykonuje dodatkową logikę, którą warto zastosować przed i po wywołaniu domyślnej funkcji HelpAction.

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;

    }
}

Zaktualizuj element HelpAction zdefiniowany przez RootCommand, aby skorzystać z niestandardowej akcji.

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

Dane wyjściowe pomocy wyglądają teraz następująco:

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

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

Zobacz także

System.CommandLine przegląd