komutlarını, seçeneklerini ve bağımsız değişkenlerini tanımlama System.CommandLine

Bu makalede, kitaplıkla System.CommandLine oluşturulan komut satırı uygulamalarında komutların, seçeneklerin ve bağımsız değişkenlerin nasıl tanımlanacağı açıklanmaktadır. Bu teknikleri gösteren eksiksiz bir uygulama oluşturmak için kullanmaya başlama System.CommandLineöğreticisine bakın.

Komut satırı uygulamasının komutlarını, seçeneklerini ve bağımsız değişkenlerini tasarlama hakkında yönergeler için bkz . Tasarım kılavuzu.

Kök komutu tanımlama

Her komut satırı uygulamasının, yürütülebilir dosyanın kendisine başvuran bir kök komutu vardır. Alt komutları, seçenekleri veya bağımsız değişkenleri olmayan bir uygulamanız varsa kodunuzu çağırmak için en basit durum şöyle görünür:

using System.CommandLine;

class Program
{
    static async Task Main(string[] args)
    {
        var rootCommand = new RootCommand("Sample command-line app");

        rootCommand.SetHandler(() =>
        {
            Console.WriteLine("Hello world!");
        });

        await rootCommand.InvokeAsync(args);
    }
}

Alt komutları tanımlama

Komutlarda alt komutlar veya fiiller olarak bilinen alt komutlar olabilir ve ihtiyacınız olan sayıda düzeyi iç içe yerleştirebilirler. Aşağıdaki örnekte gösterildiği gibi alt komutları ekleyebilirsiniz:

var rootCommand = new RootCommand();
var sub1Command = new Command("sub1", "First-level subcommand");
rootCommand.Add(sub1Command);
var sub1aCommand = new Command("sub1a", "Second level subcommand");
sub1Command.Add(sub1aCommand);

Bu örnekteki en içteki alt komut şu şekilde çağrılabilir:

myapp sub1 sub1a

Seçenekleri tanımlama

Komut işleyicisi yönteminde genellikle parametreler bulunur ve değerler komut satırı seçeneklerinden gelebilir. Aşağıdaki örnek iki seçenek oluşturur ve bunları kök komutuna ekler. Seçenek adları, POSIX CLI'leri için tipik olan çift kısa çizgi ön eklerini içerir. Komut işleyici kodu şu seçeneklerin değerlerini görüntüler:

var delayOption = new Option<int>
    (name: "--delay",
    description: "An option whose argument is parsed as an int.",
    getDefaultValue: () => 42);
