Pokyny pro návrh

2025-06-19

Následující části obsahují pokyny, které doporučujeme dodržovat při návrhu rozhraní příkazového řádku. Představte si, co vaše aplikace očekává na příkazovém řádku, podobně jako server REST API v adrese URL. Konzistentní pravidla pro rozhraní REST API jsou to, co je snadno použitelné pro vývojáře klientských aplikací. Stejně tak budou mít uživatelé aplikací příkazového řádku lepší prostředí, pokud návrh rozhraní příkazového řádku dodržuje běžné vzory.

Po vytvoření rozhraní příkazového řádku je obtížné ho změnit, zejména pokud vaši uživatelé použili rozhraní příkazového řádku ve skriptech, u kterých očekávají, že budou dál běžet. Pokyny zde byly vyvinuty po rozhraní příkazového řádku .NET a tyto pokyny se vždy nedodržují. Aktualizujeme rozhraní příkazového řádku .NET, kde to můžeme udělat bez zavedení zásadních změn. Příkladem této práce je nový návrh pro dotnet new .NET 7.

Symboly

Příkazy a dílčí příkazy

Pokud má příkaz podpříkazy, měl by příkaz fungovat jako oblast nebo identifikátor seskupení pro dílčí příkazy, a ne zadat akci. Při vyvolání aplikace zadáte příkaz seskupení a jeden z jeho dílčích příkazů. Zkuste například spustit dotnet toola zobrazí se chybová zpráva, protože tool příkaz identifikuje pouze skupinu dílčích příkazů souvisejících s nástroji, například install a list. Můžete spustit dotnet tool install, ale dotnet tool sám by byl neúplný.

Jedním ze způsobů, jak definování oblastí pomáhá uživatelům, je uspořádat výstup nápovědy.

V rozhraní příkazového řádku je často implicitní oblast. Například v rozhraní .NET CLI je implicitní oblast projekt a v Rozhraní příkazového řádku Dockeru je to image. V důsledku toho můžete použít dotnet build bez zahrnutí oblasti. Zvažte, jestli má vaše rozhraní příkazového řádku implicitní oblast. Pokud ano, zvažte, zda uživateli umožnit zahrnutí nebo vynechání podle vlastní volby, jako v docker build a docker image build. Pokud volitelně povolíte zadání implicitní oblasti uživatelem, budete mít také automaticky nápovědu a dokončování tabulátoru pro toto seskupení příkazů. Zadejte volitelné použití implicitní skupiny definováním dvou příkazů, které provádějí stejnou operaci.

Možnosti jako parametry

Možnosti by měly poskytovat parametry příkazům, a ne zadávat samotné akce. Jedná se o doporučený princip návrhu, i když není vždy následovaný System.CommandLine (--help zobrazí informace nápovědy).

Pojmenování

Krátké aliasy

Obecně doporučujeme minimalizovat počet zkratek pro možnosti, které definujete.

Konkrétně nepoužívejte žádný z následujících aliasů jinak než jejich běžné použití v rozhraní příkazového řádku .NET CLI a jiných aplikacích příkazového řádku .NET:

-i pro --interactive.

Tato možnost signalizuje uživateli, že může být vyzván k zadání vstupů na otázky, na které příkaz potřebuje odpovědět. Zobrazí se například výzva k zadání uživatelského jména. Rozhraní příkazového řádku může být používáno ve skriptech, proto buďte opatrní při vyzývání uživatelů, kteří tento přepínač nezadali.
-o pro --output.

Některé příkazy vytvářejí soubory v důsledku jejich provádění. Tato možnost by měla sloužit k určení umístění těchto souborů. V případech, kdy se vytvoří jeden soubor, by tato možnost měla být cesta k souboru. V případech, kdy se vytvoří mnoho souborů, by tato možnost měla být cesta k adresáři.
-v pro --verbosity.

Příkazy často poskytují výstup uživateli v konzole; tato možnost slouží k určení množství výstupu požadavků uživatele. Další informace naleznete v části Možnost--verbosity, dále v tomto článku.

Existují také některé aliasy s běžným využitím omezenými na .NET CLI. Tyto aliasy můžete použít pro jiné možnosti v aplikacích, ale mějte na paměti možnost nejasnosti.

-c pro --configuration

Tato možnost často odkazuje na pojmenovanou konfiguraci sestavení, například Debug nebo Release. Pro konfiguraci můžete použít libovolný název, ale většina nástrojů očekává jeden z nich. Toto nastavení se často používá ke konfiguraci jiných vlastností způsobem, který dává smysl pro danou konfiguraci – například provádět méně optimalizace kódu při sestavování Debug konfigurace. Tuto možnost zvažte, pokud má váš příkaz různé režimy provozu.
-f pro --framework

Tato možnost slouží k výběru jednoho monikeru cílového rozhraní (TFM), pro který se má aplikace spustit. Pokud má vaše aplikace příkazového řádku různé chování podle zvoleného TFM, měli byste podporovat tento příznak.
-p pro --property

Pokud vaše aplikace nakonec vyvolá MSBuild, uživatel bude často muset přizpůsobit toto volání nějakým způsobem. Tato možnost umožňuje, aby vlastnosti MSBuild byly zadány na příkazovém řádku a předány dále do podkladového volání MSBuild. Pokud vaše aplikace nepoužívá MSBuild, ale potřebuje sadu párů klíč-hodnota, zvažte použití stejného názvu možnosti nastavení, abyste využili očekávání uživatelů.
-r pro --runtime

