Gambaran umum sintaks baris perintah untuk System.CommandLine

Artikel
06/08/2023

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 sintaks baris perintah yang dikenali oleh System.CommandLine. Informasi ini akan berguna bagi pengguna serta pengembang aplikasi baris perintah .NET, termasuk .NET CLI.

Token

System.CommandLine mengurai input baris perintah ke dalam token, yang merupakan string yang dibatasi oleh spasi. Misalnya. perhatikan baris perintah berikut:

dotnet tool install dotnet-suggest --global --verbosity quiet

Masukan ini diuraikan oleh aplikasi dotnet menjadi token tool, install, dotnet-suggest, --global, --verbosity, dan quiet.

Token ditafsirkan sebagai perintah, opsi, atau argumen. Aplikasi baris perintah yang sedang dipanggil menentukan bagaimana token setelah yang pertama diinterpretasikan. Tabel berikut ini memperlihatkan cara System.CommandLine menginterpretasikan contoh sebelumnya:

Token	Diurai sebagai
`tool`	Subperintah
`install`	Subperintah
`dotnet-suggest`	Argumen untuk perintah penginstalan
`--global`	Opsi untuk perintah penginstalan
`--verbosity`	Opsi untuk perintah penginstalan
`quiet`	Argumen untuk opsi `--verbosity`

