Sdílet prostřednictvím

Přehled syntaxe příkazového řádku pro System.CommandLine

  • Článek

Důležité

System.CommandLine je aktuálně ve verzi PREVIEW a tato dokumentace je určená pro verzi 2.0 beta 4. Některé informace se týkají předběžné verze produktu, který může být podstatně změněn před vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Tento článek vysvětluje syntaxi příkazového řádku, která System.CommandLine rozpoznává. Tyto informace budou užitečné pro uživatele i vývojáře aplikací příkazového řádku .NET, včetně rozhraní příkazového řádku .NET CLI.

Tokeny

System.CommandLine parsuje vstup příkazového řádku do tokenů, což jsou řetězce oddělené mezerami. Představte si například následující příkazový řádek:

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

Tento vstup analyzuje dotnet aplikace do tokenů tool, , dotnet-suggestinstall, , --global, --verbosity, a quiet.

Tokeny se interpretují jako příkazy, možnosti nebo argumenty. Aplikace příkazového řádku, která se vyvolá, určuje, jak se tokeny interpretují po prvním. Následující tabulka ukazuje, jak System.CommandLine interpretuje předchozí příklad:

Token Parsováno jako
tool Podpříkaz
install Podpříkaz
dotnet-suggest Argument pro příkaz install
--global Možnost pro příkaz install
--verbosity Možnost pro příkaz install
quiet Argument pro --verbosity možnost

