Panduan desain

Bagian berikut menyajikan panduan untuk merancang CLI. Pikirkan apa yang diharapkan aplikasi Anda pada baris perintah seperti yang diharapkan server REST API di URL. Aturan yang konsisten untuk REST API adalah hal yang membuatnya mudah digunakan oleh pengembang aplikasi klien. Dengan cara yang sama, pengguna aplikasi baris perintah Anda akan memiliki pengalaman yang lebih baik jika desain CLI mengikuti pola umum.

Setelah Anda membuat CLI, sulit untuk mengubahnya, terutama jika pengguna Anda telah menggunakan CLI Anda dalam skrip yang mereka harapkan untuk terus berjalan.

Simbol

Perintah dan sub perintah

Jika perintah memiliki subperintah, perintah tersebut harus berfungsi sebagai area atau pengelompokan untuk subperintah, daripada menentukan tindakan. Saat memanggil aplikasi, Anda menentukan perintah pengelompokan dan salah satu subperintahnya. Misalnya, coba jalankan dotnet tool, dan Anda mendapatkan pesan kesalahan karena tool perintah hanya mengidentifikasi sekelompok subperintah terkait alat, seperti install dan list. Anda dapat menjalankan dotnet tool install, tetapi dotnet tool dengan sendirinya tidak akan lengkap.

Salah satu cara yang menentukan area membantu pengguna Anda adalah mengatur output bantuan.

Dalam CLI, sering kali ada area implisit. Misalnya, di .NET CLI, area implisit adalah proyek, dan di Docker CLI, itu adalah gambar. Akibatnya, Anda dapat menggunakan dotnet build tanpa menyertakan area. Pertimbangkan apakah CLI Anda memiliki area implisit. Jika ya, pertimbangkan apakah akan mengizinkan pengguna untuk secara opsional menyertakan atau menghilangkannya, seperti dalam docker build dan docker image build. Jika Anda secara opsional mengizinkan area implisit diketik oleh pengguna, Anda juga secara otomatis memiliki bantuan dan penyelesaian tab untuk pengelompokan perintah ini. Berikan penggunaan opsional grup implisit dengan menentukan dua perintah yang melakukan operasi yang sama.

Opsi sebagai parameter

Opsi harus menyediakan parameter ke perintah, daripada menentukan tindakan itu sendiri. Ini adalah prinsip desain yang direkomendasikan, meskipun tidak selalu diikuti oleh System.CommandLine (--help menampilkan informasi bantuan).

Penamaan

Alias pendek

Secara umum, yang terbaik adalah meminimalkan jumlah alias opsi bentuk pendek yang Anda tentukan.

Secara khusus, hindari menggunakan salah satu alias berikut secara berbeda dari penggunaan umumnya di .NET CLI dan aplikasi baris perintah .NET lainnya:

  • -i untuk --interactive.

    Opsi ini memberi sinyal kepada pengguna bahwa mereka mungkin dimintai input untuk pertanyaan yang perlu dijawab oleh perintah. Misalnya, meminta nama pengguna. CLI Anda mungkin digunakan dalam skrip, jadi berhati-hatilah dalam meminta pengguna yang belum menentukan sakelar ini.

  • -o untuk --output.

    Beberapa perintah menghasilkan file sebagai hasil dari eksekusinya. Opsi ini harus digunakan untuk membantu menentukan lokasi file tersebut. Dalam kasus di mana satu file dibuat, opsi ini harus berupa jalur file. Dalam kasus di mana banyak file dibuat, opsi ini harus menjadi jalur direktori.

  • -v untuk --verbosity.

    Perintah sering memberikan output kepada pengguna di konsol; opsi ini digunakan untuk menentukan jumlah output permintaan pengguna. Untuk informasi selengkapnya, lihat Opsi nanti --verbosity di artikel ini.

