Yardım çıkışını özelleştirme

Komut satırı uygulamaları genellikle kullanılabilir komutların, seçeneklerin ve bağımsız değişkenlerin kısa bir açıklamasını görüntüleme seçeneği sağlar. System.CommandLine HelpOption, varsayılan olarak RootCommand seçeneklerine dahil edilen öğesini sağlar. HelpOption, , HelpNameDescriptionve tarafından Namekullanıma sunulan bilgileri ve varsayılan değer veya tamamlanma kaynakları gibi diğer özellikleri kullanarak tanımlı simgeler için yardım çıkışı oluşturur.

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>

Uygulama kullanıcıları farklı platformlarda yardım istemek için farklı yöntemlere alışkın olabilir, bu nedenle yerleşik System.CommandLine uygulamalar yardım istemenin birçok yoluna yanıt verir. Aşağıdaki komutların tümü eşdeğerdir:

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

Yardım çıkışının kullanılabilir tüm komutları, bağımsız değişkenleri ve seçenekleri göstermesi gerekmez. Bunlardan bazıları özelliği aracılığıyla gizlenebilirHidden; bu da yardım çıkışında (ve tamamlamalarda) görünmedikleri ancak komut satırında belirtilebileceği anlamına gelir.

Yardım ayarlarını özelleştirme

Her simge için belirli bir yardım metni tanımlayarak komutlar için yardım çıkışını özelleştirebilir ve kullanıcılara kullanımlarıyla ilgili daha fazla netlik sağlayabilirsiniz.

Bir seçeneğin bağımsız değişkeninin adını özelleştirmek için seçeneğin System.CommandLine.Option.HelpName özelliğini kullanın.

Örnek uygulamada, --light-mode yeterince açıklanmıştır, ancak --file ve --color seçeneği açıklamalarında yapılacak değişiklikler yararlı olacaktır. --file için bağımsız değişken <FILEPATH> olarak tanımlanabilir. Seçenek için --color kullanılabilir renklerin listesini kısaltabilirsiniz.

Bu değişiklikleri yapmak için önceki kodu aşağıdaki kodla genişletin:

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

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

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]

Çıkışa yardımcı olacak bölümler ekleyin

Yardım çıkışına ilk veya son bölümleri ekleyebilirsiniz. Örneğin, Spectre.Console NuGet paketini kullanarak açıklama bölümüne ASCII resmi eklemek istediğinizi varsayalım.

varsayılanı HelpActionçağırmadan önce ve çağırdıktan sonra bazı ek mantıklar gerçekleştiren özel bir eylem tanımlayın:

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;

    }
}

HelpAction öğesini RootCommand ile tanımlanan özel eylemi kullanmak üzere güncelleştirin.

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

Yardım çıktısı artık şu şekilde görünüyor:

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

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

Ayrıca bakınız

System.CommandLine genel bakış