Gambaran umum sintaks: Perintah, opsi, dan argumen

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.

Artikel ini menjelaskan sintaks baris perintah yang System.CommandLine mengenali. Informasi ini berguna untuk pengguna dan pengembang aplikasi baris perintah .NET, termasuk .NET CLI.

Beberapa Token

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

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

Input ini diurai oleh dotnet aplikasi ke dalam 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-token setelah token pertama ditafsirkan. Tabel berikut ini memperlihatkan cara System.CommandLine menginterpretasikan contoh sebelumnya:

Tanda	Diartikan sebagai
`tool`	Perintah tambahan
`install`	Perintah tambahan
`dotnet-suggest`	Argumen untuk perintah instal
`--global`	Opsi untuk perintah penginstalan
`--verbosity`	Opsi untuk perintah penginstalan
`quiet`	Argumen untuk `--verbosity` opsi

Token dapat berisi spasi jika diapit dalam tanda kutip ("). Berikut adalah 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 adalah perintah yang menentukan tindakan.
Dalam dotnet tool install, install adalah perintah yang menentukan tindakan, dan tool merupakan perintah yang menentukan sekelompok perintah terkait. Ada perintah terkait alat lainnya, seperti tool uninstall, , tool listdan tool update.

Perintah root

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

System.CommandLine.Command adalah kelas tujuan umum untuk perintah atau subperintah apa pun, sementara System.CommandLine.RootCommand merupakan versi khusus yang ditujukan untuk titik entri akar aplikasi, mewarisi semua fitur System.CommandLine.Command tetapi menambahkan perilaku dan default khusus akar, seperti opsi Bantuan, Opsi versi , dan Direktif Sarankan.

perintah tambahan

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

Sub-perintah dapat memiliki sub-perintah mereka sendiri. Dalam dotnet tool install, install adalah sub perintah dari tool.

Anda dapat menambahkan sub perintah seperti yang ditunjukkan dalam contoh berikut:

RootCommand rootCommand = new();

Command sub1Command = new("sub1", "First-level subcommand");
rootCommand.Subcommands.Add(sub1Command);

Command sub1aCommand = new("sub1a", "Second level subcommand");
sub1Command.Subcommands.Add(sub1aCommand);

Sub perintah terdalam dalam contoh ini dapat dipanggil seperti ini:

myapp sub1 sub1a

Opsi

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

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

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

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

msbuild /version
        ^------^

System.CommandLine mendukung konvensi awalan POSIX dan Windows.

Saat mengonfigurasi opsi, Anda menentukan nama opsi termasuk awalan:

Option<int> delayOption = new("--delay", "-d")
{
    Description = "An option whose argument is parsed as an int.",
    DefaultValueFactory = parseResult => 42,
};
Option<string> messageOption = new("--message", "-m")
{
    Description = "An option whose argument is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Options.Add(delayOption);
rootCommand.Options.Add(messageOption);

Untuk menambahkan opsi ke perintah dan secara rekursif ke semua sub-perintahnya, gunakan System.CommandLine.Symbol.Recursive properti .

Opsi yang Diperlukan

Beberapa opsi memiliki argumen yang diperlukan. Misalnya di .NET CLI, --output memerlukan argumen nama folder. Jika argumen tidak disediakan, perintah gagal. Untuk membuat opsi diperlukan, atur propertinya System.CommandLine.Symbol.Required ke true, seperti yang ditunjukkan dalam contoh berikut:

Option<FileInfo> fileOption = new("--output")
{
    Required = true
};

Jika opsi yang diperlukan memiliki nilai default (ditentukan melalui DefaultValueFactory properti), opsi tidak harus ditentukan pada baris perintah. Dalam hal ini, nilai default menyediakan nilai opsi yang diperlukan.

Argumen

Argumen adalah parameter yang tidak disebutkan namanya yang dapat diteruskan ke perintah. Contoh berikut menunjukkan argumen untuk build perintah .

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

Saat Mengonfigurasi argumen, Anda menentukan nama argumen (tidak digunakan untuk penguraian, tetapi dapat digunakan untuk mendapatkan nilai yang diurai berdasarkan nama atau menampilkan bantuan) dan mengetik:

Argument<int> delayArgument = new("delay")
{
    Description = "An argument that is parsed as an int.",
    DefaultValueFactory = parseResult => 42
};
Argument<string> messageArgument = new("message")
{
    Description = "An argument that is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Arguments.Add(delayArgument);
rootCommand.Arguments.Add(messageArgument);

Nilai Default

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

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

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

Argumen yang didefinisikan tanpa nilai default diperlakukan sebagai argumen yang diperlukan.

Kesalahan penguraian

Opsi dan argumen memiliki jenis yang diharapkan, dan kesalahan dihasilkan ketika nilai tidak dapat diurai. Misalnya, kesalahan perintah berikut karena "diam" bukan salah satu nilai yang valid untuk --verbosity:

dotnet build --verbosity silent

Option<string> verbosityOption = new("--verbosity", "-v")
{
    Description = "Set the verbosity level.",
};
verbosityOption.AcceptOnlyFromAmong("quiet", "minimal", "normal", "detailed", "diagnostic");
RootCommand rootCommand = new() { verbosityOption };

ParseResult parseResult = rootCommand.Parse(args);
foreach (ParseError parseError in parseResult.Errors)
{
    Console.WriteLine(parseError.Message);
}

Argument 'silent' not recognized. Must be one of:
        'quiet'
        'minimal'
        'normal'
        'detailed'
        'diagnostic'

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

Urutan opsi dan argumen

Anda dapat menyediakan 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

Opsi 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, urutannya penting. Perintah berikut tidak setara; mereka berbeda dalam urutan nilai, yang dapat menyebabkan hasil yang berbeda:

myapp argument1 argument2
myapp argument2 argument1

Nama Lain

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

Bentuk pendek POSIX biasanya memiliki satu tanda hubung di depannya 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. Setiap alias harus ditentukan secara eksplisit. Perintah dan opsi memperlihatkan Aliases properti. Option memiliki konstruktor yang menerima alias sebagai parameter, sehingga Anda dapat menentukan opsi dengan beberapa alias dalam satu baris:

Option<bool> helpOption = new("--help", ["-h", "/h", "-?", "/?"]);
Command command = new("serialize") { helpOption };
command.Aliases.Add("serialise");

Sebaiknya Anda meminimalkan jumlah alias opsi yang Anda tentukan, dan hindari menentukan alias tertentu secara khusus. Untuk informasi selengkapnya, lihat Alias bentuk pendek.

Sensitivitas huruf besar/kecil

Nama dan alias perintah serta opsi peka terhadap huruf besar/kecil secara bawaan sesuai dengan konvensi POSIX; System.CommandLine mengikuti konvensi POSIX ini. Jika Anda ingin CLI Anda tidak sensitif terhadap huruf besar/kecil, tetapkan alias untuk berbagai alternatif penggunaan huruf besar/kecil. Misalnya, --additional-probing-path bisa memiliki alias --Additional-Probing-Path dan --ADDITIONAL-PROBING-PATH.

Dalam beberapa alat baris perintah, perbedaan dalam casing menentukan perbedaan fungsi. Misalnya, git clean -X berulah berbeda dari git clean -x. CLI di .NET ditulis dengan huruf kecil semua.

Sensitivitas kasus tidak berlaku untuk nilai argumen untuk opsi yang didasarkan pada enum. Nama enum dicocokkan terlepas dari casing.

Token `--`

Konvensi POSIX menafsirkan token tanda hubung ganda (--) sebagai mekanisme pelolosan. Semua yang mengikuti token tanda hubung ganda ditafsirkan sebagai argumen untuk perintah . Fungsionalitas ini dapat digunakan untuk mengirimkan argumen yang terlihat seperti opsi, karena mencegahnya ditafsirkan sebagai opsi.

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

myapp --interactive

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

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

myapp -- --interactive
      ^^

System.CommandLine mendukung fungsionalitas garis hubung ganda ini.

Pemisah untuk argumen opsi

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

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

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

myapp -vquiet
myapp -v quiet

System.CommandLine mendukung sintaksis 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 diilustrasikan tabel berikut:

Menit	Maks	Contoh validitas	Contoh
0	0	Sah:	--arsip
		Tidak Sah:	--file a.json
		Tidak Sah:	--file a.json --file b.json
0	1	Sah:	--bendera
		Sah:	--flag true
		Sah:	--flag false
		Tidak Sah:	--flag false --flag false
1	1	Sah:	--file a.json
		Tidak Sah:	--arsip
		Tidak Sah:	--file a.json --file b.json
0	n	Sah:	--arsip
		Sah:	--file a.json
		Sah:	--file a.json --file b.json
1	n	Sah:	--file a.json
		Sah:	--file a.json b.json
		Tidak Sah:	--arsip

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

System.CommandLine.ArgumentArity.Zero - Tidak ada nilai yang diizinkan.
System.CommandLine.ArgumentArity.ZeroOrOne - Mungkin memiliki satu nilai, mungkin tidak memiliki nilai.
System.CommandLine.ArgumentArity.ExactlyOne - Harus memiliki satu nilai.
System.CommandLine.ArgumentArity.ZeroOrMore - Mungkin memiliki satu nilai, beberapa nilai, atau tidak ada nilai.
System.CommandLine.ArgumentArity.OneOrMore - Mungkin memiliki beberapa nilai, harus memiliki setidaknya satu nilai.

Anda dapat secara eksplisit mengatur aritas dengan menggunakan properti Arity, tetapi dalam banyak kasus hal itu tidak diperlukan. System.CommandLine secara otomatis menentukan aritas argumen berdasarkan jenis argumen:

Jenis argumen	Arity bawaan
`Boolean`	`ArgumentArity.ZeroOrOne`
Tipe koleksi	`ArgumentArity.ZeroOrMore`
Segala sesuatu yang lain	`ArgumentArity.ExactlyOne`

Penimpaan opsi

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

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

Beberapa argumen

Secara default, saat Anda memanggil perintah, Anda dapat mengulangi nama opsi untuk menentukan beberapa argumen untuk opsi yang memiliki aritas maksimum lebih besar dari satu.

myapp --items one --items two --items three

Untuk mengizinkan beberapa argumen tanpa mengulangi nama opsi, atur System.CommandLine.Option.AllowMultipleArgumentsPerToken ke true. Pengaturan ini memungkinkan Anda memasukkan baris perintah berikut.

myapp --items one two three

Pengaturan yang sama memiliki efek yang berbeda jika aritas argumen maksimum adalah 1. Ini memungkinkan Anda untuk mengulangi opsi tetapi hanya mengambil nilai terakhir pada baris. Dalam contoh berikut, nilai three akan diteruskan ke aplikasi.

myapp --item one --item two --item three

Pembundelan opsi

POSIX merekomendasikan agar Anda mendukung penggabungan opsi karakter tunggal, juga dikenal sebagai penumpukan. Opsi yang dibundel adalah alias opsi karakter tunggal yang ditentukan bersama-sama setelah satu awalan tanda hubung. 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 tersebut 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 (penanda)

Jika true atau false diteruskan untuk opsi yang memiliki bool argumen, opsi akan diurai seperti yang diharapkan. Tetapi opsi yang jenis argumennya bool biasanya tidak memerlukan argumen untuk ditentukan. Opsi Boolean, kadang-kadang disebut "flag", biasanya memiliki aritasSystem.CommandLine.ArgumentArity.ZeroOrOne. Kehadiran nama opsi pada baris perintah, tanpa argumen yang mengikutinya, menghasilkan nilai truedefault . Tidak adanya nama opsi dalam input baris perintah menghasilkan nilai false. myapp Jika perintah 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 versi perangkat lunak

Aplikasi yang dibangun di atas System.CommandLine secara otomatis menyediakan nomor versi menanggapi opsi --version yang digunakan dengan perintah root. Contohnya:

dotnet --version

6.0.100

File tanggapan

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 mana pun di dalam baris yang ingin Anda sisipkan perintah, opsi, dan argumen. Ekstensi file .rsp adalah konvensi umum, tetapi Anda dapat menggunakan ekstensi file apa pun.

Baris berikut setara:

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

Isi dari sample1.rsp:

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

Konten dari sample2.rsp:

--no-restore

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

Token dibatasi oleh spasi. Baris yang berisi Selamat pagi! diperlakukan sebagai dua token, Baik dan pagi!.
Beberapa token yang diapit dalam tanda kutip ditafsirkan sebagai token tunggal. Baris yang berisi "Selamat pagi!" diperlakukan sebagai satu token, Selamat pagi!.
Teks apa pun 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.

Petunjuk

System.CommandLine memperkenalkan elemen sintaksis yang disebut direktif yang diwakili oleh jenis System.CommandLine.Directive. Direktif [diagram] adalah contoh. Saat Anda menyertakan [diagram] setelah nama aplikasi, System.CommandLine menampilkan diagram hasil penguraian alih-alih memanggil aplikasi baris perintah:

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

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

Tujuan direktif adalah untuk menyediakan fungsionalitas lintas fitur yang dapat berlaku untuk semua aplikasi baris perintah. Karena direktif secara sintetis berbeda dari sintaks aplikasi sendiri, mereka dapat menyediakan fungsionalitas yang berlaku di seluruh aplikasi.

Arahan harus sesuai dengan aturan sintaks berikut:

Ini adalah token pada baris perintah yang muncul setelah nama aplikasi tetapi sebelum sub-perintah atau opsi apa pun.
Ini dikelilingi dalam tanda kurung siku.
Ini tidak berisi spasi.

Perintah yang tidak dikenali diabaikan tanpa menyebabkan kesalahan penguraian.

Direktif dapat menyertakan argumen, dipisahkan dari nama direktif dengan titik dua.

Direktif berikut sudah terpasang:

[diagram]
[suggest]

Petunjuk `[diagram]`

Pengguna dan pengembang mungkin merasa berguna untuk melihat bagaimana aplikasi akan menginterpretasikan input tertentu. Salah satu fitur bawaan aplikasi System.CommandLine adalah instruksi [diagram], yang memungkinkan Anda melihat pratinjau hasil penguraian input perintah. Contohnya:

myapp [diagram] --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 tanda kurung siku.
Untuk hasil opsi [ --delay !<not-an-int> ], ! menunjukkan kesalahan penguraian. Nilai not-an-int untuk int opsi 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 mana pun.

Sarankan direktif

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

dotnet [suggest] buil

build
build-server
msbuild

Bagikan melalui