Bagikan melalui

Cara menentukan perintah, opsi, dan argumen di System.CommandLine

  • Artikel

Penting

System.CommandLine saat ini dalam PRATINJAU, dan dokumentasi ini untuk versi 2.0 beta 4. Beberapa informasi terkait produk prarilis yang dapat diubah secara signifikan sebelum dirilis. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Artikel ini menjelaskan cara menentukan perintah, opsi, dan argumen dalam aplikasi baris perintah yang dibangun dengan System.CommandLine pustaka. Untuk membangun aplikasi lengkap yang mengilustrasikan teknik ini, lihat tutorial Mulai menggunakan System.CommandLine.

Untuk panduan tentang cara mendesain perintah, opsi, dan argumen aplikasi baris perintah, lihat Panduan desain.

Menentukan perintah akar

Setiap aplikasi baris perintah memiliki perintah root, yang mengacu pada file yang dapat dieksekusi itu sendiri. Kasus paling sederhana untuk memanggil kode Anda, jika Anda memiliki aplikasi tanpa subperintah, opsi, atau argumen, akan terlihat seperti ini:

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

Menentukan sub-perintah

Perintah dapat memiliki perintah turunan, yang dikenal sebagai subperintah atau kata kerja, dan dapat menumpuk tingkat sebanyak yang Anda butuhkan. Anda dapat menambahkan subperintah, seperti yang ditunjukkan dalam contoh berikut:

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

Sub perintah terdalam dalam contoh ini dapat dipanggil seperti ini:

myapp sub1 sub1a

Menentukan opsi

Metode handler perintah biasanya memiliki parameter, dan nilainya dapat berasal dari opsi baris perintah. Contoh berikut membuat dua opsi dan menambahkannya ke perintah root. Nama opsi mencakup awalan tanda hubung ganda, yang khas untuk POSIX CLIs. Kode handler perintah menampilkan nilai opsi tersebut:

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

Berikut adalah contoh input baris perintah dan output yang dihasilkan untuk kode contoh sebelumnya:

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

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

Opsi global

Untuk menambahkan opsi ke satu perintah sekaligus, gunakan metode Add atau AddOption seperti yang ditunjukkan dalam contoh sebelumnya. Untuk menambahkan opsi ke perintah dan secara rekursif ke semua sub-perintahnya, gunakan AddGlobalOption metode, seperti yang ditunjukkan dalam contoh berikut:

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

Kode sebelumnya ditambahkan --delay sebagai opsi global ke perintah root, dan tersedia di handler untuk subCommand1a.

Menentukan argumen

Argumen ditentukan dan ditambahkan ke perintah seperti opsi. Contoh berikut seperti contoh opsi, tetapi mendefinisikan argumen alih-alih opsi:

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

Berikut adalah contoh input baris perintah dan output yang dihasilkan untuk kode contoh sebelumnya:

myapp 42 "Hello world!"

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

Argumen yang didefinisikan tanpa nilai default, seperti messageArgument dalam contoh sebelumnya, diperlakukan sebagai argumen yang diperlukan. Pesan kesalahan ditampilkan, dan handler perintah tidak dipanggil, jika argumen yang diperlukan tidak disediakan.

Menentukan alias

Baik perintah maupun opsi mendukung alias. Anda dapat menambahkan alias ke opsi dengan memanggil AddAlias:

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

Misalnya, baris perintah berikut ini setara:

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

Alias perintah bekerja dengan cara yang sama.

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

Kode ini membuat baris perintah berikut setara:

myapp serialize
myapp serialise

Kami menyarankan agar Anda meminimalkan jumlah alias opsi yang Anda tentukan, dan hindari menentukan alias tertentu secara khusus. Untuk informasi selengkapnya, lihat Alias bentuk pendek.

Opsi yang diperlukan

Untuk membuat opsi diperlukan, atur propertinya IsRequired ke true, seperti yang ditunjukkan dalam contoh berikut:

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

Bagian opsi dari perintah membantu menunjukkan opsi diperlukan:

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

Jika baris perintah untuk aplikasi contoh ini tidak menyertakan --endpoint, pesan kesalahan ditampilkan dan penangan perintah tidak dipanggil:

Option '--endpoint' is required.

Jika opsi yang diperlukan memiliki nilai default, opsi tidak harus ditentukan pada baris perintah. Dalam hal ini, nilai default menyediakan nilai opsi yang diperlukan.

Perintah, opsi, dan argumen tersembunyi

Anda mungkin ingin mendukung perintah, opsi, atau argumen, tetapi hindari membuatnya mudah ditemukan. Misalnya, ini mungkin fitur yang tidak digunakan lagi atau administratif atau pratinjau. Gunakan IsHidden properti untuk mencegah pengguna menemukan fitur tersebut dengan menggunakan penyelesaian atau bantuan tab, seperti yang ditunjukkan dalam contoh berikut:

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

Bagian opsi dari perintah contoh ini membantu menghilangkan --endpoint opsi.

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

Atur aritas argumen

Anda dapat mengatur secara eksplisit aritas argumen dengan menggunakan Arity properti, tetapi dalam banyak kasus yang tidak diperlukan. System.CommandLine secara otomatis menentukan aritas argumen berdasarkan jenis argumen:

Jenis Argumen Aritas default
Boolean ArgumentArity.ZeroOrOne
Tipe koleksi ArgumentArity.ZeroOrMore
Segala sesuatu yang lain ArgumentArity.ExactlyOne

Beberapa argumen

Secara default, saat Anda memanggil perintah, Anda dapat mengulangi nama opsi untuk menentukan beberapa argumen untuk opsi yang memiliki aritas maksimum lebih besar dari satu.

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

Untuk mengizinkan beberapa argumen tanpa mengulangi nama opsi, atur Option.AllowMultipleArgumentsPerToken ke true. Pengaturan ini memungkinkan Anda memasukkan baris perintah berikut.

myapp --items one two three

Pengaturan yang sama memiliki efek yang berbeda jika aritas argumen maksimum adalah 1. Ini memungkinkan Anda untuk mengulangi opsi tetapi hanya mengambil nilai terakhir pada baris. Dalam contoh berikut, nilai three akan diteruskan ke perintah.

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

Mencantumkan nilai argumen yang valid

Untuk menentukan daftar nilai yang valid untuk opsi atau argumen, tentukan enum sebagai jenis opsi atau gunakan FromAmong, seperti yang ditunjukkan dalam contoh berikut:

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");

Berikut adalah contoh input baris perintah dan output yang dihasilkan untuk kode contoh sebelumnya:

myapp --language not-a-language

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

Bagian opsi dari perintah membantu memperlihatkan nilai yang valid:

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

Validasi opsi dan argumen

Untuk informasi tentang validasi argumen dan cara menyesuaikannya, lihat bagian berikut dalam artikel Pengikatan parameter:

Lihat juga