için komut satırı söz dizimine genel bakış System.CommandLine
Önemli
System.CommandLine
şu anda ÖNİzLEME aşamasındadır ve bu belgeler 2.0 beta 4 sürümüne yöneliktir.
Bazı bilgiler, yayımlanmadan önce önemli ölçüde değiştirilebilen yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.
Bu makalede, tanıyan komut satırı söz dizimi System.CommandLine
açıklanmaktadır. Bilgiler hem kullanıcılar hem de .NET CLI dahil olmak üzere .NET komut satırı uygulamalarının geliştiricileri için yararlı olacaktır.
Belirteçler
System.CommandLine
komut satırı girişini, boşluklarla ayrılmış dizeler olan belirteçler halinde ayrıştırılır. Örneğin, aşağıdaki komut satırını göz önünde bulundurun:
dotnet tool install dotnet-suggest --global --verbosity quiet
Bu giriş, uygulama tarafından dotnet
belirteçler tool
, , install
, dotnet-suggest
--global
, --verbosity
ve quiet
içine ayrıştırılır.
Belirteçler komut, seçenek veya bağımsız değişken olarak yorumlanır. Çağrılan komut satırı uygulaması, ilk belirteçlerden sonraki belirteçlerin nasıl yorumlandığını belirler. Aşağıdaki tabloda, önceki örneğin nasıl System.CommandLine
yorumlanması gösterilmektedir:
Belirteç | Farklı ayrıştırıldı |
---|---|
tool |
Alt komut |
install |
Alt komut |
dotnet-suggest |
Yükleme komutu için bağımsız değişken |
--global |
Yükleme komutu seçeneği |
--verbosity |
Yükleme komutu seçeneği |
quiet |
Seçenek bağımsız --verbosity değişkeni |
Belirteç tırnak işareti ("
içine alınmışsa boşluklar içerebilir. Bir örnek aşağıda verilmiştir:
dotnet tool search "ef migrations add"
Komutlar
Komut satırı girişindeki komut, bir eylemi belirten veya ilgili eylemler grubunu tanımlayan bir belirteçtir. Örneğin:
- içinde
dotnet run
,run
eylemi belirten bir komutdur. install
içindedotnet tool install
, bir eylemi belirten bir komut vetool
ilgili komutlardan oluşan bir grubu belirten bir komut. ,tool list
vetool update
gibitool uninstall
araçla ilgili başka komutlar da vardır.
Kök komutlar
Kök komutu, uygulamanın yürütülebilir dosyasının adını belirten komutdur. Örneğin, dotnet
komut dotnet.exe yürütülebilir dosyasını belirtir.
Alt Komutlar
Komut satırı uygulamalarının çoğu fiil olarak da bilinen alt komutları destekler. Örneğin, komutunun dotnet
girerek dotnet run
çağırdığınız bir run
alt komutu vardır.
Alt komutların kendi alt komutları olabilir. içinde dotnet tool install
, install
bir alt komutudur tool
.
Seçenekler
Seçenek, bir komuta geçirilebilen adlandırılmış bir parametredir. POSIX CLI'leri genellikle seçenek adının önüne iki kısa çizgi (--
) ekler. Aşağıdaki örnekte iki seçenek gösterilmektedir:
dotnet tool update dotnet-suggest --verbosity quiet --global
^---------^ ^------^
Bu örnekte gösterildiği gibi, seçeneğin değeri açık (quiet
için --verbosity
) veya örtük olabilir (aşağıda --global
hiçbir şey yoktur). Değeri belirtilmemiş seçenekler genellikle seçenek komut satırında belirtilirse varsayılan true
olarak Boole parametreleridir.
Bazı Windows komut satırı uygulamaları için, seçenek adıyla bir baştaki eğik çizgi (/
) kullanarak bir seçeneği tanımlarsınız. Örneğin:
msbuild /version
^------^
System.CommandLine
hem POSIX hem de Windows ön ek kurallarını destekler. Bir seçeneği yapılandırırken, ön ek dahil olmak üzere seçenek adını belirtirsiniz.
Bağımsız değişkenler
Bağımsız değişken, bir seçeneğe veya komuta geçirilen değerdir. Aşağıdaki örneklerde seçeneği için verbosity
bir bağımsız değişken ve komutu için bir bağımsız değişken gösterilmektedir build
.
dotnet tool update dotnet-suggest --verbosity quiet --global
^---^
dotnet build myapp.csproj
^----------^
Bağımsız değişkenler açıkça sağlanmayan varsayılan değerlere sahip olabilir. Örneğin, birçok seçenek, seçenek adı komut satırında olduğunda varsayılan true
değer olan örtük boole parametreleridir. Aşağıdaki komut satırı örnekleri eşdeğerdir:
dotnet tool update dotnet-suggest --global
^------^
dotnet tool update dotnet-suggest --global true
^-----------^
Bazı seçeneklerde gerekli bağımsız değişkenler bulunur. Örneğin, .NET CLI'da --output
bir klasör adı bağımsız değişkeni gerektirir. Bağımsız değişken sağlanmazsa, komut başarısız olur.
Bağımsız değişkenlerin beklenen türleri olabilir ve System.CommandLine
bir bağımsız değişken beklenen türe ayrıştırılamıyorsa bir hata iletisi görüntüler. Örneğin, "sessiz" için geçerli değerlerden --verbosity
biri olmadığından aşağıdaki komut hataları:
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
Bağımsız değişkenlerin kaç değer sağlanabileceği konusunda da beklentileri vardır. Örnekler bağımsız değişken arity bölümünde verilmiştir.
Seçeneklerin ve bağımsız değişkenlerin sırası
Komut satırındaki seçeneklerden önce bağımsız değişkenlerden veya bağımsız değişkenlerden önce seçenekler sağlayabilirsiniz. Aşağıdaki komutlar eşdeğerdir:
dotnet add package System.CommandLine --prerelease
dotnet add package --prerelease System.CommandLine
Seçenekler herhangi bir sırada belirtilebilir. Aşağıdaki komutlar eşdeğerdir:
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
Birden çok bağımsız değişken olduğunda sıra önemlidir. Aşağıdaki komutların eşdeğer olması gerekmez:
myapp argument1 argument2
myapp argument2 argument1
Bu komutlar, komut işleyici koduna aynı değerlere sahip bir liste geçirir, ancak değerlerin sırasına göre farklılık gösterir ve bu da farklı sonuçlara yol açabilir.
Diğer adlar
Hem POSIX hem de Windows'ta bazı komutların ve seçeneklerin diğer adlara sahip olması yaygındır. Bunlar genellikle yazması daha kolay olan kısa formlardır. Diğer adlar, büyük/küçük harfe duyarsızlığın benzetimini yapmak ve bir sözcüğün alternatif yazımını desteklemek gibi başka amaçlar için de kullanılabilir.
POSIX kısa formlarının genellikle başında tek bir kısa çizgi ve ardından tek bir karakter bulunur. Aşağıdaki komutlar eşdeğerdir:
dotnet build --verbosity quiet
dotnet build -v quiet
GNU standardı otomatik diğer adları önerir. Başka bir ifadeyle, uzun formlu bir komutun veya seçenek adının herhangi bir bölümünü girebilirsiniz ve kabul edilir. Bu davranış aşağıdaki komut satırlarını eşdeğer hale getirir:
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
otomatik diğer adları desteklemez.
Büyük/küçük harfe duyarlı
Komut ve seçenek adları ve diğer adları POSIX kuralına göre varsayılan olarak büyük/küçük harfe duyarlıdır ve System.CommandLine
bu kuralı izler. CLI'nizin büyük/küçük harfe duyarsız olmasını istiyorsanız, çeşitli büyük/küçük harf alternatifleri için diğer adlar tanımlayın. Örneğin, --additional-probing-path
ve diğer adları --Additional-Probing-Path
--ADDITIONAL-PROBING-PATH
olabilir.
Bazı komut satırı araçlarında, büyük/küçük harf farkı işlevdeki farkı belirtir. Örneğin, git clean -X
değerinden git clean -x
farklı davranır. .NET CLI'nin tümü küçük harftir.
Büyük/küçük harf duyarlılığı, sabit listeleri temel alan seçenekler için bağımsız değişken değerlerine uygulanmaz. Numaralandırma adları büyük/küçük harfe bakılmaksızın eşleştirilir.
Belirteç --
POSIX kuralı, çift çizgili (--
) belirteci bir kaçış mekanizması olarak yorumlar. Çift çizgi belirtecini izleyen her şey komutun bağımsız değişkenleri olarak yorumlanır. Bu işlev, seçenekler gibi görünen bağımsız değişkenleri göndermek için kullanılabilir, çünkü bunların seçenek olarak yorumlanmasını önler.
Uygulamam'ın bağımsız message
değişken aldığını ve değerinin message
olmasını --interactive
istediğinizi varsayalım. Aşağıdaki komut satırı beklenmeyen sonuçlar verebilir.
myapp --interactive
Bir --interactive
seçeneği yoksamyapp
, --interactive
belirteç bağımsız değişken olarak yorumlanır. Ancak uygulamanın bir --interactive
seçeneği varsa, bu giriş bu seçeneğe başvuru olarak yorumlanır.
Aşağıdaki komut satırı, bağımsız değişkenin değerini message
"--interactive" olarak ayarlamak için çift tire belirtecini kullanır:
myapp -- --interactive
^^
System.CommandLine
bu çift çizgi işlevselliğini destekler.
Seçenek-bağımsız değişken sınırlayıcıları
System.CommandLine
bir seçenek adı ile bağımsız değişkeni arasında sınırlayıcı olarak boşluk, '=' veya ':' kullanmanıza olanak tanır. Örneğin, aşağıdaki komutlar eşdeğerdir:
dotnet build -v quiet
dotnet build -v=quiet
dotnet build -v:quiet
POSIX kuralı, tek karakterli bir seçenek diğer adı belirtirken sınırlayıcıyı atlamanıza olanak tanır. Örneğin, aşağıdaki komutlar eşdeğerdir:
myapp -vquiet
myapp -v quiet
System.CommandLine varsayılan olarak bu söz dizimlerini destekler.
Bağımsız değişken arity
Bir seçeneğin veya komutun bağımsız değişkeninin arlığı , bu seçenek veya komut belirtilirse geçirilebilen değerlerin sayısıdır.
Arity, aşağıdaki tabloda gösterildiği gibi en düşük değer ve en yüksek değerle ifade edilir:
Minimum | Max | Örnek geçerlilik | Örnek |
---|---|---|---|
0 | 0 | Geçerli: | --Dosya |
Geçersiz: | --file a.json | ||
Geçersiz: | --file a.json --file b.json | ||
0 | 1 | Geçerli: | --Bayrak |
Geçerli: | --flag true | ||
Geçerli: | --flag false | ||
Geçersiz: | --flag false --flag false | ||
1 | 1 | Geçerli: | --file a.json |
Geçersiz: | --Dosya | ||
Geçersiz: | --file a.json --file b.json | ||
0 | n | Geçerli: | --Dosya |
Geçerli: | --file a.json | ||
Geçerli: | --file a.json --file b.json | ||
1 | n | Geçerli: | --file a.json |
Geçerli: | --file a.json b.json | ||
Geçersiz: | --Dosya |
System.CommandLine
aşağıdaki değerlerle birlikte arity tanımlamaya yönelik bir ArgumentArity yapıya sahiptir:
- Zero - Hiçbir değere izin verilmez.
- ZeroOrOne - Tek bir değere sahip olabilir, değer olmayabilir.
- ExactlyOne - Tek bir değere sahip olmalıdır.
- ZeroOrMore - Bir değere, birden çok değere sahip olabilir veya değer olmayabilir.
- OneOrMore - Birden çok değer olabilir, en az bir değere sahip olmalıdır.
Arity genellikle türünden çıkarılabilir. Örneğin, bir int
seçeneğin arity'i ExactlyOne
ve bir List<int>
seçeneğin arity'i vardır OneOrMore
.
Seçenek geçersiz kılmaları
Maksimum değer 1 ise, System.CommandLine
yine de bir seçeneğin birden çok örneğini kabul etmek üzere yapılandırılabilir. Bu durumda, yinelenen bir seçeneğin son örneği önceki örneklerin üzerine yazar. Aşağıdaki örnekte, 2 değeri komutuna myapp
geçirilir.
myapp --delay 3 --message example --delay 2
Birden çok bağımsız değişken
Arity maksimum değeri birden fazlaysa, System.CommandLine
seçenek adını yinelemeden bir seçenek için birden çok bağımsız değişkeni kabul etmek üzere yapılandırılabilir.
Aşağıdaki örnekte, komuta geçirilen myapp
liste "a", "b", "c" ve "d" içerir:
myapp --list a b c --list d
Seçenek paketleme
POSIX, yığınlama olarak da bilinen tek karakterli seçeneklerin paketlemesini desteklemenizi önerir. Paketlenmiş seçenekler, tek bir kısa çizgi ön eki sonrasında birlikte belirtilen tek karakterli seçenek diğer adlarıdır. Yalnızca son seçenek bir bağımsız değişken belirtebilir. Örneğin, aşağıdaki komut satırları eşdeğerdir:
git clean -f -d -x
git clean -fdx
Seçenek paketinden sonra bir bağımsız değişken sağlanırsa, paketteki son seçenek için geçerlidir. Aşağıdaki komut satırları eşdeğerdir:
myapp -a -b -c arg
myapp -abc arg
Bu örnekteki her iki değişkende de bağımsız değişken arg
yalnızca seçeneğine -c
uygulanır.
Boole seçenekleri (bayraklar)
Bağımsız değişken içeren bool
bir seçenek için veya false
geçirilirsetrue
, beklendiği gibi ayrıştırılır. Ancak bağımsız değişken türü bool
genellikle bir bağımsız değişkenin belirtilmesi gerekmez. Bazen "bayraklar" olarak da adlandırılan Boole seçeneklerinde genellikle bir arity değeri ZeroOrOnevardır. Komut satırında seçenek adının varlığı, onu izleyen bağımsız değişken olmadan varsayılan değerini verir true
. Komut satırı girişinde seçenek adının olmaması değerini verir false
. myapp
Komut adlı --interactive
bir Boole seçeneğinin değerini yazdırırsa, aşağıdaki giriş aşağıdaki çıkışı oluşturur:
myapp
myapp --interactive
myapp --interactive false
myapp --interactive true
False
True
False
True
--help seçeneği
Komut satırı uygulamaları genellikle kullanılabilir komutların, seçeneklerin ve bağımsız değişkenlerin kısa bir açıklamasını görüntüleme seçeneği sağlar. System.CommandLine
otomatik olarak yardım çıkışı oluşturur. Örneğin:
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.
Uygulama kullanıcıları farklı platformlarda yardım istemek için farklı yöntemlere alışkın olabilir, bu nedenle yerleşik System.CommandLine
uygulamalar yardım istemenin birçok yoluna yanıt verir. Aşağıdaki komutların tümü eşdeğerdir:
dotnet --help
dotnet -h
dotnet /h
dotnet -?
dotnet /?
Yardım çıkışının kullanılabilir tüm komutları, bağımsız değişkenleri ve seçenekleri göstermesi gerekmez. Bazıları gizlenmiş olabilir; bu da yardım çıkışında görünmedikleri ancak komut satırında belirtilebileceği anlamına gelir.
--version seçeneği
Üzerinde System.CommandLine
oluşturulan uygulamalar, kök komutuyla kullanılan seçeneğe --version
yanıt olarak sürüm numarasını otomatik olarak sağlar. Örneğin:
dotnet --version
6.0.100
Yanıt dosyaları
Yanıt dosyası, komut satırı uygulaması için belirteç kümesi içeren bir dosyadır. Yanıt dosyaları, iki senaryoda yararlı olan bir özelliğidir System.CommandLine
:
- Terminalin karakter sınırından daha uzun bir giriş belirterek bir komut satırı uygulaması çağırmak için.
- Satırın tamamını yeniden oluşturmadan aynı komutu art arda çağırmak için.
Yanıt dosyası kullanmak için, satırda komut, seçenek ve bağımsız değişken eklemek istediğiniz herhangi bir @
yere ön ekli dosya adını girin. .rsp dosya uzantısı yaygın bir kuraldır, ancak herhangi bir dosya uzantısını kullanabilirsiniz.
Aşağıdaki satırlar eşdeğerdir:
dotnet build --no-restore --output ./build-output/
dotnet @sample1.rsp
dotnet build @sample2.rsp --output ./build-output/
sample1.rsp içeriği:
build
--no-restore
--output
./build-output/
sample2.rsp içeriği:
--no-restore
Yanıt dosyasındaki metnin nasıl yorumlandığını belirleyen söz dizimi kuralları şunlardır:
- Belirteçler boşluklarla sınırlandırılır. Günaydın! içeren bir satır iki belirteç olarak değerlendirilir: İyi ve sabah!.
- Tırnak içine alınmış birden çok belirteç tek bir belirteç olarak yorumlanır. "Günaydın!" ifadesini içeren bir satır tek bir belirteç olarak değerlendirilir, Günaydın!.
- Simge
#
ile satırın sonu arasındaki tüm metinler açıklama olarak değerlendirilir ve yoksayılır. - ön ekli
@
belirteçler ek yanıt dosyalarına başvurabilir. - Yanıt dosyasında birden çok metin satırı olabilir. Satırlar birleştirilir ve belirteç dizisi olarak yorumlanır.
Yönergeler
System.CommandLine
yönergesi olarak adlandırılan bir sözdizimi öğesi tanıtır. yönergesi [parse]
bir örnektir. Uygulamanın adından sonra eklediğinizde [parse]
, System.CommandLine
komut satırı uygulamasını çağırmak yerine ayrıştırma sonucunun diyagramını görüntüler:
dotnet [parse] build --no-restore --output ./build-output/
^-----^
[ dotnet [ build [ --no-restore <True> ] [ --output <./build-output/> ] ] ]
Yönergelerin amacı, komut satırı uygulamaları arasında uygulanabilecek çapraz kesme işlevleri sağlamaktır. Yönergeler, uygulamanın kendi söz diziminden söz diziminden söz diziminden ayrı olduğundan, uygulamalar arasında geçerli olan işlevleri sağlayabilir.
Yönerge aşağıdaki söz dizimi kurallarına uymalıdır:
- Komut satırında uygulama adından sonra gelen ancak alt komutlardan veya seçeneklerden önce gelen bir belirteçtir.
- Köşeli ayraç içine alınmış.
- Boşluk içermez.
Tanınmayan yönerge ayrıştırma hatasına neden olmadan yoksayılır.
Yönerge, yönerge adından iki nokta üst üste ile ayrılmış bir bağımsız değişken içerebilir.
Aşağıdaki yönergeler yerleşik olarak bulunur:
yönergesi [parse]
Hem kullanıcılar hem de geliştiriciler, bir uygulamanın belirli bir girişi nasıl yorumlayacaklarını görmek yararlı olabilir. Bir System.CommandLine
uygulamanın varsayılan özelliklerinden biri, komut girişini ayrıştırma işleminin sonucunu önizlemenizi sağlayan yönergedir [parse]
. Örneğin:
myapp [parse] --delay not-an-int --interactive --file filename.txt extra
![ myapp [ --delay !<not-an-int> ] [ --interactive <True> ] [ --file <filename.txt> ] *[ --fgcolor <White> ] ] ???--> extra
Yukarıdaki örnekte:
- Komutu (
myapp
), alt seçenekleri ve bu seçeneklerin bağımsız değişkenleri köşeli ayraçlar kullanılarak gruplandırılır. - seçenek sonucu
[ --delay !<not-an-int> ]
için ,!
bir ayrıştırma hatası gösterir. Birint
seçeneğin değerinot-an-int
beklenen türe ayrıştırılamaz. Hata, şu hata seçeneğini içeren komutun önünde tarafından da işaretlenir!
:![ myapp...
. - Seçenek sonucu
*[ --fgcolor <White> ]
için, seçenek komut satırında belirtilmedi, bu nedenle yapılandırılan varsayılan kullanıldı.White
bu seçenek için geçerli değerdir. Yıldız işareti, değerin varsayılan değer olduğunu gösterir. ???-->
uygulama komutlarından veya seçeneklerinden hiçbirine eşleşmemiş girişi gösterir.
yönergesi [suggest]
yönergesi, [suggest]
tam olarak komutu bilmediğiniz komutları aramanıza olanak tanır.
dotnet [suggest] buil
build
build-server
msbuild
Tasarım kılavuzu
Aşağıdaki bölümlerde, CLI tasarlarken izlemenizi önerdiğimiz yönergeler verilmiştir. Uygulamanızın komut satırında ne beklediğini, REST API sunucusunun URL'de beklediğine benzer şekilde düşünün. REST API'ler için tutarlı kurallar, istemci uygulama geliştiricileri tarafından kolayca kullanılabilir olmalarını sağlar. Aynı şekilde, CLI tasarımı yaygın desenleri izlerse komut satırı uygulamalarınızın kullanıcıları daha iyi bir deneyime sahip olur.
Bir CLI oluşturduktan sonra, özellikle de kullanıcılarınız cli'nizi çalışmaya devam etmesini bekledikleri betiklerde kullandıysa değiştirmek zordur. Buradaki yönergeler .NET CLI sonrasında geliştirilmiştir ve her zaman bu yönergeleri izlemez. Hataya neden olan değişikliklere gerek kalmadan .NET CLI'yi güncelleştiriyoruz. Bu çalışmaya örnek olarak .NET 7'deki için yeni tasarım dotnet new
verilmiştir.
Komutlar ve alt komutlar
Bir komutun alt komutları varsa, komutun bir eylem belirtmek yerine alt komutlar için bir alan veya gruplandırma tanımlayıcısı olarak çalışması gerekir. Uygulamayı çağırdığınızda gruplandırma komutunu ve alt komutlarından birini belirtirsiniz. Örneğin, komutunu çalıştırmayı dotnet tool
deneyin ve komutu yalnızca ve list
gibi install
araçla ilgili bir alt komut grubunu tanımladığından tool
bir hata iletisi alırsınız. komutunu çalıştırabilirsiniz dotnet tool install
, ancak dotnet tool
kendi başına tamamlanmamış olur.
Alanları tanımlamanın, kullanıcılarınızın yardım çıkışını düzenlemesine yardımcı olmanın yollarından biri.
CLI içinde genellikle örtük bir alan vardır. Örneğin, .NET CLI'da örtük alan projedir ve Docker CLI'da görüntüdür. Sonuç olarak, bir alan eklemeden kullanabilirsiniz dotnet build
. CLI'nizin örtük bir alanı olup olmadığını göz önünde bulundurun. Varsa, kullanıcının isteğe bağlı olarak ve docker image build
içinde olarak docker build
eklemesine veya atmasına izin verip vermeyeceğini göz önünde bulundurun. İsteğe bağlı olarak örtük alanın kullanıcınız tarafından yazılmasına izin verirseniz, bu komut grubu için otomatik olarak yardım ve sekme tamamlamanız da olur. Aynı işlemi gerçekleştiren iki komut tanımlayarak örtük grubun isteğe bağlı kullanımını sağlayın.
Parametre olarak seçenekler
Seçenekler, eylemlerin kendilerini belirtmek yerine komutlara parametre sağlamalıdır. Bu önerilen bir tasarım ilkesidir, ancak her zaman takip System.CommandLine
edilmez (--help
yardım bilgilerini görüntüler).
Kısa formlu diğer adlar
Genel olarak, tanımladığınız kısa biçimli seçenek diğer adlarının sayısını en aza indirmenizi öneririz.
Özellikle, aşağıdaki diğer adlardan herhangi birini .NET CLI ve diğer .NET komut satırı uygulamalarında ortak kullanımlarından farklı kullanmaktan kaçının:
-i
için--interactive
.Bu seçenek kullanıcıya komutun yanıtlanması gereken sorulara giriş istenebileceğini bildirir. Örneğin, kullanıcı adı isteme. CLI'niz betiklerde kullanılabilir, bu nedenle bu anahtarı belirtmemiş kullanıcılara sorulduğunda dikkatli olun.
-o
için--output
.Bazı komutlar, yürütmeleri sonucunda dosya üretir. Bu seçenek, bu dosyaların nerede bulunması gerektiğini saptamaya yardımcı olmak için kullanılmalıdır. Tek bir dosyanın oluşturulduğu durumlarda, bu seçenek bir dosya yolu olmalıdır. Birçok dosya oluşturulduğu durumlarda, bu seçenek bir dizin yolu olmalıdır.
-v
için--verbosity
.Komutlar genellikle konsoldaki kullanıcıya çıkış sağlar; bu seçenek, kullanıcının istediği çıkış miktarını belirtmek için kullanılır. Daha fazla bilgi için bu makalenin devamında yer alan Seçeneği
--verbosity
bölümüne bakın.
.NET CLI ile sınırlı ortak kullanıma sahip bazı diğer adlar da vardır. Uygulamalarınızdaki diğer seçenekler için bu diğer adları kullanabilirsiniz, ancak karışıklık olasılığına dikkat edin.
--configuration
için-c
Bu seçenek genellikle veya
Release
gibiDebug
adlandırılmış bir Derleme Yapılandırmasına başvurur. Yapılandırma için istediğiniz herhangi bir adı kullanabilirsiniz, ancak çoğu araç bunlardan birini bekler. Bu ayar genellikle diğer özellikleri bu yapılandırma için anlamlı bir şekilde yapılandırmak için kullanılır; örneğin, yapılandırmayı oluştururken daha az kod iyileştirmesiDebug
yapma. Komutunuzda farklı işlem modları varsa bu seçeneği göz önünde bulundurun.--framework
için-f
Bu seçenek, yürütülecek tek bir Hedef Çerçeve Takma Adı (TFM) seçmek için kullanılır, dolayısıyla CLI uygulamanızın hangi TFM'nin seçildiğine bağlı olarak farklı davranışlara sahipse bu bayrağı desteklemeniz gerekir.
--property
için-p
Uygulamanız sonunda MSBuild'i çağırırsa, kullanıcının genellikle bu çağrıyı bir şekilde özelleştirmesi gerekir. Bu seçenek, MSBuild özelliklerinin komut satırında sağlanmasına ve temel alınan MSBuild çağrısına geçirilmesine olanak tanır. Uygulamanız MSBuild kullanmıyorsa ancak bir anahtar-değer çifti kümesine ihtiyaç duyuyorsa, kullanıcıların beklentilerinden yararlanmak için aynı seçenek adını kullanmayı göz önünde bulundurun.
--runtime
için-r
Uygulamanız farklı çalışma zamanlarında çalıştırılabilirse veya çalışma zamanına özgü mantığı varsa, çalışma Zamanı Tanımlayıcısı belirtmenin bir yolu olarak bu seçeneği desteklemeyi göz önünde bulundurun. Uygulamanız --runtime'ı destekliyorsa ve'yi
--arch
de desteklemeyi--os
göz önünde bulundurun. Bu seçenekler RID'nin yalnızca işletim sistemi veya mimari bölümlerini belirtmenize olanak sağlar ve bölümün geçerli platformdan belirlenmek üzere belirtilmemiş olmasını sağlar. Daha fazla bilgi için bkz . dotnet publish.
Kısa adlar
Komutların, seçeneklerin ve bağımsız değişkenlerin adlarını olabildiğince kısa ve kolay yazabilirsiniz. Örneğin, yeterince açıksa class
komutunu classification
yapmayın.
Küçük harfli adlar
Komutları veya seçenekleri büyük/küçük harfe duyarsız hale getirmek için büyük harfli diğer adlar yapabilmeniz dışında, adları yalnızca küçük harfle tanımlayın.
Kebap servis talebi adları
Sözcükleri ayırt etmek için kebap büyük/küçük harf kullanın. Örneğin, --additional-probing-path
.
Çoğullaştırma
Bir uygulama içinde çoğullaştırmada tutarlı olun. Örneğin, birden çok değere (birden fazla maksimum arity) sahip olabilecek seçenekler için çoğul ve tekil adları karıştırmayın:
Seçenek adları | Tutarlılık |
---|---|
--additional-probing-paths ve --sources |
✔️ |
--additional-probing-path ve --source |
✔️ |
--additional-probing-paths ve --source |
❌ |
--additional-probing-path ve --sources |
❌ |
Fiiller ve isim karşılaştırması
Eylemlere başvuran komutlar (altında alt komutları olmayanlar) için isim yerine fiiller kullanın, örneğin: dotnet workload remove
değil dotnet workload removal
. Ayrıca seçenekler için fiiller yerine isimleri kullanın; örneğin: --configuration
, değil --configure
.
Seçeneği --verbosity
System.CommandLine
uygulamalar genellikle konsola ne kadar çıkış gönderileceğini belirten bir --verbosity
seçenek sunar. Standart beş ayar şunlardır:
Q[uiet]
M[inimal]
N[ormal]
D[etailed]
Diag[nostic]
Bunlar standart adlardır, ancak mevcut uygulamalar bazen yerine , ve , veya Diagnostic
yerine kullanır Silent
Quiet
. Debug
Verbose
Trace
Her uygulama, her düzeyde nelerin görüntüleneceğini belirleyen kendi ölçütlerini tanımlar. Genellikle bir uygulamanın yalnızca üç düzeye ihtiyacı vardır:
- Quiet
- Normal
- Tanılama
Bir uygulamanın beş farklı düzeye ihtiyacı yoksa, seçenek yine de aynı beş ayarı tanımlamalıdır. Bu durumda ve Minimal
Normal
aynı çıktıyı üretir ve Detailed
Diagnostic
benzer şekilde aynı olur. Bu, kullanıcılarınızın yalnızca tanıdıklarını yazmasına olanak tanır ve en uygun olan kullanılır.
için beklenen Quiet
, konsolunda hiçbir çıkış görüntülenmemiş olmasıdır. Ancak, bir uygulama etkileşimli mod sunuyorsa, uygulama aşağıdaki alternatiflerden birini yapmalıdır:
- belirtilmiş olsa
--verbosity
Quiet
bile giriş--interactive
istemlerini görüntüler. - ve'nin
--interactive
birlikte kullanılmasına--verbosity Quiet
izin verme.
Aksi takdirde uygulama, kullanıcıya ne beklediğini belirtmeden girişi bekler. Uygulamanızın donduğunu ve kullanıcının uygulamanın giriş beklediğinden haberi olmayacaktır.
Diğer adlar tanımlarsanız, için kullanın -v
ve bağımsız değişken olmadan için --verbosity Diagnostic
bir diğer ad yapın-v
.--verbosity
için --verbosity Quiet
kullanın-q
.
.NET CLI ve POSIX kuralları
.NET CLI, tüm POSIX kurallarını tutarlı bir şekilde izlemez.
Çift çizgi
.NET CLI'daki çeşitli komutlar çift çizgili belirtecin özel bir uygulamasına sahiptir. , ve dotnet tool run
durumundadotnet run
dotnet watch
, izleyen --
belirteçler komutu tarafından çalıştırılan uygulamaya geçirilir. Örneğin:
dotnet run --project ./myapp.csproj -- --message "Hello world!"
^^
Bu örnekte, --project
seçeneği komutuna dotnet run
geçirilir ve --message
bağımsız değişkenine sahip seçenek, çalıştırıldığında uygulamama komut satırı seçeneği olarak geçirilir.
--
kullanarak çalıştırdığınız dotnet run
bir uygulamaya seçenekleri geçirmek için belirteç her zaman gerekli değildir. Çift tire olmadan, dotnet run
komut otomatik olarak uygulamaya geçirerek kendisine veya MSBuild'e dotnet run
uygulandığı kabul edilmeen seçenekleri çalıştırır. Bu nedenle, bağımsız değişkenleri ve seçenekleri tanımadığından dotnet run
aşağıdaki komut satırları eşdeğerdir:
dotnet run -- quotes read --delay 0 --fg-color red
dotnet run quotes read --delay 0 --fg-color red
Seçenek-bağımsız değişken sınırlayıcının atlanmış olması
.NET CLI, tek karakterli bir seçenek diğer adı belirtirken sınırlayıcıyı atlamanıza olanak tanıyan POSIX kuralını desteklemez.
Seçenek adını yinelemeden birden çok bağımsız değişken
.NET CLI, seçenek adını yinelemeden bir seçenek için birden çok bağımsız değişken kabul etmez.
Boole seçenekleri
.NET CLI'de, bazı Boole seçenekleri ile geçiş false
true
yaptığınızda aynı davranışa neden olur. Bu davranış, seçeneği uygulayan .NET CLI kodu yalnızca seçeneğin varlığını veya yokluğunu denetlediğinde ve değeri yoksaydığında sonuç verir. Komutuna örnek olarak --no-restore
verilmiştir dotnet build
. Geçiş no-restore false
ve geri yükleme işlemi, veya no-restore
belirttiğinizde no-restore true
olduğu gibi atlanır.
Kebap olayı
Bazı durumlarda,.NET CLI komut, seçenek veya bağımsız değişken adları için kebap büyük/küçük harf kullanmaz. Örneğin, yerine --additional-probing-path
adlı --additionalprobingpath
bir .NET CLI seçeneği vardır.