Ada juga beberapa alias dengan penggunaan umum yang terbatas pada .NET CLI. Anda dapat menggunakan alias ini untuk opsi lain di aplikasi Anda, tetapi ketahui kemungkinan kebingungan.

  • -c untuk --configuration

    Opsi ini sering mengacu pada Konfigurasi Build bernama, seperti Debug atau Release. Anda dapat menggunakan nama apa pun yang Anda inginkan untuk konfigurasi, tetapi sebagian besar alat mengharapkan salah satunya. Pengaturan ini sering digunakan untuk mengonfigurasi properti lain dengan cara yang masuk akal untuk konfigurasi tersebut Debug —misalnya, melakukan lebih sedikit pengoptimalan kode saat membangun konfigurasi. Pertimbangkan opsi ini jika perintah Anda memiliki mode operasi yang berbeda.

  • -f untuk --framework

    Opsi ini digunakan untuk memilih Satu Target Framework Moniker (TFM) untuk dijalankan, jadi jika aplikasi CLI Anda memiliki perilaku yang berbeda berdasarkan TFM mana yang dipilih, Anda harus mendukung bendera ini.

  • -p untuk --property

    Jika aplikasi Anda akhirnya memanggil MSBuild, pengguna akan sering perlu menyesuaikan panggilan tersebut dalam beberapa cara. Opsi ini memungkinkan properti MSBuild disediakan pada baris perintah dan diteruskan ke panggilan MSBuild yang mendasar. Jika aplikasi Anda tidak menggunakan MSBuild tetapi memerlukan sekumpulan pasangan kunci-nilai, pertimbangkan untuk menggunakan nama opsi yang sama ini untuk memanfaatkan ekspektasi pengguna.

  • -r untuk --runtime

    Jika aplikasi Anda dapat berjalan pada runtime yang berbeda, atau memiliki logika khusus runtime, pertimbangkan untuk mendukung opsi ini sebagai cara menentukan Pengidentifikasi Runtime. Jika aplikasi Anda mendukung --runtime, pertimbangkan untuk mendukung --os dan --arch juga. Opsi ini memungkinkan Anda menentukan hanya bagian OS atau arsitektur dari RID, sementara bagian yang tidak ditentukan akan otomatis ditentukan berdasarkan platform saat ini. Untuk mengetahui informasi selengkapnya, lihat dotnet publish.

Nama singkat

Buat nama untuk perintah, opsi, dan argumen sesingkat dan mudah dieja. Misalnya, jika class cukup jelas, jangan buat perintah classification.

Nama dengan huruf kecil

Tentukan nama hanya dalam huruf kecil, kecuali Anda bisa membuat alias menggunakan huruf besar agar perintah atau opsi menjadi tidak peka terhadap huruf besar atau kecil.

Nama kasus Kebab

Gunakan kebab case untuk membedakan kata-kata. Contohnya, --additional-probing-path.

Pluralisasi

Dalam aplikasi, konsistenlah dalam penggunaan kata jamak. Misalnya, jangan mencampur nama jamak dan tunggal untuk opsi yang dapat memiliki beberapa nilai (aritas maksimum lebih besar dari satu):

Nama opsi Konsistensi
--additional-probing-paths dan --sources ✔️
--additional-probing-path dan --source ✔️
--additional-probing-paths dan --source ❌
--additional-probing-path dan --sources ❌

Kata kerja vs. kata benda

Gunakan kata kerja daripada kata benda untuk perintah yang merujuk ke tindakan (yang tanpa sub-perintah di bawahnya), misalnya: dotnet workload remove, bukan dotnet workload removal. Dan gunakan kata benda daripada kata kerja untuk opsi, misalnya: --configuration, bukan --configure.

Opsi --verbosity

System.CommandLine aplikasi biasanya menawarkan --verbosity opsi yang menentukan berapa banyak output yang dikirim ke konsol. Berikut adalah lima pengaturan standar:

  • Q[uiet]
  • M[inimal]
  • N[ormal]
  • D[etailed]
  • Diag[nostic]

Ini adalah nama standar, tetapi aplikasi yang ada terkadang digunakan Silent sebagai pengganti Quiet, dan Trace, Debug, atau Verbose menggantikan Diagnostic.

