Bagikan melalui

Penyelesaian tab untuk 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.

Aplikasi yang menggunakan System.CommandLine memiliki dukungan bawaan untuk penyelesaian tab di shell tertentu. Untuk mengaktifkannya, pengguna akhir harus mengambil beberapa langkah sekali per shell. Setelah ini selesai, penyelesaian tab otomatis untuk nilai statis di aplikasi Anda, seperti nilai enum atau nilai yang ditentukan dengan memanggil System.CommandLine.Option<T>.AcceptOnlyFromAmong. Anda juga dapat menyesuaikan penyelesaian tab dengan menyediakan nilai secara dinamis pada runtime.

Aktifkan pelengkapan tab

Pada komputer tempat Anda ingin mengaktifkan penyelesaian tab, ikuti langkah-langkah ini.

Untuk .NET CLI:

Untuk aplikasi baris perintah lainnya yang dibangun di System.CommandLine:

  • dotnet-suggest Instal alat global.

  • Tambahkan skrip shim yang sesuai ke profil shell Anda. Anda mungkin perlu membuat file profil shell. Skrip shim meneruskan permintaan penyelesaian dari shell Anda ke alat dotnet-suggest, yang mendelegasikannya ke aplikasi berbasis System.CommandLine yang sesuai.

    • Untuk bash, tambahkan konten dotnet-suggest-shim.bash ke ~/.bash_profile.

    • Untuk zsh, tambahkan konten dotnet-suggest-shim.zsh ke ~/.zshrc.

    • Untuk PowerShell, tambahkan konten dotnet-suggest-shim.ps1 ke profil PowerShell Anda. Anda dapat menemukan jalur yang diharapkan ke profil PowerShell dengan menjalankan perintah berikut di konsol Anda:

      echo $profile

  • Daftarkan aplikasi dengan memanggil dotnet-suggest register --command-path $executableFilePath, di mana $executableFilePath adalah jalur ke file aplikasi yang dapat dieksekusi.

Setelah shell pengguna disiapkan dan executable terdaftar, fungsi penyelesaian otomatis akan berfungsi untuk semua aplikasi yang menggunakan System.CommandLine.

Untuk cmd.exe pada Windows (Prompt Perintah Windows) tidak ada mekanisme penyelesaian tab yang dapat dicolokkan, sehingga tidak ada skrip shim yang tersedia. Untuk shell lainnya, cari masalah GitHub yang memiliki label Area-Completions. Jika tidak menemukan masalah, Anda dapat membuka masalah baru.

Mendapatkan nilai penyelesaian tab pada run-time

Kode berikut menunjukkan aplikasi yang mengambil nilai untuk penyelesaian tab secara dinamis saat runtime. Kode mendapatkan daftar tanggal dua minggu berikutnya setelah tanggal saat ini. Daftar disediakan untuk --date opsi dengan memanggil CompletionSources.Add:

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

new DateCommand().Parse(args).Invoke();

class DateCommand : Command
{
    private Argument<string> subjectArgument = new("subject")
    {
        Description = "The subject of the appointment."
    };
    private Option<DateTime> dateOption = new("--date")
    {
        Description = "The day of week to schedule. Should be within one week."
    };

    public DateCommand() : base("schedule", "Makes an appointment for sometime in the next week.")
    {
        this.Arguments.Add(subjectArgument);
        this.Options.Add(dateOption);

        dateOption.CompletionSources.Add(ctx => {
            var today = System.DateTime.Today;
            List<CompletionItem> dates = new();
            foreach (var i in Enumerable.Range(1, 7))
            {
                var date = today.AddDays(i);
                dates.Add(new CompletionItem(
                    label: date.ToShortDateString(),
                    sortText: $"{i:2}"));
            }
            return dates;
        });

        this.SetAction(parseResult =>
        {
            Console.WriteLine($"Scheduled \"{parseResult.GetValue(subjectArgument)}\" for {parseResult.GetValue(dateOption)}");
        });
    }
}

Nilai yang ditampilkan saat tombol Tab ditekan disediakan sebagai contoh elemen CompletionItem.

dates.Add(new CompletionItem(
    label: date.ToShortDateString(),
    sortText: $"{i:2}"));

Properti berikut ini CompletionItem telah diatur:

  • Label adalah nilai penyelesaian yang akan ditampilkan.
  • SortText memastikan bahwa nilai dalam daftar disajikan dalam urutan yang benar. Ini diatur dengan mengonversi i ke string dua digit, sehingga pengurutan didasarkan pada 01, 02, 03, dan sebagainya, hingga 14. Jika Anda tidak mengatur parameter ini, pengurutan didasarkan pada Label, yang dalam contoh ini dalam format tanggal pendek dan tidak akan mengurutkan dengan benar.

Ada properti lain CompletionItem , seperti Documentation dan Detail, tetapi belum digunakan dalam System.CommandLine.

Daftar penyelesaian tab dinamis yang dibuat oleh kode ini juga muncul dalam output bantuan:

Description:
  Makes an appointment for sometime in the next week.

Usage:
  schedule <subject> [options]

Arguments:
  <subject>  The subject of the appointment.

Options:
  --date                                                                          The day of week to schedule. Should be within one week.
  <2/4/2022|2/5/2022|2/6/2022|2/7/2022|2/8/2022|2/9/2022|2/10/2022>
  --version                                                                       Show version information
  -?, -h, --help

Lihat juga

System.CommandLine ringkasan