Aracılığıyla paylaş

Tasarım kılavuzu

Aşağıdaki bölümlerde CLI tasarlama yönergeleri 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.

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.

Semboller

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, dotnet tool komutunu çalıştırmayı deneyin ve tool komutunun, install ve list gibi araçlarla ilgili alt komutlar grubunu yalnızca tanımladığından bir hata mesajı 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'de ö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 docker build ve docker image build eklemesine veya çıkartmasına izin verip vermeyeceğinizi göz önünde bulundurun. İsteğe bağlı olarak varsayılan alanın kullanıcınız tarafından yazılmasına izin verirseniz, bu komut grubu için otomatik olarak yardım ve sekme tamamlama sağlanır. 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 System.CommandLine tarafından her zaman takip edilmez (--help yardım bilgilerini gösterir).

Adlandırma

Kısa formlu diğer adlar

Genel olarak, tanımladığınız kısa biçimli seçeneklerin diğer adlarının sayısını en aza indirmek en iyisidir.

Ö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ılabileceğinden, bu anahtarı belirtmemiş olan kullanıcılara soru sorarken 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.

  • -c için --configuration

    Bu seçenek genellikle Debug veya Release gibi 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, o yapılandırmayı anlamlı hale getirmek için yapılandırmak amacıyla kullanılır; örneğin, Debug yapılandırma yapılırken daha az kod iyileştirmesi yapılması. Komutunuzda farklı işlem modları varsa bu seçeneği göz önünde bulundurun.

  • -f için --framework

    Bu seçenek, yürütülecek tek bir Hedef Çerçeve Takma Adı (TFM) seçmek için kullanılır. Eğer CLI uygulamanız, seçilen TFM'ye bağlı olarak farklı davranışlar sergiliyorsa bu bayrağı desteklemeniz önemlidir.

  • -p için --property

    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.

  • -r için --runtime

    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, --os ve --arch'yi de desteklemeyi göz önünde bulundurun. RID'nin yalnızca işletim sistemi veya mimari bölümlerini belirtmenize olanak tanıyan bu seçeneklerle, belirtilmeyen kısım mevcut platformdan otomatik olarak belirlenir. 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

Adları sadece küçük harfle tanımlayın, ancak komutları veya seçenekleri büyük/küçük harf duyarsız hale getirmek için büyük harfle takma adlar oluşturabilirsiniz.

Kebap durum adları

Sözcükleri ayırt etmek için kebab case, yani kelimeler arasında tire kullanın. Örneğin, --additional-probing-path.

Çoğullaştırma

Bir uygulama içinde çoğullaştırmada tutarlı olun. Örneğin, birden fazla değere (maksimum aradeğer birden büyük) sahip olabilecek seçenekler için tekil ve çoğul 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 Silent yerine Quiet kullanır ve Trace yerine Debug, Verbose veya Diagnostic kullanır.

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:

  • Sessiz
  • Sıradan
  • Tanı

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 bildiklerini yazmasına olanak tanır ve en doğru olanı kullanılır.

Quiet için beklenti, konsolda hiçbir çıktının görünmemesidir. Ancak, bir uygulama etkileşimli mod sunuyorsa, uygulama aşağıdakilerden birini yapmalıdır:

  • --interactive belirtilmiş olduğunda, --verbosityQuiet bile giriş istemlerini görüntüle.
  • Birlikte --verbosity Quiet ve --interactive kullanılmasına izin verme.

Aksi takdirde uygulama, kullanıcıya ne beklediğini belirtmeden girişi bekler. Uygulamanız donmuş gibi görünecek ve kullanıcının uygulamanın girdisi beklediğinden hiçbir şekilde haberi olmayacak.

Diğer adlar tanımlarsanız, -v için --verbosity kullanın ve bağımsız değişken olmadan -v'yi --verbosity Diagnostic için bir diğer ad yapın. -q için --verbosity Quiet kullanın.

.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. dotnet run, dotnet watch ve dotnet tool run durumunda, --'yi izleyen belirteçler, komut 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 dotnet run komutuna geçirilir ve --message seçeneği bağımsız değişkeniyle birlikte çalıştırıldığında myapp'e komut satırı seçeneği olarak geçirilir.

-- kullanarak çalıştırdığınız bir uygulamaya seçenekleri geçirmek için, dotnet run belirteç her zaman gerekli değildir. Çift tire olmadan, dotnet run komutu, kendisine veya MSBuild'e uygulandığı kabul edilmeyen seçenekleri otomatik olarak çalıştırılan uygulamaya aktarı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.

Birden çok bağımsız değişkeni seçenek adını yinelemeden belirtme

.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çeneklerini geçiş false veya true yaptığınızda aynı davranış görülür. Bu davranış, seçeneği uygulayan .NET CLI kodu yalnızca seçeneğin varlığını veya yokluğunu denetleyip değeri yoksaydığında meydana gelir. Örnek olarak --no-restore komutu için dotnet build verilmiştir. --no-restore false verildiğinde ve --no-restore true veya --no-restore belirttiğinizde olduğu gibi geri yükleme işlemi atlanacaktır.

Kebap olayı

Bazı durumlarda, .NET CLI komut, seçenek veya bağımsız değişken adları için kebap durumu kullanmaz. Örneğin, yerine --additionalprobingpathadlı --additional-probing-path bir .NET CLI seçeneği vardır.

Ayrıca bakınız

  • Last updated on