Penguraian dan pemanggilan dalam System.CommandLine

2025-06-19

Penting

System.CommandLine saat ini dalam PRATINJAU, dan dokumentasi ini untuk versi 2.0 beta 5. Beberapa informasi berkaitan dengan produk prarilis yang mungkin dimodifikasi secara substansial sebelum dirilis. Microsoft tidak memberikan jaminan, tersurat maupun tersirat, sehubungan dengan informasi yang diberikan di sini.

System.CommandLine memberikan pemisahan yang jelas antara penguraian baris perintah dan pemanggilan tindakan. Proses penguraian bertanggung jawab untuk mengurai input baris perintah dan membuat System.CommandLine.ParseResult objek yang berisi nilai yang diurai (dan mengurai kesalahan). Proses pemanggilan tindakan bertanggung jawab untuk memanggil tindakan yang terkait dengan perintah, opsi, atau direktif yang diurai (argumen tidak dapat memiliki tindakan).

Dalam contoh berikut dari tutorial Mulai menggunakan System.CommandLine kami, ParseResult dibuat dengan mengurai input baris perintah. Tidak ada tindakan yang ditentukan atau dipanggil:

using System.CommandLine;
using System.CommandLine.Parsing;

namespace scl;

class Program
{
    static int Main(string[] args)
    {
        Option<FileInfo> fileOption = new("--file")
        {
            Description = "The file to read and display on the console."
        };

        RootCommand rootCommand = new("Sample app for System.CommandLine");
        rootCommand.Options.Add(fileOption);

        ParseResult parseResult = rootCommand.Parse(args);
        if (parseResult.GetValue(fileOption) is FileInfo parsedFile)
        {
            ReadFile(parsedFile);
            return 0;
        }
        foreach (ParseError parseError in parseResult.Errors)
        {
            Console.Error.WriteLine(parseError.Message);
        }
        return 1;
    }

    static void ReadFile(FileInfo file)
    {
        foreach (string line in File.ReadLines(file.FullName))
        {
            Console.WriteLine(line);
        }
    }
}

Tindakan dipanggil ketika perintah tertentu (atau direktif, atau opsi) berhasil diurai. Tindakan ini adalah delegasi yang mengambil System.CommandLine.ParseResult parameter dan mengembalikan int kode keluar (tindakan asinkron juga tersedia)). Kode keluar dikembalikan oleh System.CommandLine.Parsing.ParseResult.Invoke metode dan dapat digunakan untuk menunjukkan apakah perintah berhasil dijalankan atau tidak.

Dalam contoh berikut dari tutorial Mulai menggunakan System.CommandLine , tindakan didefinisikan untuk perintah root dan dipanggil setelah mengurai input baris perintah:

using System.CommandLine;

namespace scl;

class Program
{
    static int Main(string[] args)
    {
        Option<FileInfo> fileOption = new("--file")
        {
            Description = "The file to read and display on the console."
        };

        RootCommand rootCommand = new("Sample app for System.CommandLine");
        rootCommand.Options.Add(fileOption);

        rootCommand.SetAction(parseResult =>
        {
            FileInfo parsedFile = parseResult.GetValue(fileOption);
            ReadFile(parsedFile);
            return 0;
        });

        ParseResult parseResult = rootCommand.Parse(args);
        return parseResult.Invoke();
    }

    static void ReadFile(FileInfo file)
    {
        foreach (string line in File.ReadLines(file.FullName))
        {
            Console.WriteLine(line);
        }
    }
}

Beberapa simbol bawaan, seperti System.CommandLine.Help.HelpOption, , System.CommandLine.VersionOptionatau System.CommandLine.Completions.SuggestDirective, dilengkapi dengan tindakan yang telah ditentukan sebelumnya. Simbol-simbol ini secara otomatis ditambahkan ke perintah akar saat Anda membuatnya, dan ketika Anda memanggil System.CommandLine.Parsing.ParseResult, simbol tersebut "berfungsi dengan sendirinya." Penggunaan tindakan memungkinkan Anda untuk fokus pada logika aplikasi Anda, sementara pustaka menangani parsing dan pemanggilan tindakan untuk simbol bawaan. Jika mau, Anda dapat tetap pada proses penguraian dan tidak menentukan tindakan apa pun (seperti pada contoh pertama di atas).

ParseResult

Jenisnya System.CommandLine.Parsing.ParseResult adalah kelas yang mewakili hasil penguraian input baris perintah. Anda perlu menggunakannya untuk mendapatkan nilai yang diurai untuk opsi dan argumen (tidak peduli apakah Anda menggunakan tindakan atau tidak). Anda juga dapat memeriksa apakah ada kesalahan penguraian atau token yang tidak cocok.