Pokud vaše aplikace může běžet v různých modulech runtime nebo má logiku specifickou pro modul runtime, zvažte podporu této možnosti jako způsob určení identifikátoru modulu runtime. Pokud vaše aplikace podporuje --runtime, zvažte podporu --os a --arch také. Tyto možnosti umožňují zadat pouze operační systém nebo architektonické části identifikátoru RID, přičemž část, která není specifikována, bude odvozena z aktuální platformy. Další informace najdete v tématu dotnet publish.

Krátké názvy

Zvolte názvy pro příkazy, možnosti a argumenty co nejkratší a co nejsnadněji psatelné. Pokud class je například dostatečně jasné, nevytvávejte příkaz classification.

Malá písmena ve jménech

Definujte názvy pouze malými písmeny, ale můžete použít velké aliasy, aby byly příkazy nebo možnosti necitlivé na velká a malá písmena.

Názvy v kebabovém zápisu

K rozlišení slov použijte kebab case . Například: --additional-probing-path.

Pluralizace

V rámci aplikace musí být konzistentní v pluralizaci. Například nemíchejte množné číslo a jednoznačný název pro možnosti, které můžou mít více hodnot (maximálně jedno):

Názvy možností	Konzistence
`--additional-probing-paths` a `--sources`	✔️
`--additional-probing-path` a `--source`	✔️
`--additional-probing-paths` a `--source`	❌
`--additional-probing-path` a `--sources`	❌

Slovesa vs. podstatná jména

Pro příkazy, které odkazují na akce (ty bez dílčích příkazů), použijte příkazy místo podstatných jmen, například: dotnet workload remove, ne dotnet workload removal. A místo sloves použijte pro možnosti podstatná jména, například: --configuration, ne --configure.

Možnost `--verbosity`

System.CommandLine aplikace obvykle nabízejí --verbosity možnost, která určuje, kolik výstupu se odešle do konzoly. Toto je standardní pět nastavení:

Q[uiet]
M[inimal]
N[ormal]
D[etailed]
Diag[nostic]

Jedná se o standardní názvy, ale stávající aplikace někdy používají Silent místo Quiet, a Trace, Debugnebo Verbose místo Diagnostic.

Každá aplikace definuje vlastní kritéria, která určují, co se zobrazí na jednotlivých úrovních. Aplikace obvykle potřebuje jenom tři úrovně:

Tichý
Normální
Diagnostika

Pokud aplikace nepotřebuje pět různých úrovní, měla by tato možnost stále definovat stejná pět nastavení. V takovém případě Minimal a Normal vytvoří stejný výstup a DetailedDiagnostic bude stejně stejný. To umožňuje uživatelům jednoduše zadat, co dobře znají, a použije se nejvhodnější možnost.

Očekávání pro Quiet je, že se na konzoli nezobrazí žádný výstup. Pokud ale aplikace nabízí interaktivní režim, měla by aplikace udělat jednu z těchto věcí:

Zobrazí výzvy k zadání vstupu, pokud je specifikován --interactive, i když --verbosity je Quiet.
Nepovoluje používání --verbosity Quiet a --interactive společně.

V opačném případě aplikace počká na vstup, aniž by uživateli řekl, na co čeká. Zobrazí se, že vaše aplikace zmrzla a uživatel nebude mít představu, že aplikace čeká na vstup.

Pokud definujete aliasy, použijte -v pro --verbosity a použijte -v bez argumentu jako alias pro --verbosity Diagnostic. Použít -q pro --verbosity Quiet.

Konvence rozhraní příkazového řádku .NET a POSIX

Rozhraní .NET CLI konzistentně nedodržuje všechny konvence POSIX.

Dvojitá pomlčka

Několik příkazů v rozhraní .NET CLI má speciální implementaci tokenu s dvojitou pomlčkou. V případě dotnet run, dotnet watch a dotnet tool run se tokeny, které následují --, předají do aplikace, která se spouští příkazem. Například:

dotnet run --project ./myapp.csproj -- --message "Hello world!"
                                    ^^

V tomto příkladu je možnost --project předána příkazu dotnet run, a možnost --message s jejím argumentem je při spuštění předána jako možnost příkazového řádku myapp.

Token -- není vždy nutný pro předávání možností do aplikace, kterou spouštíte pomocí dotnet run. Bez dvojité pomlčky příkaz dotnet run automaticky předá aplikaci, která je spuštěna, všechny možnosti, které nejsou rozpoznány jako vztahující se na dotnet run nebo na MSBuild. Následující příkazové řádky jsou tedy ekvivalentní, protože dotnet run nerozpozná argumenty a možnosti:

dotnet run -- quotes read --delay 0 --fg-color red
dotnet run quotes read --delay 0 --fg-color red

Vynechání oddělovače typu argument-opce

Rozhraní .NET CLI nepodporuje konvenci POSIX, která umožňuje vynechat oddělovač při zadávání aliasu možnosti s jedním znakem.

Více argumentů bez opakování názvu možnosti

Rozhraní příkazového řádku .NET nepřijímá více argumentů pro jednu možnost bez opakování názvu možnosti.

Boolovské možnosti

V rozhraní příkazového řádku .NET mají některé logické možnosti za následek stejné chování při předání false jako při předání true. Toto chování má za následek, že kód rozhraní příkazového řádku .NET, který implementuje tuto možnost, kontroluje pouze přítomnost nebo nepřítomnost této možnosti a ignoruje hodnotu. Příkladem je --no-restore pro dotnet build příkaz. Pokud předáte --no-restore false, operace obnovení bude přeskočena stejně jako při zadání --no-restore true nebo --no-restore.

Kebab case

V některých případech .NET CLI nepoužívá pro názvy příkazů, možností nebo argumentů formát kebab. K dispozici je například možnost rozhraní příkazového řádku .NET, která má název --additionalprobingpath místo --additional-probing-path.

Sdílet prostřednictvím