için komut satırı söz dizimine genel bakış System.CommandLine

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.CommandLinekomut 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, --verbosityve quietiç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 ve tool ilgili komutlardan oluşan bir grubu belirten bir komut. , tool listve tool updategibi tool uninstallaraç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 --globalhiç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 --verbositybiri 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-PATHolabilir.

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 -xfarklı 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ı --interactiveistediğ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 ExactlyOneve 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 -cuygulanı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ı --interactivebir 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.CommandLineyö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:

• [parse]
• [suggest]

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. Bir int seçeneğin değeri not-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 tooldeneyin ve komutu yalnızca ve listgibi 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 buildiç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 Releasegibi Debug 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ştirmesi Debug 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 classificationyapmayı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 removedeğ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 Diagnosticyerine kullanır SilentQuiet. DebugVerboseTrace

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 MinimalNormal aynı çıktıyı üretir ve DetailedDiagnostic 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 --verbosityQuietbile 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 Diagnosticbir diğer ad yapın-v.--verbosity için --verbosity Quietkullanı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 rundurumundadotnet rundotnet 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 runbir 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ş falsetrueyaptığı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-restorebelirttiğ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-pathadlı --additionalprobingpath bir .NET CLI seçeneği vardır.

Ayrıca bkz.

• Açık kaynak CLI tasarım kılavuzu
• GNU standartları
• System.CommandLine Genel bakış
• Öğretici: Kullanmaya başlama System.CommandLine