Bagikan melalui

Cara menyesuaikan penguraian dan validasi di System.CommandLine

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.

Secara default, System.CommandLine menyediakan sekumpulan pengurai bawaan yang dapat mengurai banyak jenis umum:

  • bool
  • byte dan sbyte
  • short dan ushort
  • int dan uint
  • long dan ulong
  • float dan double
  • decimal
  • DateTime dan DateTimeOffset
  • DateOnlydan TimeOnly
  • Guid
  • FileSystemInfo, FileInfo, dan DirectoryInfo
  • enum
  • berbagai array dan daftar dari jenis-jenis yang telah disebutkan

Jenis lain tidak didukung, tetapi Anda dapat membuat pengurai kustom untuk mereka. Anda juga dapat memvalidasi nilai yang diurai, yang berguna saat Anda ingin memastikan bahwa input memenuhi kriteria tertentu.

Validator

Setiap opsi, argumen, dan perintah dapat memiliki satu atau beberapa validator. Validator digunakan untuk memastikan bahwa nilai yang diurai memenuhi kriteria tertentu. Misalnya, Anda dapat memvalidasi bahwa angka positif, atau bahwa string tidak kosong. Anda juga dapat membuat validator kompleks yang memeriksa terhadap beberapa kondisi.

Setiap jenis simbol di System.CommandLine memiliki Validators properti yang berisi daftar validator. Validator dijalankan setelah input diurai, dan mereka dapat melaporkan kesalahan jika validasi gagal.

Untuk menyediakan kode validasi kustom, panggil System.CommandLine.Option.Validators.Add opsi atau argumen Anda (atau perintah), seperti yang ditunjukkan dalam contoh berikut:

Option<int> delayOption = new("--delay");
delayOption.Validators.Add(result =>
{
    if (result.GetValue(delayOption) < 1)
    {
        result.AddError("Must be greater than 0");
    }
});

System.CommandLine menyediakan sekumpulan validator bawaan yang dapat digunakan untuk memvalidasi jenis umum:

  • AcceptExistingOnly - mengonfigurasi opsi atau argumen yang diberikan untuk hanya menerima nilai yang sesuai dengan file atau direktori yang ada.
  • AcceptLegalFileNamesOnly - mengonfigurasi opsi atau argumen yang diberikan untuk hanya menerima nilai yang mewakili nama file hukum.
  • AcceptOnlyFromAmong - mengonfigurasi opsi atau argumen yang diberikan untuk hanya menerima nilai dari sekumpulan nilai tertentu.

Pengurai kustom

Pengurai kustom diperlukan untuk mengurai jenis tanpa pengurai default, seperti jenis kompleks. Mereka juga dapat digunakan untuk mengurai tipe yang didukung dengan cara yang berbeda dari pengurai bawaan.

Misalkan Anda memiliki Person jenis:

public class Person
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
}

Anda dapat membaca nilai dan membuat instans Person dalam tindakan perintah:

rootCommand.SetAction(parseResult =>
{
    Person person = new()
    {
        FirstName = parseResult.GetValue(firstNameOption),
        LastName = parseResult.GetValue(lastNameOption)
    };
    DoRootCommand(parseResult.GetValue(fileOption), person);
});

Dengan pengurai kustom, Anda bisa mendapatkan jenis kustom dengan cara yang sama seperti Anda mendapatkan nilai primitif:

Option<Person?> personOption = new("--person")
{
    Description = "An option whose argument is parsed as a Person",
    CustomParser = result =>
    {
        if (result.Tokens.Count != 2)
        {
            result.AddError("--person requires two arguments");
            return null;
        }
        return new Person
        {
            FirstName = result.Tokens.First().Value,
            LastName = result.Tokens.Last().Value
        };
    }
};

Jika Anda ingin mengurai serta memvalidasi input, gunakan CustomParser delegasi, seperti yang ditunjukkan dalam contoh berikut:

Option<int> delayOption = new("--delay")
{
    Description = "An option whose argument is parsed as an int.",
    CustomParser = result =>
    {
        if (!result.Tokens.Any())
        {
            return 42;
        }

        if (int.TryParse(result.Tokens.Single().Value, out var delay))
        {
            if (delay < 1)
            {
                result.AddError("Must be greater than 0");
            }
            return delay;
        }
        else
        {
            result.AddError("Not an int.");
            return 0; // Ignored.
        }
    }
};

Berikut adalah beberapa contoh apa yang dapat Anda lakukan dengan CustomParser yang tidak dapat Anda lakukan dengan validator:

  • Uraikan jenis string input lainnya (misalnya, uraikan "1,2,3" ke dalam int[]).
  • Aritas dinamis. Misalnya, jika Anda memiliki dua argumen yang didefinisikan sebagai array string, dan Anda harus menangani urutan string dalam input baris perintah, metode ini System.CommandLine.Parsing.ArgumentResult.OnlyTake memungkinkan Anda membagi string input secara dinamis di antara argumen.

Lihat juga