var messageOption = new Option<string>
    ("--message", "An option whose argument is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.Add(delayOption);
rootCommand.Add(messageOption);

rootCommand.SetHandler((delayOptionValue, messageOptionValue) =>
    {
        Console.WriteLine($"--delay = {delayOptionValue}");
        Console.WriteLine($"--message = {messageOptionValue}");
    },
    delayOption, messageOption);

Aşağıda bir komut satırı girişi örneği ve yukarıdaki örnek kod için elde edilen çıkış verilmişti:

myapp --delay 21 --message "Hello world!"

--delay = 21
--message = Hello world!

Genel seçenekler

Bir kerede bir komuta seçenek eklemek için, önceki örnekte gösterildiği gibi veya AddOption yöntemini kullanınAdd. Bir komuta seçenek eklemek ve tüm alt komutlarına özyinelemeli olarak aşağıdaki örnekte gösterildiği gibi yöntemini kullanın AddGlobalOption :

var delayOption = new Option<int>
    ("--delay", "An option whose argument is parsed as an int.");
var messageOption = new Option<string>
    ("--message", "An option whose argument is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.AddGlobalOption(delayOption);
rootCommand.Add(messageOption);

var subCommand1 = new Command("sub1", "First level subcommand");
rootCommand.Add(subCommand1);

var subCommand1a = new Command("sub1a", "Second level subcommand");
subCommand1.Add(subCommand1a);

subCommand1a.SetHandler((delayOptionValue) =>
    {
        Console.WriteLine($"--delay = {delayOptionValue}");
    },
    delayOption);

await rootCommand.InvokeAsync(args);

Yukarıdaki kod, kök komutuna genel bir seçenek olarak eklenir --delay ve işleyicisinde için subCommand1akullanılabilir.

Bağımsız değişkenleri tanımlama

Bağımsız değişkenler tanımlanır ve seçenekler gibi komutlara eklenir. Aşağıdaki örnek, seçenekler örneğine benzer, ancak seçenekler yerine bağımsız değişkenleri tanımlar:

var delayArgument = new Argument<int>
    (name: "delay",
    description: "An argument that is parsed as an int.",
    getDefaultValue: () => 42);
var messageArgument = new Argument<string>
    ("message", "An argument that is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.Add(delayArgument);
rootCommand.Add(messageArgument);

rootCommand.SetHandler((delayArgumentValue, messageArgumentValue) =>
    {
        Console.WriteLine($"<delay> argument = {delayArgumentValue}");
        Console.WriteLine($"<message> argument = {messageArgumentValue}");
    },
    delayArgument, messageArgument);

await rootCommand.InvokeAsync(args);

Aşağıda bir komut satırı girişi örneği ve yukarıdaki örnek kod için elde edilen çıkış verilmişti:

myapp 42 "Hello world!"

<delay> argument = 42
<message> argument = Hello world!

Önceki örnekte olduğu gibi messageArgument varsayılan değer olmadan tanımlanan bir bağımsız değişken, gerekli bir bağımsız değişken olarak değerlendirilir. Gerekli bir bağımsız değişken sağlanmazsa bir hata iletisi görüntülenir ve komut işleyicisi çağrılmaz.

Diğer adları tanımlama

Hem komutlar hem de seçenekler diğer adları destekler. öğesini çağırarak AddAliasbir seçeneğe diğer ad ekleyebilirsiniz:

var option = new Option("--framework");
option.AddAlias("-f");

Bu diğer ad göz önüne alındığında, aşağıdaki komut satırları eşdeğerdir:

myapp -f net6.0
myapp --framework net6.0

Komut diğer adları aynı şekilde çalışır.

var command = new Command("serialize");
command.AddAlias("serialise");

Bu kod aşağıdaki komut satırlarını eşdeğer hale getirir:

myapp serialize
myapp serialise

Tanımladığınız seçenek diğer adlarının sayısını en aza indirmenizi ve özellikle belirli diğer adları tanımlamaktan kaçınmanızı öneririz. Daha fazla bilgi için bkz . Kısa form diğer adları.

Gerekli seçenekler

Bir seçeneğin gerekli olmasını sağlamak için, aşağıdaki örnekte gösterildiği gibi özelliğini trueolarak ayarlayınIsRequired:

var endpointOption = new Option<Uri>("--endpoint") { IsRequired = true };
var command = new RootCommand();
command.Add(endpointOption);

command.SetHandler((uri) =>
    {
        Console.WriteLine(uri?.GetType());
        Console.WriteLine(uri?.ToString());
    },
    endpointOption);

await command.InvokeAsync(args);

Komut yardımının seçenekler bölümü seçeneğin gerekli olduğunu gösterir:

Options:
  --endpoint <uri> (REQUIRED)
  --version               Show version information
  -?, -h, --help          Show help and usage information

Bu örnek uygulamanın komut satırı içermiyorsa --endpointbir hata iletisi görüntülenir ve komut işleyicisi çağrılmaz:

Option '--endpoint' is required.

Gerekli bir seçeneğin varsayılan değeri varsa, seçeneğin komut satırında belirtilmesi gerekmez. Bu durumda, varsayılan değer gerekli seçenek değerini sağlar.

Gizli komutlar, seçenekler ve bağımsız değişkenler

Bir komutu, seçeneği veya bağımsız değişkeni desteklemek isteyebilirsiniz, ancak bulmayı kolaylaştırmaktan kaçının. Örneğin, kullanım dışı bırakılmış veya yönetim veya önizleme özelliği olabilir. IsHidden Aşağıdaki örnekte gösterildiği gibi, kullanıcıların sekme tamamlama veya yardım kullanarak bu özellikleri bulmasını önlemek için özelliğini kullanın:

var endpointOption = new Option<Uri>("--endpoint") { IsHidden = true };
var command = new RootCommand();
command.Add(endpointOption);

command.SetHandler((uri) =>
    {
        Console.WriteLine(uri?.GetType());
        Console.WriteLine(uri?.ToString());
    },
    endpointOption);

await command.InvokeAsync(args);

Bu örneğin komutunun seçenekler bölümü seçeneği atlar --endpoint .

Options:
  --version               Show version information
  -?, -h, --help          Show help and usage information

Bağımsız değişken arity'sini ayarlama

özelliğini kullanarak Arity bağımsız değişken arity değerini açıkça ayarlayabilirsiniz, ancak çoğu durumda bu gerekli değildir. System.CommandLine bağımsız değişken türünü temel alarak bağımsız değişken arity değerini otomatik olarak belirler:

Birden çok bağımsız değişken

Varsayılan olarak, bir komutu çağırdığınızda, bir seçenek adını yineleyerek maksimum arity değeri birden fazla olan bir seçenek için birden çok bağımsız değişken belirtebilirsiniz.

myapp --items one --items two --items three

Seçenek adını yinelemeden birden çok bağımsız değişkene izin vermek için trueolarak ayarlayınOption.AllowMultipleArgumentsPerToken. Bu ayar aşağıdaki komut satırını girmenizi sağlar.

myapp --items one two three

En fazla bağımsız değişken arity değeri 1 ise aynı ayarın farklı bir etkisi vardır. Bir seçeneği yinelemenize olanak tanır, ancak satırdaki yalnızca son değeri alır. Aşağıdaki örnekte, değer three uygulamaya geçirilir.

myapp --item one --item two --item three

Geçerli bağımsız değişken değerlerini listeleme

Bir seçenek veya bağımsız değişken için geçerli değerlerin listesini belirtmek için, seçenek türü olarak bir sabit listesi belirtin veya aşağıdaki örnekte gösterildiği gibi kullanın FromAmong:

var languageOption = new Option<string>(
    "--language",
    "An option that that must be one of the values of a static list.")
        .FromAmong(
            "csharp",
            "fsharp",
            "vb",
            "pwsh",
            "sql");

Aşağıda bir komut satırı girişi örneği ve yukarıdaki örnek kod için elde edilen çıkış verilmişti:

myapp --language not-a-language

Argument 'not-a-language' not recognized. Must be one of:
        'csharp'
        'fsharp'
        'vb'
        'pwsh'
        'sql'

Komut yardımının seçenekler bölümünde geçerli değerler gösterilir:

Options:
  --language <csharp|fsharp|vb|pwsh|sql>  An option that must be one of the values of a static list.
  --version                               Show version information
  -?, -h, --help                          Show help and usage information

Seçenek ve bağımsız değişken doğrulama

Bağımsız değişken doğrulama ve nasıl özelleştirileceği hakkında bilgi için Parametre bağlama makalesindeki aşağıdaki bölümlere bakın:

• Yerleşik tür ve arity bağımsız değişken doğrulaması
• Özel doğrulama ve bağlama

Ayrıca bkz.

• System.CommandLine Genel bakış
• Parametre bağlama