Setiap aplikasi menentukan kriterianya sendiri yang menentukan apa yang ditampilkan di setiap tingkatan. Biasanya, aplikasi hanya memerlukan tiga tingkat:

  • Tenang
  • Biasa
  • Diagnostik

Jika aplikasi tidak memerlukan lima tingkat yang berbeda, opsi tersebut masih harus menentukan lima pengaturan yang sama. Dalam hal ini, Minimal dan Normal akan menghasilkan output yang sama, dan Detailed juga Diagnostic akan sama. Ini memungkinkan pengguna Anda untuk hanya mengetik apa yang mereka kenal, dan yang paling cocok akan digunakan.

Harapan untuk Quiet adalah bahwa tidak ada output yang ditampilkan di konsol. Namun, jika aplikasi menawarkan mode interaktif, aplikasi harus melakukan salah satu hal berikut:

  • Tampilkan perintah untuk input ketika --interactive ditentukan, bahkan jika --verbosity adalah Quiet.
  • Melarang penggunaan --verbosity Quiet dan --interactive bersama-sama.

Jika tidak, aplikasi akan menunggu input tanpa memberi tahu pengguna apa yang ditunggunya. Tampaknya aplikasi Anda membeku, dan pengguna tidak akan tahu aplikasi sedang menunggu input.

Jika Anda menentukan alias, gunakan -v untuk --verbosity dan buat -v tanpa argumen sebagai alias untuk --verbosity Diagnostic. Gunakan -q untuk --verbosity Quiet.

Konvensi .NET CLI dan POSIX

.NET CLI tidak secara konsisten mengikuti semua konvensi POSIX.

Garis ganda

Beberapa perintah dalam .NET CLI memiliki implementasi khusus dari token tanda hubung ganda. Dalam kasus dotnet run, dotnet watch, dan dotnet tool run, token yang mengikuti -- diteruskan ke aplikasi yang sedang dijalankan oleh perintah. Contohnya:

dotnet run --project ./myapp.csproj -- --message "Hello world!"
                                    ^^

Dalam contoh ini, --project opsi diteruskan ke dotnet run perintah, dan --message opsi dengan argumennya diteruskan sebagai opsi baris perintah ke myapp saat dijalankan.

Token -- tidak selalu diperlukan untuk meneruskan opsi ke aplikasi yang Anda jalankan dengan menggunakan dotnet run. Tanpa garis miring ganda, perintah dotnet run secara otomatis meneruskan opsi apa pun yang tidak diakui berlaku untuk dotnet run atau MSBuild ke aplikasi yang sedang dijalankan. Jadi baris perintah berikut ini setara karena dotnet run tidak mengenali argumen dan opsi:

dotnet run -- quotes read --delay 0 --fg-color red
dotnet run quotes read --delay 0 --fg-color red

Ketiadaan pemisah opsi-ke-argumen

.NET CLI tidak mendukung konvensi POSIX yang memungkinkan Anda menghilangkan pemisah saat Anda menentukan alias opsi karakter tunggal.

Beberapa argumen tanpa mengulangi nama opsi

.NET CLI tidak menerima beberapa argumen untuk satu opsi tanpa mengulangi nama opsi.

Opsi Boolean

Dalam .NET CLI, beberapa opsi Boolean menghasilkan perilaku yang sama ketika Anda menggunakan false sama seperti ketika Anda menggunakan true. Perilaku ini menghasilkan ketika kode .NET CLI yang mengimplementasikan opsi hanya memeriksa keberadaan atau tidak adanya opsi, mengabaikan nilai. Contohnya adalah --no-restore untuk dotnet build perintah . Lewati --no-restore false dan operasi pemulihan akan dilewatkan seperti saat Anda menentukan --no-restore true atau --no-restore.

Kasus Kebab

Dalam beberapa kasus, .NET CLI tidak menggunakan kasus kebab untuk nama perintah, opsi, atau argumen. Misalnya, ada opsi .NET CLI yang dinamai --additionalprobingpath alih-alih --additional-probing-path.

Lihat juga

  • Last updated on