Menyesuaikan output bantuan

Aplikasi baris perintah biasanya menyediakan opsi untuk menampilkan deskripsi singkat tentang perintah, opsi, dan argumen yang tersedia. System.CommandLine menyediakan System.CommandLine.Help.HelpOption yang secara default disertakan dalam opsi RootCommand . System.CommandLine. Help.HelpOption menghasilkan output bantuan untuk simbol yang ditentukan dengan menggunakan informasi yang diekspos oleh System.CommandLine.Symbol.Name, , System.CommandLine.Symbol.HelpNameSystem.CommandLine.Symbol.Description, dan properti lainnya seperti nilai default atau sumber penyelesaian.

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>

Pengguna aplikasi mungkin terbiasa dengan berbagai cara untuk meminta bantuan di berbagai platform, sehingga aplikasi yang dibangun di System.CommandLine mampu merespons berbagai cara permintaan bantuan. Perintah berikut ini semuanya setara:

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

Output bantuan tidak selalu menampilkan semua perintah, argumen, dan opsi yang tersedia. Beberapa dari mereka mungkin disembunyikan melalui System.CommandLine.Symbol.Hidden properti , yang berarti mereka tidak muncul dalam output bantuan (dan penyelesaian) tetapi dapat ditentukan pada baris perintah.

Kustomisasi fitur bantuan

Anda dapat menyesuaikan output bantuan untuk perintah dengan menentukan teks bantuan tertentu untuk setiap simbol, memberikan kejelasan lebih lanjut kepada pengguna mengenai penggunaannya.

Untuk mengkustomisasi nama argumen opsi, gunakan properti opsi System.CommandLine.Option.HelpName .

Dalam aplikasi sampel, --light-mode dijelaskan secara memadai, tetapi perubahan deskripsi opsi pada --file dan --color akan membantu. Untuk --file, argumen dapat diidentifikasi sebagai <FILEPATH>. Untuk opsi , --color Anda dapat mempersingkat daftar warna yang tersedia.

Untuk membuat perubahan ini, perluas kode sebelumnya dengan kode berikut:

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

Aplikasi ini sekarang menghasilkan output bantuan berikut:

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]

Tambahkan bagian untuk meningkatkan hasil

Anda dapat menambahkan bagian pertama atau terakhir ke output bantuan. Misalnya, Anda ingin menambahkan beberapa seni ASCII ke bagian deskripsi dengan menggunakan paket Spectre.Console NuGet.

Tentukan tindakan kustom yang melakukan beberapa logika tambahan sebelum dan sesudah memanggil default 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;

    }
}

Perbarui HelpAction yang ditentukan oleh RootCommand untuk menggunakan tindakan kustom.

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

Sekarang tampilan output bantuan seperti ini:

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

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

Lihat juga

System.CommandLine ringkasan