System.Commandline kitaplığıyla oluşturulan uygulamalarda yardım özelleştirme

Belirli bir komut, seçenek veya bağımsız değişken için yardımı özelleştirebilir ve yardım bölümlerinin tamamını ekleyebilir veya değiştirebilirsiniz.

Bu makaledeki örnekler aşağıdaki komut satırı uygulamasıyla çalışır:

Bu kod bir using yönerge gerektirir:

using System.CommandLine;

var fileOption = new Option<FileInfo>(
    "--file",
    description: "The file to print out.",
    getDefaultValue: () => new FileInfo("scl.runtimeconfig.json"));
var lightModeOption = new Option<bool> (
    "--light-mode",
    description: "Determines whether the background color will be black or white");
var foregroundColorOption = new Option<ConsoleColor>(
    "--color",
    description: "Specifies the foreground color of console output",
    getDefaultValue: () => ConsoleColor.White);

var rootCommand = new RootCommand("Read a file")
{
    fileOption,
    lightModeOption,
    foregroundColorOption
};

rootCommand.SetHandler((file, lightMode, color) =>
    {
        Console.BackgroundColor = lightMode ? ConsoleColor.White: ConsoleColor.Black;
        Console.ForegroundColor = color;
        Console.WriteLine($"--file = {file?.FullName}");
        Console.WriteLine($"File contents:\n{file?.OpenText().ReadToEnd()}");
    },
    fileOption,
    lightModeOption,
    foregroundColorOption);

await rootCommand.InvokeAsync(args);

Özelleştirme olmadan aşağıdaki yardım çıkışı oluşturulur:

Description:
  Read a file

Usage:
  scl [options]

Options:
  --file <file>                                               The file to print out. [default: scl.runtimeconfig.json]
  --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|Dark  [default: White]
  Magenta|DarkRed|DarkYellow|Gray|Green|Magenta|Red|White|Ye
  llow>
  --version                                                   Show version information
  -?, -h, --help                                              Show help and usage information

Tek bir seçenek veya bağımsız değişken için yardımı özelleştirme

Bir seçeneğin bağımsız değişkeninin adını özelleştirmek için seçeneğin ArgumentHelpName özelliğini kullanın. Ayrıca HelpBuilder.CustomizeSymbol , bir komut, seçenek veya bağımsız değişken için yardım çıkışının birkaç bölümünü özelleştirmenizi sağlar (Symbol üç türün de temel sınıfıdır). ile CustomizeSymbolşunları belirtebilirsiniz:

• İlk sütun metni.
• İkinci sütun metni.
• Varsayılan değerin açıklandığı şekilde.

Örnek uygulamada, --light-mode yeterince açıklanmıştır, ancak ve --color seçeneği açıklamalarında yapılan değişiklikler --file yararlı olacaktır. için --filebağımsız değişkeni yerine <file>olarak <FILEPATH> tanımlanabilir. Seçenek için --color , birinci sütundaki kullanılabilir renklerin listesini kısaltabilir ve ikinci sütunda bazı renklerin bazı arka planlarla çalışmayacağını belirten bir uyarı ekleyebilirsiniz.

Bu değişiklikleri yapmak için, önceki kodda gösterilen satırı silin await rootCommand.InvokeAsync(args); ve yerine aşağıdaki kodu ekleyin:

fileOption.ArgumentHelpName = "FILEPATH";

var parser = new CommandLineBuilder(rootCommand)
        .UseDefaults()
        .UseHelp(ctx =>
        {
            ctx.HelpBuilder.CustomizeSymbol(foregroundColorOption,
                firstColumnText: "--color <Black, White, Red, or Yellow>",
                secondColumnText: "Specifies the foreground color. " +
                    "Choose a color that provides enough contrast " +
                    "with the background color. " + 
                    "For example, a yellow foreground can't be read " +
                    "against a light mode background.");
        })
        .Build();

parser.Invoke(args);

Güncelleştirilmiş kod ek using yönergeler gerektirir:

using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;

Uygulama şimdi aşağıdaki yardım çıkışını üretir:

Description:
  Read a file

Usage:
  scl [options]

Options:
  --file <FILEPATH>                       The file to print out. [default: CustomHelp.runtimeconfig.json]
  --light-mode                            Determines whether the background color will be black or white
  --color <Black, White, Red, or Yellow>  Specifies the foreground color. Choose a color that provides enough contrast
                                          with the background color. For example, a yellow foreground can't be read
                                          against a light mode background.
  --version                               Show version information
  -?, -h, --help                          Show help and usage information

Bu çıkış, ve secondColumnText parametrelerinin firstColumnText sütunları içinde sözcük kaydırmayı desteklediğini gösterir.

Yardım bölümlerini ekleme veya değiştirme

Yardım çıkışının tüm bölümünü ekleyebilir veya değiştirebilirsiniz. Örneğin, Spectre.Console NuGet paketini kullanarak açıklama bölümüne ASCII resmi eklemek istediğinizi varsayalım.

yöntemine geçirilen UseHelp lambda'ya HelpBuilder.CustomizeLayout bir çağrı ekleyerek düzeni değiştirin:

fileOption.ArgumentHelpName = "FILEPATH";

var parser = new CommandLineBuilder(rootCommand)
        .UseDefaults()
        .UseHelp(ctx =>
        {
            ctx.HelpBuilder.CustomizeSymbol(foregroundColorOption,
                firstColumnText: "--color <Black, White, Red, or Yellow>",
                secondColumnText: "Specifies the foreground color. " +
                    "Choose a color that provides enough contrast " +
                    "with the background color. " +
                    "For example, a yellow foreground can't be read " +
                    "against a light mode background.");
            ctx.HelpBuilder.CustomizeLayout(
                _ =>
                    HelpBuilder.Default
                        .GetLayout()
                        .Skip(1) // Skip the default command description section.
                        .Prepend(
                            _ => Spectre.Console.AnsiConsole.Write(
                                new FigletText(rootCommand.Description!))
                ));
        })
        .Build();

await parser.InvokeAsync(args);

Yukarıdaki kod ek using bir yönerge gerektirir:

using Spectre.Console;

sınıfı, System.CommandLine.Help.HelpBuilder.Default mevcut yardım biçimlendirme işlevselliğinin parçalarını yeniden kullanmanıza ve bunları özel yardımınızda oluşturmanıza olanak tanır.

Yardım çıkışı şu şekilde görünür:

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


Usage:
  scl [options]

Options:
  --file <FILEPATH>                       The file to print out. [default: CustomHelp.runtimeconfig.json]
  --light-mode                            Determines whether the background color will be black or white
  --color <Black, White, Red, or Yellow>  Specifies the foreground color. Choose a color that provides enough contrast
                                          with the background color. For example, a yellow foreground can't be read
                                          against a light mode background.
  --version                               Show version information
  -?, -h, --help                          Show help and usage information

yerine bölüm metni Spectre.Consoleolarak yalnızca bir dize kullanmak istiyorsanız, önceki örnekteki Prepend kodu aşağıdaki kodla değiştirin:

.Prepend(
    _ => _.Output.WriteLine("**New command description section**")

Ayrıca bkz.

System.CommandLine Genel bakış