GetValue

Metode ini System.CommandLine.Parsing.ParseResult.GetValue<T> memungkinkan Anda untuk mengambil nilai opsi dan argumen:

int integer = parseResult.GetValue(delayOption);
string? message = parseResult.GetValue(messageOption);

Anda juga bisa mendapatkan nilai berdasarkan nama, tetapi ini mengharuskan Anda menentukan jenis nilai yang ingin Anda dapatkan.

Contoh berikut menggunakan penginisialisasi koleksi C# untuk membuat perintah akar:

RootCommand rootCommand = new("Parameter binding example")
{
    new Option<int>("--delay")
    {
        Description = "An option whose argument is parsed as an int."
    },
    new Option<string>("--message")
    {
        Description = "An option whose argument is parsed as a string."
    }
};

Kemudian menggunakan GetValue metode untuk mendapatkan nilai berdasarkan nama:

rootCommand.SetAction(parseResult =>
{
    int integer = parseResult.GetValue<int>("--delay");
    string? message = parseResult.GetValue<string>("--message");

    DisplayIntAndString(integer, message);
});

Kelebihan beban GetValue ini mendapatkan nilai yang diurai atau default untuk nama simbol yang ditentukan, dalam konteks perintah yang diurai (bukan seluruh pohon simbol). Ini menerima nama simbol, bukan alias.

Kesalahan penguraian

Properti System.CommandLine.Parsing.ParseResult.Errors berisi daftar kesalahan penguraian yang terjadi selama proses penguraian. Setiap kesalahan diwakili oleh System.CommandLine.Parsing.ParseError objek, yang berisi informasi tentang kesalahan, seperti pesan kesalahan dan token yang menyebabkan kesalahan.

Saat Anda memanggil System.CommandLine.Parsing.ParseResult.Invoke metode , metode mengembalikan kode keluar yang menunjukkan apakah penguraian berhasil atau tidak. Jika ada kesalahan penguraian, kode keluar bukan nol, dan semua kesalahan penguraian dicetak ke kesalahan standar.

Jika Anda tidak memanggil metode System.CommandLine.Parsing.ParseResult.Invoke, Anda perlu menangani kesalahan sendiri, misalnya dengan mencetak kesalahan tersebut.

foreach (ParseError parseError in parseResult.Errors)
{
    Console.Error.WriteLine(parseError.Message);
}
return 1;

Token yang tidak cocok

Properti System.CommandLine.Parsing.ParseResult.UnmatchedTokens berisi daftar token yang diurai tetapi tidak cocok dengan perintah, opsi, atau argumen yang dikonfigurasi.

Daftar token yang tidak cocok berguna dalam perintah yang berperilaku seperti pembungkus. Perintah pembungkus mengambil sekumpulan token dan meneruskannya ke perintah atau aplikasi lain. Perintah sudo di Linux adalah contoh. Dibutuhkan nama pengguna untuk meniru diikuti oleh perintah untuk dijalankan. Contohnya:

sudo -u admin apt update

Baris perintah ini akan menjalankan perintah apt update sebagai pengguna admin.

Untuk menerapkan perintah pembungkus seperti ini, atur properti System.CommandLine.Command.TreatUnmatchedTokensAsErrors perintah ke false. System.CommandLine.Parsing.ParseResult.UnmatchedTokens Kemudian properti akan berisi semua argumen yang tidak secara eksplisit milik perintah. Dalam contoh sebelumnya, ParseResult.UnmatchedTokens akan berisi apt token dan update .

Tindakan

Tindakan adalah fungsi delegasi yang dipanggil saat perintah (atau opsi atau direktif) berhasil diparsing. Mereka mengambil parameter System.CommandLine.ParseResult dan mengembalikan kode keluaran int atau Task<int>. Kode keluar digunakan untuk menunjukkan apakah tindakan berhasil dijalankan atau tidak.

System.CommandLine menyediakan kelas System.CommandLine.CommandLineAction dasar abstrak dan dua kelas turunan: System.CommandLine.SynchronousCommandLineAction dan System.CommandLine.AsynchronousCommandLineAction. Yang pertama digunakan untuk tindakan sinkron yang mengembalikan int kode keluar, sementara yang terakhir digunakan untuk tindakan asinkron yang mengembalikan Task<int> kode keluar.

Anda tidak perlu membuat jenis turunan untuk menentukan tindakan. Anda dapat menggunakan System.CommandLine.Command.SetAction metode untuk mengatur tindakan untuk perintah. Aksi sinkron bisa berupa delegasi yang memerlukan System.CommandLine.ParseResult parameter dan memberikan int kode keluar. Tindakan asinkron dapat menjadi sebagai delegasi yang mengambil parameter System.CommandLine.ParseResult dan CancellationToken dan mengembalikan Task<int>.