Token může obsahovat mezery, pokud je uzavřen v uvozovkách ("). Tady je příklad:

dotnet tool search "ef migrations add"

Příkazy

Příkaz ve vstupu příkazového řádku je token, který určuje akci nebo definuje skupinu souvisejících akcí. Příklad:

  • In dotnet runje run příkaz, který určuje akci.
  • In dotnet tool installje install příkaz, který určuje akci a tool je příkaz, který určuje skupinu souvisejících příkazů. Existují další příkazy související s nástroji, například tool uninstall, tool lista tool update.

Kořenové příkazy

Kořenový příkaz je příkaz, který určuje název spustitelného souboru aplikace. Například dotnet příkaz určuje dotnet.exe spustitelný soubor.

Podpříkazy

Většina aplikací příkazového řádku podporuje dílčí příkazy, označované také jako příkazy. Například příkaz dotnet má run podpříkaz, který vyvoláte zadáním dotnet run.

Podpříkazy můžou mít vlastní podpříkazy. V dotnet tool install, install je podpříkaz .tool

Možnosti

Možnost je pojmenovaný parametr, který lze předat příkazu. Rozhraní CLI POSIX obvykle předponu názvu možnosti dvěma pomlčkami (--). Následující příklad ukazuje dvě možnosti:

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

Jak je znázorněno v tomto příkladu, může být hodnota možnosti explicitní (quiet pro --verbosity) nebo implicitní (nic není následující --global). Možnosti, které nemají zadanou žádnou hodnotu, jsou obvykle logické parametry, které jsou výchozí true , pokud je tato možnost zadána na příkazovém řádku.

U některých aplikací příkazového řádku pro Windows identifikujete možnost pomocí počátečního lomítka (/) s názvem možnosti. Příklad:

msbuild /version
        ^------^

System.CommandLine podporuje konvence předpon POSIX i Windows. Při konfiguraci možnosti zadáte název možnosti včetně předpony.

Argumenty

Argument je hodnota předaná možnosti nebo příkazu. Následující příklady ukazují argument pro verbosity možnost a argument příkazu build .

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

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

Argumenty můžou mít výchozí hodnoty, které platí, pokud není explicitně zadaný žádný argument. Mnoho možností je například implicitně logických parametrů s výchozím nastavením true , kdy je název možnosti v příkazovém řádku. Následující příklady příkazového řádku jsou ekvivalentní:

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

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

Některé možnosti mají požadované argumenty. Například v rozhraní příkazového řádku .NET vyžaduje --output argument názvu složky. Pokud argument není zadaný, příkaz selže.

Argumenty můžou mít očekávané typy a System.CommandLine zobrazí chybovou zprávu, pokud argument nelze analyzovat do očekávaného typu. Například následující chyby příkazu, protože "silent" není jedna z platných hodnot pro --verbosity:

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

Argumenty také mají očekávání o tom, kolik hodnot lze poskytnout. Příklady jsou uvedeny v části o argumentu arity.

Pořadí možností a argumentů

Možnosti můžete zadat před argumenty nebo argumenty před možnostmi na příkazovém řádku. Následující příkazy jsou ekvivalentní:

dotnet add package System.CommandLine --prerelease
dotnet add package --prerelease System.CommandLine

Možnosti lze zadat v libovolném pořadí. Následující příkazy jsou ekvivalentní:

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

Pokud existuje více argumentů, záleží na pořadí. Následující příkazy nemusí nutně odpovídat:

myapp argument1 argument2
myapp argument2 argument1

Tyto příkazy předávají seznam se stejnými hodnotami kódu obslužné rutiny příkazů, ale liší se v pořadí hodnot, což může vést k různým výsledkům.

Aliasy

V POSIX i Windows je běžné, že některé příkazy a možnosti mají aliasy. Obvykle se jedná o krátké formuláře, které se snadněji zadají. Aliasy se dají použít i pro jiné účely, například k simulaci rozlišování velkých a malých písmen a k podpoře alternativních pravopisů slova.

Krátké formuláře POSIX obvykle obsahují jeden počáteční spojovník následovaný jedním znakem. Následující příkazy jsou ekvivalentní:

dotnet build --verbosity quiet
dotnet build -v quiet

Standard GNU doporučuje automatické aliasy. To znamená, že můžete zadat libovolnou část dlouhého příkazu nebo názvu možnosti a bude přijata. Toto chování by odpovídalo následujícím příkazům:

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 nepodporuje automatické aliasy.

Rozlišování malých a velkých písmen

Názvy příkazů a možností a aliasy ve výchozím nastavení rozlišují malá a velká písmena podle konvence POSIX a System.CommandLine řídí se touto konvencí. Pokud chcete, aby rozhraní příkazového řádku nerozlišuje malá a velká písmena, definujte aliasy pro různé alternativy velikosti písmen. Může mít například --additional-probing-path aliasy --Additional-Probing-Path a --ADDITIONAL-PROBING-PATH.

V některých nástrojích příkazového řádku určuje rozdíl v sadě casing rozdíl ve funkci. Například git clean -X se chová jinak než git clean -x. Rozhraní příkazového řádku .NET je malými písmeny.

Citlivost malých a velkých písmen se nevztahuje na hodnoty argumentů pro možnosti založené na výčtech. Názvy výčtů se shodují bez ohledu na velikost písmen.

Token --

Konvence POSIX interpretuje token typu double-dash (--) jako řídicí mechanismus. Vše, co následuje za dvojitým pomlčkovým tokenem, se interpretuje jako argumenty příkazu. Tuto funkci lze použít k odeslání argumentů, které vypadají jako možnosti, protože brání jejich interpretaci jako možnosti.

Předpokládejme, že má moje aplikace message argument a chcete, aby hodnota message byla --interactive. Následující příkazový řádek může poskytnout neočekávané výsledky.

myapp --interactive

Pokud myapp nemá --interactive možnost, --interactive token se interpretuje jako argument. Pokud ale aplikace má --interactive možnost, bude tento vstup interpretován jako odkaz na tuto možnost.

Následující příkazový řádek používá token dvojitého pomlčky k nastavení hodnoty argumentu message na ---interactive:

myapp -- --interactive
      ^^

System.CommandLine podporuje tuto funkci s dvojitou pomlčkou.

Oddělovače argumentů option

System.CommandLine umožňuje použít mezeru , =nebo :, jako oddělovač mezi názvem parametru a jeho argumentem. Například následující příkazy jsou ekvivalentní:

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

Konvence POSIX umožňuje vynechat oddělovač při zadávání aliasu možnosti s jedním znakem. Například následující příkazy jsou ekvivalentní:

myapp -vquiet
myapp -v quiet

System.CommandLine podporuje tuto syntaxi ve výchozím nastavení.

Argument arity

Arity parametru nebo argumentu příkazu je počet hodnot, které lze předat, pokud je tato možnost nebo příkaz zadán.

Arity se vyjadřují s minimální hodnotou a maximální hodnotou, jak znázorňuje následující tabulka:

Min. Max. Příklad platnosti Příklad
0 0 Platný: --Soubor
Neplatný: --file a.json
Neplatný: --file a.json --file b.json
0 1 Platný: --Vlajky
Platný: --flag true
Platný: --flag false
Neplatný: --flag false --flag false
1 1 Platný: --file a.json
Neplatný: --Soubor
Neplatný: --file a.json --file b.json
0 N Platný: --Soubor
Platný: --file a.json
Platný: --file a.json --file b.json
0 N Platný: --file a.json
Platný: --soubor a.json b.json
Neplatný: --Soubor

System.CommandLineArgumentArity má strukturu pro definování arity s následujícími hodnotami:

  • Zero - Nejsou povoleny žádné hodnoty.
  • ZeroOrOne – Může mít jednu hodnotu, nemusí mít žádné hodnoty.
  • ExactlyOne - Musí mít jednu hodnotu.
  • ZeroOrMore – Může mít jednu hodnotu, více hodnot nebo žádné hodnoty.
  • OneOrMore – Může mít více hodnot, musí mít aspoň jednu hodnotu.

Arity lze často odvodit z typu. Například možnost int márity ExactlyOneList<int> a možnost má arity OneOrMore.

Přepsání možností

Pokud je maximální počet arity 1, je stále možné nakonfigurovat tak, System.CommandLine aby přijímal více instancí možnosti. V takovém případě poslední instance opakované možnosti přepíše všechny starší instance. V následujícím příkladu by se hodnota 2 předala myapp příkazu.

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

Více argumentů

Pokud je maximum arity více než jedno, můžete nakonfigurovat tak, System.CommandLine aby přijímalo více argumentů pro jednu možnost bez opakování názvu možnosti.

V následujícím příkladu by seznam předaný myapp příkazu obsahoval "a", "b", "c" a "d":

myapp --list a b c --list d

Sdružování možností

POSIX doporučuje podporovat sdružování jednoznakových možností, označovaných také jako stacking. Sbalené možnosti jsou aliasy možností s jedním znakem zadané po jedné předponě spojovníku. Argument může zadat pouze poslední možnost. Například následující příkazové řádky jsou ekvivalentní:

git clean -f -d -x
git clean -fdx

Pokud je argument poskytnut po sadě možností, použije se na poslední možnost v sadě. Následující příkazové řádky jsou ekvivalentní:

myapp -a -b -c arg
myapp -abc arg

V obou variantách v tomto příkladu by argument arg platil pouze pro možnost -c.

Logické možnosti (příznaky)

Pokud true nebo false je předán pro možnost s argumentem bool , parsuje se podle očekávání. Možnost, jejíž typ argumentu obvykle bool nevyžaduje zadání argumentu. Logické možnosti, někdy označované jako "příznaky", obvykle mají arityZeroOrOne. Přítomnost názvu možnosti na příkazovém řádku bez argumentu, který následuje za ním, má za následek výchozí hodnotu true. Absence názvu možnosti ve vstupu příkazového řádku vede k hodnotě false. Pokud příkaz myapp vypíše hodnotu logické možnosti s názvem --interactive, následující vstup vytvoří následující výstup:

myapp
myapp --interactive
myapp --interactive false
myapp --interactive true

False
True
False
True

Možnost --help

Aplikace příkazového řádku obvykle poskytují možnost zobrazit stručný popis dostupných příkazů, možností a argumentů. System.CommandLine automaticky vygeneruje výstup nápovědy. Příklad:

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.

Uživatelé aplikací můžou být zvyklí na různé způsoby, jak požádat o pomoc na různých platformách, takže aplikace založené na System.CommandLine mnoha způsobech žádosti o pomoc reagují. Všechny následující příkazy jsou ekvivalentní:

dotnet --help
dotnet -h
dotnet /h
dotnet -?
dotnet /?

Výstup nápovědy nemusí nutně zobrazovat všechny dostupné příkazy, argumenty a možnosti. Některé z nich můžou být skryté, což znamená, že se nezobrazují ve výstupu nápovědy, ale dají se zadat na příkazovém řádku.

Možnost --version

Aplikace vytvořené System.CommandLine automaticky poskytují číslo verze v reakci na --version možnost použitou s kořenovým příkazem. Příklad:

dotnet --version

6.0.100

Soubory odpovědí

Soubor odpovědi je soubor, který obsahuje sadu tokenů pro aplikaci příkazového řádku. Soubory odpovědí jsou funkcí System.CommandLine , která je užitečná ve dvou scénářích:

  • Pokud chcete vyvolat aplikaci příkazového řádku zadáním vstupu, který je delší než limit znaků terminálu.
  • Pokud chcete vyvolat stejný příkaz opakovaně, aniž byste museli znovu zadávat celý řádek.

Pokud chcete použít soubor odpovědi, zadejte název souboru s předponou znaménko @ , ať jste kdekoli na řádku, kam chcete vložit příkazy, možnosti a argumenty. Přípona souboru .rsp je běžná konvence, ale můžete použít jakoukoli příponu souboru.

Následující řádky jsou ekvivalentní:

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

Obsah vzorku1.rsp:

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

Obsah vzorku2.rsp:

--no-restore

Tady jsou syntaktická pravidla, která určují, jak se text v souboru odpovědi interpretuje:

  • Tokeny jsou oddělené mezerami. Řádek, který obsahuje Dobré ráno! je považován za dva tokeny, Dobré a ráno!.
  • Více tokenů uzavřených v uvozovkách se interpretuje jako jeden token. Řádek, který obsahuje "Dobré ráno!" je považován za jeden token, Dobrý den!.
  • Jakýkoli text mezi symbolem a koncem # řádku se považuje za komentář a ignoruje se.
  • Tokeny s předponou @ můžou odkazovat na další soubory odpovědí.
  • Soubor odpovědi může mít více řádků textu. Řádky jsou zřetězeny a interpretovány jako posloupnost tokenů.

Direktivy

System.CommandLinezavádí syntaktický prvek označovaný jako direktiva. Tato direktiva [parse] je příkladem. Když za název aplikace zahrnete [parse] , System.CommandLine zobrazí se místo vyvolání aplikace příkazového řádku diagram výsledku analýzy:

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

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

Účelem direktiv je poskytovat průřezové funkce, které se dají použít napříč aplikacemi příkazového řádku. Vzhledem k tomu, že direktivy se syntakticky liší od vlastní syntaxe aplikace, můžou poskytovat funkce, které se vztahují napříč aplikacemi.

Direktiva musí odpovídat následujícím pravidlům syntaxe:

  • Je to token na příkazovém řádku, který přichází za názvem aplikace, ale před libovolnými dílčími příkazy nebo možnostmi.
  • Je uzavřený v hranatých závorkách.
  • Neobsahuje mezery.

Nerozpoznaná direktiva se ignoruje, aniž by to způsobilo chybu analýzy.

Direktiva může obsahovat argument oddělený od názvu direktivy dvojtečka.

Následující direktivy jsou integrované:

Direktiva [parse]

Uživatelé i vývojáři můžou zjistit, jak bude aplikace interpretovat daný vstup. Jednou z výchozích funkcí System.CommandLine aplikace je [parse] direktiva, která umožňuje zobrazit náhled výsledku analýzy vstupu příkazu. Příklad:

myapp [parse] --delay not-an-int --interactive --file filename.txt extra

![ myapp [ --delay !<not-an-int> ] [ --interactive <True> ] [ --file <filename.txt> ] *[ --fgcolor <White> ] ]   ???--> extra

V předchozím příkladu:

  • Příkaz (myapp), jeho podřízené možnosti a argumenty těchto možností jsou seskupené pomocí hranatých závorek.
  • Výsledek [ --delay !<not-an-int> ]! možnosti označuje chybu analýzy. Hodnotu not-an-int pro možnost int nelze analyzovat s očekávaným typem. Chyba je také označena ! před příkazem, který obsahuje chybovou možnost: ![ myapp....
  • Pro výsledek *[ --fgcolor <White> ]možnosti nebyla na příkazovém řádku zadána možnost, takže se použilo nakonfigurované výchozí nastavení. White je platná hodnota pro tuto možnost. Hvězdička označuje, že hodnota je výchozí.
  • ???--> odkazuje na vstup, který nebyl spárován s žádnými příkazy nebo možnostmi aplikace.

Direktiva [suggest]

Direktiva [suggest] umožňuje vyhledávat příkazy, když neznáte přesný příkaz.

dotnet [suggest] buil

build
build-server
msbuild

Pokyny pro návrh

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.

Jakmile vytvoříte 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 ho můžeme provést bez zavedení zásadních změn. Příkladem této práce je nový návrh pro dotnet new .NET 7.

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í příkazového řádku .NET CLI je implicitní oblast projektem a v rozhraní příkazového řádku Dockeru se jedná o 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 povolit uživateli volitelně zahrnout nebo vynechat jako in 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).

Krátké aliasy formulářů

Obecně doporučujeme minimalizovat počet krátkých aliasů možností, 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 se může používat ve skriptech, proto při zobrazení výzvy uživatelům, kteří tento přepínač nezadávali, buďte opatrní.

  • -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 --verbosity Možnost 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 při sestavování Debug konfigurace méně optimalizace kódu. 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á provést, takže pokud má vaše aplikace rozhraní příkazového řádku odlišné chování na základě toho, který TFM je zvolen, měli byste tento příznak podporovat.

  • -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 poskytnuty na příkazovém řádku a předány do podkladového volání NÁSTROJE MSBuild. Pokud vaše aplikace nepoužívá NÁSTROJ MSBuild, ale potřebuje sadu párů klíč-hodnota, zvažte použití stejného názvu možnosti, abyste mohli využít 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 části architektury identifikátoru RID, přičemž část, která není určena, bude určena z aktuální platformy. Další informace najdete v tématu dotnet publish.

Krátké názvy

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

Malá písmena

Definujte názvy pouze malými písmeny, kromě toho, že můžete vytvářet velké aliasy, aby se příkazy nebo možnosti nerozlišily malá a velká písmena.

Názvy velkých písmen Kebabu

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ě:

  • Quiet
  • 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žít se nejlepší přizpůsobení.

Očekává se Quiet , že se v konzole nezobrazí žádný výstup. Pokud ale aplikace nabízí interaktivní režim, měla by aplikace provést jednu z následujících alternativ:

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

Jinak 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 proveďte -v bez argumentu alias pro --verbosity Diagnostic. Použít -q pro --verbosity Quiet.

Konvence .NET CLI 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 runtokenů a dotnet watchdotnet tool runtokenů, které následují--, se předají do aplikace, která se spouští příkazem. Příklad:

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

V tomto příkladu se tato možnost předá příkazu a --message možnost s jejím argumentem se při spuštění předá jako možnost příkazového řádku aplikaci.--projectdotnet run

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 dotnet run příkaz automaticky předá aplikaci, která spouští všechny možnosti, které nejsou rozpoznány jako použití na dotnet run sebe 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 argumentů option-to-argument

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.

Logické 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-restoredotnet build příkaz. Předání no-restore false a operace obnovení se přeskočí stejně jako při zadání no-restore true nebo no-restore.

Kebab case

V některýchpřípadechch K dispozici je například možnost rozhraní příkazového řádku .NET, která má název --additionalprobingpath místo --additional-probing-path.

Viz také