Token dapat berisi spasi jika diapit dalam tanda kutip ("). Berikut contohnya:

dotnet tool search "ef migrations add"

Perintah

Perintah dalam input baris perintah adalah token yang menentukan tindakan atau menentukan sekelompok tindakan terkait. Contohnya:

Dalam dotnet run, run merupakan perintah yang menentukan tindakan.
Dalam dotnet tool install, install merupakan perintah yang menentukan tindakan, dan tool merupakan perintah yang menentukan sekelompok perintah terkait. Ada perintah terkait alat lainnya, seperti tool uninstall, tool list, dan tool update.

Perintah akar

Perintah akar adalah perintah yang menentukan nama aplikasi yang dapat dieksekusi. Misalnya, perintah dotnet menentukan dotnet.exe dapat dieksekusi.

Subperintah

Sebagian besar aplikasi baris perintah mendukung subperintah, juga dikenal sebagai kata kerja. Misalnya, perintah dotnet memiliki subperintah run yang Anda panggil dengan memasukkan dotnet run.

Subperintah dapat memiliki subperintah mereka sendiri. Dalam dotnet tool install, install merupakan subperintah dari tool.

Opsi

Opsi adalah parameter bernama yang dapat diteruskan ke perintah. POSIX CLIs biasanya mengawali nama opsi dengan dua tanda hubung (--). Contoh berikut menunjukkan dua opsi:

dotnet tool update dotnet-suggest --verbosity quiet --global
                                  ^---------^       ^------^

Seperti yang diilustrasikan dalam contoh ini, nilai opsi mungkin eksplisit (quiet untuk --verbosity) atau implisit (tidak ada yang mengikuti --global). Opsi yang tidak memiliki nilai yang ditentukan biasanya adalah parameter Boolean yang default ke true jika opsi ditentukan pada baris perintah.

Untuk beberapa aplikasi baris perintah Windows, Anda dapat mengidentifikasi opsi dengan menggunakan garis miring jarak antar baris (/) dengan nama opsi. Contohnya:

msbuild /version
        ^------^

System.CommandLine mendukung konvensi awalan POSIX dan Windows. Saat Anda mengonfigurasi opsi, tentukan nama opsi termasuk awalannya.

Argumen

Argumen adalah nilai yang diteruskan ke opsi atau perintah. Contoh berikut menunjukkan argumen untuk opsi verbosity dan argumen untuk perintah build.

dotnet tool update dotnet-suggest --verbosity quiet --global
                                              ^---^

dotnet build myapp.csproj
             ^----------^

Argumen dapat memiliki nilai default yang berlaku jika tidak ada argumen yang disediakan secara eksplisit. Misalnya, banyak opsi secara implisit merupakan parameter Boolean dengan default true saat nama opsi ada di baris perintah. Contoh baris perintah berikut ini setara:

dotnet tool update dotnet-suggest --global
                                  ^------^

dotnet tool update dotnet-suggest --global true
                                  ^-----------^

Beberapa opsi membutuhkan argumen. Misalnya di .NET CLI, --output memerlukan argumen nama folder. Jika argumen tidak disediakan, perintah gagal.

Argumen dapat memiliki jenis yang diharapkan, dan System.CommandLine menampilkan pesan kesalahan jika argumen tidak dapat diurai ke dalam jenis yang diharapkan. Misalnya, kesalahan perintah berikut karena "senyap" bukan salah satu nilai yang valid untuk --verbosity:

dotnet build --verbosity silent

Cannot parse argument 'silent' for option '-v' as expected type 'Microsoft.DotNet.Cli.VerbosityOptions'. Did you mean one of the following?
Detailed
Diagnostic
Minimal
Normal
Quiet

Argumen juga memiliki harapan tentang berapa banyak nilai yang dapat diberikan. Contoh disediakan di bagian argumen aritas.

Urutan opsi dan argumen

Anda dapat memberikan opsi sebelum argumen atau argumen sebelum opsi pada baris perintah. Perintah berikut ini setara:

dotnet add package System.CommandLine --prerelease
dotnet add package --prerelease System.CommandLine

Bagian tersebut dapat ditentukan dalam urutan apa pun. Perintah berikut ini setara:

dotnet add package System.CommandLine --prerelease --no-restore --source https://api.nuget.org/v3/index.json
dotnet add package System.CommandLine --source https://api.nuget.org/v3/index.json --no-restore --prerelease

Ketika ada beberapa argumen, urutan itu penting. Perintah berikut belum tentu setara:

myapp argument1 argument2
myapp argument2 argument1

Perintah ini meneruskan daftar dengan nilai yang sama ke kode pengendali perintah, tetapi urutan nilainya berbeda, yang dapat menghasilkan hasil yang berbeda.

Alias

Di POSIX dan Windows, wajar bagi beberapa perintah dan opsi untuk memiliki alias. Ini biasanya formulir pendek yang lebih mudah diketik. Alias juga dapat digunakan untuk tujuan lain, seperti untuk mensimulasikan ketidakpekaan huruf besar/kecil dan untuk mendukung ejaan kata alternatif.

Bentuk pendek POSIX biasanya memiliki tanda hubung jarak antar baris tunggal diikuti oleh satu karakter. Perintah berikut ini setara:

dotnet build --verbosity quiet
dotnet build -v quiet

Standar GNU merekomendasikan alias otomatis. Artinya, Anda dapat memasukkan bagian mana pun dari perintah bentuk panjang atau nama opsi dan itu akan diterima. Perilaku ini akan membuat baris perintah berikut setara:

dotnet publish --output ./publish
dotnet publish --outpu ./publish
dotnet publish --outp ./publish
dotnet publish --out ./publish
dotnet publish --ou ./publish
dotnet publish --o ./publish

System.CommandLine tidak mendukung alias otomatis.

Sensitivitas huruf besar/besar

Perintah, nama opsi, dan alias peka huruf besar/kecil secara default sesuai dengan konvensi POSIX, dan System.CommandLine mengikuti konvensi ini. Jika Anda ingin CLI Anda tidak sensitif, tentukan alias untuk berbagai alternatif huruf besar/kecil. Misalnya, --additional-probing-path dapat memiliki alias --Additional-Probing-Path dan --ADDITIONAL-PROBING-PATH.

Dalam beberapa alat baris perintah, perbedaan huruf besar/kecil menentukan perbedaan fungsi. Misalnya, git clean -X berperilaku berbeda dari git clean -x. .NET CLI semuanya menggunakan huruf kecil.

Sensitivitas huruf besar/kecil tidak berlaku bagi nilai argumen untuk opsi yang didasarkan pada enum. Nama enum akan dicocokkan terlepas dari huruf besar/kecilnya.

Token `--`

Konvensi POSIX menginterpretasikan token tanda hubung ganda (--) sebagai mekanisme escape. Segala sesuatu yang mengikuti token tanda hubung ganda ditafsirkan sebagai argumen untuk perintah. Fungsi ini dapat digunakan untuk mengirimkan argumen yang terlihat seperti opsi, karena dapat mencegah argumen ditafsirkan sebagai opsi.

Misalkan myapp mengambil argumen message, dan Anda ingin nilai message menjadi --interactive. Baris perintah berikut mungkin memberikan hasil yang tidak terduga.

myapp --interactive

Jika myapp tidak memiliki opsi --interactive, token --interactive ditafsirkan sebagai argumen. Tetapi jika aplikasi memang memiliki opsi --interactive, input ini akan ditafsirkan sebagai mengacu pada opsi tersebut.

Baris perintah berikut menggunakan token tanda hubung-ganda untuk mengatur nilai argumen message ke "--interaktif":

myapp -- --interactive
      ^^

System.CommandLine mendukung fungsionalitas tanda hubung ganda ini.

Pemisah argumen opsi

System.CommandLine memungkinkan Anda menggunakan spasi, '=', atau ':' sebagai pemisah antara nama opsi dan argumennya. Misalnya, perintah berikut ini setara:

dotnet build -v quiet
dotnet build -v=quiet
dotnet build -v:quiet

Konvensi POSIX memungkinkan Anda menghilangkan pemisah saat menentukan alias opsi satu karakter. Misalnya, perintah berikut ini setara:

myapp -vquiet
myapp -v quiet

System.CommandLine mendukung sintaks ini secara default.

Aritas argumen

Aritas opsi atau argumen perintah adalah jumlah nilai yang dapat diteruskan jika opsi atau perintah tersebut ditentukan.

Aritas dinyatakan dengan nilai minimum dan nilai maksimum, seperti yang digambarkan tabel berikut:

Min	Maks	Contoh validitas	Contoh
0	0	Valid:	--file
		Tidak Valid:	--file a.json
		Tidak Valid:	--file a.json --file b.json
0	1	Valid:	--flag
		Valid:	--flag true
		Valid:	--flag false
		Tidak Valid:	--flag false --flag false
1	1	Valid:	--file a.json
		Tidak Valid:	--file
		Tidak Valid:	--file a.json --file b.json
0	n	Valid:	--file
		Valid:	--file a.json
		Valid:	--file a.json --file b.json
1	n	Valid:	--file a.json
		Valid:	--file a.json b.json
		Tidak Valid:	--file

System.CommandLine memiliki struktur ArgumentArity untuk mendefinisikan aritas, dengan nilai berikut:

Zero - Tidak ada nilai yang diperbolehkan.
ZeroOrOne - Mungkin memiliki satu nilai, mungkin tidak memiliki nilai.
ExactlyOne - Harus memiliki satu nilai.
ZeroOrMore - Mungkin memiliki satu nilai, beberapa nilai, atau tanpa nilai.
OneOrMore - Mungkin memiliki beberapa nilai, harus memiliki setidaknya satu nilai.

Aritas sering dapat disimpulkan dari jenisnya. Misalnya, opsi int memiliki aritas ExactlyOne, dan opsi List<int> memiliki aritas OneOrMore.

Penimpaan opsi

Jika aritas maksimum adalah 1, System.CommandLine masih dapat dikonfigurasi untuk menerima beberapa instans opsi. Dalam hal ini, instans terakhir dari opsi berulang menimpa instans sebelumnya. Dalam contoh berikut, nilai 2 akan diteruskan ke perintah myapp.

myapp --delay 3 --message example --delay 2

Beberapa argumen

Jika aritas maksimum lebih dari satu, System.CommandLine dapat dikonfigurasi guna menerima beberapa argumen untuk satu opsi tanpa mengulangi nama opsi.

Dalam contoh berikut, daftar yang diteruskan ke perintah myapp akan berisi "a", "b", "c", dan "d":

myapp --list a b c --list d

Bundling opsi

POSIX merekomendasikan agar Anda mendukung bundling opsi karakter tunggal, juga dikenal sebagai penumpukan. Opsi yang dibundel adalah alias opsi karakter tunggal yang ditentukan bersama setelah awalan tanda hubung tunggal. Hanya opsi terakhir yang dapat menentukan argumen. Misalnya, baris perintah berikut ini setara:

git clean -f -d -x
git clean -fdx

Jika argumen disediakan setelah bundel opsi, argumen itu berlaku untuk opsi terakhir dalam bundel. Baris perintah berikut ini setara:

myapp -a -b -c arg
myapp -abc arg

Dalam kedua varian dalam contoh ini, argumen arg hanya akan berlaku untuk opsi -c.

Opsi Boolean (bendera)

Jika true atau false diteruskan untuk opsi yang memiliki argumen bool, maka akan diurai seperti yang diharapkan. Tetapi opsi yang jenis argumennya bool biasanya tidak memerlukan argumen untuk ditentukan. Opsi Boolean, kadang-kadang disebut "bendera", biasanya memiliki aritas ZeroOrOne. Kehadiran nama opsi pada baris perintah, tanpa argumen yang mengikutinya, menghasilkan nilai default true. Tidak adanya nama opsi dalam input baris perintah menghasilkan nilai false. Jika perintah myapp mencetak nilai opsi Boolean bernama --interactive, input berikut membuat output berikut:

myapp
myapp --interactive
myapp --interactive false
myapp --interactive true

False
True
False
True

Opsi --bantuan

Aplikasi baris perintah biasanya menyediakan opsi untuk menampilkan deskripsi singkat tentang perintah, opsi, dan argumen yang tersedia. System.CommandLine secara otomatis menghasilkan output bantuan. Contohnya:

dotnet list --help

Description:
  List references or packages of a .NET project.

Usage:
  dotnet [options] list [<PROJECT | SOLUTION>] [command]

Arguments:
  <PROJECT | SOLUTION>  The project or solution file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -?, -h, --help  Show command line help.

Commands:
  package    List all package references of the project or solution.
  reference  List all project-to-project references of the project.

Pengguna aplikasi mungkin terbiasa dengan berbagai cara untuk meminta bantuan pada platform yang berbeda, sehingga aplikasi yang dibangun di atas System.CommandLine merespons banyak cara untuk meminta bantuan. Semua perintah berikut ini setara:

dotnet --help
dotnet -h
dotnet /h
dotnet -?
dotnet /?

Output bantuan tidak selalu menampilkan semua perintah, argumen, dan opsi yang tersedia. Beberapa dari mereka mungkin tersembunyi, artinya, mereka tidak muncul dalam output bantuan tetapi dapat ditentukan pada baris perintah.

Opsi --versi

Aplikasi bawaan System.CommandLine secara otomatis menyediakan nomor versi sebagai respons terhadap opsi --version yang digunakan dengan perintah root. Contohnya:

dotnet --version

6.0.100

File respons

File respons adalah file yang berisi sekumpulan token untuk aplikasi baris perintah. File respons adalah fitur System.CommandLine yang berguna dalam dua skenario:

Untuk memanggil aplikasi baris perintah dengan menentukan input yang lebih panjang dari batas karakter terminal.
Untuk memanggil perintah yang sama berulang kali tanpa mengetik ulang seluruh baris.

Untuk menggunakan file respons, masukkan nama file yang diawali dengan tanda @ di baris mana pun yang ingin Anda sisipkan perintah, opsi, dan argumen. Ekstensi file .rsp adalah konvensi umum, tetapi Anda dapat menggunakan ekstensi file apa pun.

Baris berikut ini setara:

dotnet build --no-restore --output ./build-output/
dotnet @sample1.rsp
dotnet build @sample2.rsp --output ./build-output/

Konten sample1.rsp:

build
--no-restore 
--output
./build-output/

Konten sample2.rsp:

--no-restore

Berikut adalah aturan sintaks yang menentukan bagaimana teks dalam file respons ditafsirkan:

Token dipisahkan oleh spasi. Baris yang berisi Selamat pagi! diperlakukan sebagai dua token, Selamat dan pagi!.
Beberapa token yang diapit tanda kutip ditafsirkan sebagai satu token. Baris yang berisi "Selamat pagi!" diperlakukan sebagai satu token, Selamat pagi!.
Teks apa pun di antara simbol # dan akhir baris diperlakukan sebagai komentar dan diabaikan.
Token yang diawali dengan @ dapat mereferensikan file respons tambahan.
File respons dapat memiliki beberapa baris teks. Garis digabungkan dan ditafsirkan sebagai urutan token.

Arahan

System.CommandLine memperkenalkan elemen sintaksis yang disebut petunjuk. Petunjuk [parse] adalah contoh. Saat Anda menyertakan [parse] setelah nama aplikasi, System.CommandLine menampilkan diagram hasil penguraian, bukan memanggil aplikasi baris perintah:

dotnet [parse] build --no-restore --output ./build-output/
       ^-----^

[ dotnet [ build [ --no-restore <True> ] [ --output <./build-output/> ] ] ]

Tujuan dari adanya arahan adalah untuk menyediakan fungsionalitas lintas sektoral yang dapat diterapkan di seluruh aplikasi baris perintah. Karena petunjuk berbeda secara sintaksis dari sintaks aplikasi sendiri, mereka dapat menyediakan fungsionalitas yang berlaku di seluruh aplikasi.

Petunjuk harus sesuai dengan aturan sintaks berikut:

Petunjuk ini adalah token pada baris perintah yang muncul setelah nama aplikasi tetapi sebelum subperintah atau opsi apa pun.
Petunjuk diapit dalam tanda kurung siku.
Petunjuk tidak berisi spasi.

Petunjuk yang tidak dikenal diabaikan tanpa menyebabkan kesalahan penguraian.

Petunjuk dapat menyertakan argumen, dipisahkan dari nama petunjuk oleh titik dua.

Petunjuk berikut dibuat di:

[parse]
[suggest]

Petunjuk `[parse]`

Baik pengguna maupun pengembang mungkin merasa penting untuk melihat bagaimana aplikasi akan menginterpretasikan input yang diberikan. Salah satu fitur default aplikasi System.CommandLine adalah petunjuk [parse], yang memungkinkan Anda melihat pratinjau hasil input perintah penguraian. Contohnya:

myapp [parse] --delay not-an-int --interactive --file filename.txt extra

![ myapp [ --delay !<not-an-int> ] [ --interactive <True> ] [ --file <filename.txt> ] *[ --fgcolor <White> ] ]   ???--> extra

Dalam contoh sebelumnya:

Perintah (myapp), opsi turunannya, dan argumen untuk opsi tersebut dikelompokkan menggunakan kurung siku.
Untuk hasil opsi [ --delay !<not-an-int> ], ! menunjukkan kesalahan penguraian. Nilai not-an-int untuk opsi int tidak dapat diurai ke jenis yang diharapkan. Kesalahan juga ditandai oleh ! di depan perintah yang berisi opsi yang salah: ![ myapp....
Untuk hasil opsi *[ --fgcolor <White> ], opsi tidak ditentukan pada baris perintah, sehingga default yang dikonfigurasi digunakan. White adalah nilai efektif untuk opsi ini. Tanda bintang menunjukkan bahwa nilainya adalah default.
???--> menunjuk ke input yang tidak cocok dengan perintah atau opsi aplikasi apa pun.

Petunjuk `[suggest]`

Petunjuk [suggest] memungkinkan Anda mencari perintah saat Anda tidak mengetahui perintah yang tepat.

dotnet [suggest] buil

build
build-server
msbuild

Panduan desain

Bagian berikut menyajikan panduan sebaiknya Anda ikuti saat merancang CLI. Pikirkan apa yang diharapkan aplikasi Anda di baris perintah mirip dengan apa yang diharapkan server REST API di URL. Aturan yang konsisten untuk REST API adalah 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. Pedoman di sini dikembangkan setelah .NET CLI, dan tidak selalu mengikuti pedoman ini. Kami memperbarui .NET CLI di mana kami dapat melakukannya tanpa memperkenalkan perubahan yang melanggar. Contoh pekerjaan ini adalah desain baru untuk dotnet new di .NET 7.

Perintah dan subperintah

Jika perintah memiliki subperintah, perintah harus berfungsi sebagai area, atau pengenal grup untuk subperintah, bukan menentukan tindakan. Saat memanggil aplikasi, tentukan perintah pengelompokan dan salah satu subperintahnya. Misalnya, coba jalankan dotnet tool, dan Anda akan mendapatkan pesan kesalahan karena perintah tool 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 mendefinisikan area yang membantu pengguna Anda adalah dengan mengatur keluaran bantuan.

Dalam CLI sering ada area implisit. Misalnya, di .NET CLI, area implisitnya adalah proyek dan di Docker CLI area implisitnya adalah gambar. Akibatnya, Anda dapat menggunakan dotnet build tanpa menyertakan area. Pertimbangkan apakah CLI Anda memiliki area implisit. Jika punya, 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, Anda juga secara otomatis memiliki bantuan dan penyelesaian tab untuk pengelompokan perintah ini. Berikan penggunaan opsional grup implisit dengan mendefinisikan 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).

Alias bentuk pendek

Secara umum, sebaiknya minimalkan jumlah alias opsi bentuk pendek yang Anda tentukan.

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

-i untuk --interactive.

Opsi ini memberi sinyal kepada pengguna bahwa mereka mungkin diminta untuk menginput pertanyaan yang perlu dijawab oleh perintah. Misalnya, meminta nama pengguna. CLI Anda dapat digunakan dalam skrip, jadi berhati-hatilah dalam meminta pengguna yang belum menentukan pengalihan ini.
-o untuk --output.

Beberapa perintah menghasilkan file sebagai hasil dari eksekusinya. Opsi ini harus digunakan untuk membantu menentukan di mana file-file itu harus ditempatkan. Dalam kasus pembuatan satu file, opsi ini harus berupa jalur file. Dalam kasus pembuatan banyak file, opsi ini harus berupa jalur direktori.
-v untuk --verbosity.

Perintah sering memberikan output kepada pengguna di konsol; opsi ini digunakan untuk menentukan jumlah output yang diminta pengguna. Untuk informasi selengkapnya, lihat --verbosityOpsi selanjutnya di artikel ini.

Ada juga beberapa alias dengan penggunaan umum terbatas pada .NET CLI. Anda dapat menggunakan alias ini untuk opsi lain di aplikasi Anda, tetapi waspadai 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—misalnya, melakukan lebih sedikit pengoptimalan kode saat membangun konfigurasi Debug. 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 dieksekusi, jadi jika aplikasi CLI Anda memiliki perilaku berbeda berdasarkan TFM yang dipilih, Anda harus mendukung tanda ini.
-p untuk --property

Jika aplikasi Anda akhirnya memanggil MSBuild, pengguna akan sering perlu menyesuaikan panggilan itu dalam beberapa cara. Opsi ini memungkinkan properti MSBuild disediakan pada baris perintah dan diteruskan ke panggilan MSBuild yang mendasarinya. Jika aplikasi Anda tidak menggunakan MSBuild tetapi membutuhkan satu set pasangan kunci-nilai, pertimbangkan untuk menggunakan nama opsi yang sama ini untuk memanfaatkan harapan 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 untuk menentukan Pengidentifikasi Runtime. Jika aplikasi Anda mendukung --runtime, pertimbangkan untuk mendukung --os dan --arch juga. Opsi ini memungkinkan Anda menentukan OS atau bagian arsitektur RID saja, membiarkan bagian yang tidak ditentukan dari platform saat ini. Untuk mengetahui informasi selengkapnya, lihat dotnet publish.

Nama pendek

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

Nama huruf kecil

Tetapkan nama dalam huruf kecil saja, kecuali Anda dapat membuat alias huruf besar untuk membuat perintah atau opsi tidak peka huruf besar/kecil.

Nama kasus kebab

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

Pluralisasi

Dalam sebuah aplikasi, konsistenlah dalam hal pluralisasi. Misalnya, jangan mencampur nama jamak dan tunggal untuk opsi yang dapat memiliki banyak 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 pada tindakan (yang tanpa subperintah 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`

Aplikasi System.CommandLine biasanya menawarkan opsi --verbosity 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, namun aplikasi yang ada terkadang menggunakan Silent sebagai pengganti Quiet, dan Trace, Debug, atau Verbose sebagai pengganti Diagnostic.

Setiap aplikasi menentukan kriterianya sendiri yang menentukan apa yang ditampilkan di setiap tingkatan. Biasanya aplikasi hanya membutuhkan tiga level:

Tenang
Normal
Ekstensi

Jika aplikasi tidak memerlukan lima level berbeda, opsi tersebut masih harus menentukan lima pengaturan yang sama. Dalam hal ini, Minimal dan Normal akan menghasilkan output yang sama, begitu juga dengan Detailed dan Diagnostic akan sama. Hal ini memungkinkan pengguna Anda untuk hanya mengetik apa yang familier bagi mereka, dan akan menggunakan apa yang paling cocok bagi mereka.

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

Tampilkan perintah input ketika --interactive ditentukan, bahkan jika --verbosity adalah Quiet.
Larang penggunaan --verbosity Quiet dan --interactive secara bersamaan.

Atau, aplikasi akan menunggu input tanpa memberi tahu pengguna apa yang menunggunya. Tampaknya aplikasi Anda membeku dan pengguna tidak tahu bahwa aplikasi sedang menunggu input.

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

Konvensi .NET CLI dan POSIX

.NET CLI tidak secara konsisten mengikuti semua konvensi POSIX.

Tanda hubung-ganda

Beberapa perintah di .NET CLI memiliki implementasi khusus token tanda hubung. 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, opsi --project diteruskan ke perintah dotnet run, dan opsi --message 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 tanda hubung ganda, perintah dotnet run secara otomatis meneruskan ke aplikasi yang sedang menjalankan opsi apa pun yang tidak dikenali sebagai diterapkan ke dotnet run itu sendiri atau ke MSBuild. 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

Penghapusan pemisah opsi-ke-argumen

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

Perbanyak argumen tanpa mengulangi nama opsi

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

Opsi Boolean

Di .NET CLI, beberapa opsi Boolean menghasilkan perilaku yang sama saat Anda melewati false seperti saat Anda melewati true. Perilaku ini terjadi ketika kode .NET CLI yang mengimplementasikan opsi hanya memeriksa ada atau tidaknya opsi, mengabaikan nilainya. Contohnya adalah --no-restore untuk perintah dotnet build. Lewati no-restore false dan operasi pemulihan akan dilewati sama seperti ketika 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, bukan --additional-probing-path.

Bagikan melalui