rootCommand.SetAction(parseResult =>
{
    FileInfo parsedFile = parseResult.GetValue(fileOption);
    ReadFile(parsedFile);
    return 0;
});

Tindakan asinkron

Tindakan sinkron dan asinkron tidak boleh dicampur dalam aplikasi yang sama. Jika Anda ingin menggunakan tindakan asinkron, aplikasi Anda harus asinkron dari atas ke bawah. Ini berarti bahwa semua tindakan harus asinkron, dan Anda harus menggunakan metode System.CommandLine.Command.SetAction yang menerima delegasi yang mengembalikan kode keluar Task<int>. Selain itu, CancellationToken yang diteruskan ke delegasi aksi perlu diteruskan ke semua metode yang dapat dibatalkan, seperti operasi I/O berkas atau permintaan jaringan.

Selain itu, Anda perlu memastikan bahwa System.CommandLine.Parsing.ParseResult.InvokeAsync metode digunakan alih-alih System.CommandLine.Parsing.ParseResult.Invoke. Metode ini asinkron dan mengembalikan Task<int> kode keluar. Ini juga menerima parameter opsional CancellationToken yang dapat digunakan untuk membatalkan tindakan.

Kode sebelumnya menggunakan SetAction kelebihan beban yang mendapatkan ParseResult dan CancellationToken bukan hanya ParseResult:

static Task<int> Main(string[] args)
{
    Option<string> urlOption = new("--url", "A URL.");
    RootCommand rootCommand = new("Handle termination example") { urlOption };

    rootCommand.SetAction((ParseResult parseResult, CancellationToken cancellationToken) =>
    {
        string? urlOptionValue = parseResult.GetValue(urlOption);
        return DoRootCommand(urlOptionValue, cancellationToken);
    });

    return rootCommand.Parse(args).InvokeAsync();
}

public static async Task<int> DoRootCommand(
    string? urlOptionValue, CancellationToken cancellationToken)
{
    using HttpClient httpClient = new();

    try
    {
        await httpClient.GetAsync(urlOptionValue, cancellationToken);
        return 0;
    }
    catch (OperationCanceledException)
    {
        await Console.Error.WriteLineAsync("The operation was aborted");
        return 1;
    }
}

Batas waktu penghentian proses

System.CommandLine.CommandLineConfiguration.ProcessTerminationTimeout memungkinkan sinyal dan penanganan penghentian proses (Ctrl+C, SIGINT, SIGTERM) melalui CancellationToken yang diteruskan ke setiap tindakan asinkron selama pemanggilan. Ini diaktifkan secara default (2 detik), tetapi Anda dapat mengaturnya ke null untuk menonaktifkannya.

Saat diaktifkan, jika tindakan tidak selesai dalam batas waktu yang ditentukan, proses akan dihentikan. Ini berguna untuk menangani penghentian dengan anggun, misalnya, dengan menyimpan status sebelum proses dihentikan.

Untuk menguji kode sampel dari paragraf sebelumnya, jalankan perintah dengan URL yang akan memakan waktu sejenak untuk dimuat, dan sebelum selesai memuat, tekan Ctrl+C. Pada macOS tekan Command+Period(.). Contohnya:

testapp --url https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis

The operation was aborted

Kode keluaran

Kode keluar adalah nilai bilangan bulat yang dikembalikan oleh tindakan yang menunjukkan keberhasilan atau kegagalannya. Menurut konvensi, kode keluar menandakan 0 keberhasilan, sementara nilai bukan nol menunjukkan kesalahan. Penting untuk menentukan kode keluar yang bermakna dalam aplikasi Anda untuk mengomunikasikan status eksekusi perintah dengan jelas.

Setiap metode SetAction memiliki pemanggilan berlebih yang menerima delegasi untuk mengembalikan kode keluar int, di mana kode keluar perlu disediakan secara eksplisit, dan pemanggilan berlebih yang mengembalikan 0.

static int Main(string[] args)
{
    Option<int> delayOption = new("--delay");
    Option<string> messageOption = new("--message");

    RootCommand rootCommand = new("Parameter binding example")
    {
        delayOption,
        messageOption
    };

    rootCommand.SetAction(parseResult =>
    {
        Console.WriteLine($"--delay = {parseResult.GetValue(delayOption)}");
        Console.WriteLine($"--message = {parseResult.GetValue(messageOption)}");
        // Value returned from the action delegate is the exit code.
        return 100;
    });

    return rootCommand.Parse(args).Invoke();
}

Lihat juga

Cara menyesuaikan penguraian dan validasi di System.CommandLine System.CommandLine ikhtisar

Bagikan melalui