Přehled syntaxe: Příkazy, možnosti a argumenty

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

Tokény

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, install, dotnet-suggest, --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 tokenu. Následující tabulka ukazuje, jak System.CommandLine interpretuje předchozí příklad:

Žeton	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"

Hierarchie symbolů (příkazy, možnosti, argumenty) se považuje za důvěryhodný vstup; hodnoty tokenu nejsou.

Příkazy

Příkaz ve vstupu příkazového řádku je token, který určuje akci nebo definuje skupinu souvisejících akcí. Napří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říkaz

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.

Command je třída pro obecné účely pro jakýkoli příkaz nebo podpříkaz, zatímco RootCommand je specializovaná verze určená pro kořenový vstupní bod aplikace. RootCommand dědí všechny funkce, Command ale přidává chování a výchozí hodnoty specifické pro kořen, jako je například možnost nápověda, možnost verze a direktiva Navrhnout.

Podpříkazy

Většina aplikací příkazového řádku podporuje dílčí příkazy, označované také jako slovesa. 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 je install podpříkazem tool.

Můžete přidat dílčí příkazy, jak je znázorněno v následujícím příkladu:

RootCommand rootCommand = new();

Command sub1Command = new("sub1", "First-level subcommand");
rootCommand.Subcommands.Add(sub1Command);

Command sub1aCommand = new("sub1a", "Second level subcommand");
sub1Command.Subcommands.Add(sub1aCommand);

Nejvnitřnější podpříkaz v tomto příkladu lze vyvolat takto:

myapp sub1 sub1a

Možnosti

Možnost je pojmenovaný parametr, který lze předat příkazu. POSIX CLI obvykle označují název 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 následujícího --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. Napří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:

Option<int> delayOption = new("--delay", "-d")
{
    Description = "An option whose argument is parsed as an int.",
    DefaultValueFactory = parseResult => 42,
};
Option<string> messageOption = new("--message", "-m")
{
    Description = "An option whose argument is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Options.Add(delayOption);
rootCommand.Options.Add(messageOption);

Chcete-li přidat možnost k příkazu a rekurzivně do všech jeho dílčích příkazů, použijte System.CommandLine.Symbol.Recursive vlastnost.

Požadované možnosti

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. Pokud chcete nastavit požadovanou možnost, nastavte její Required vlastnost na true, jak je znázorněno v následujícím příkladu:

Option<FileInfo> fileOption = new("--output")
{
    Required = true
};

Pokud má požadovaná možnost výchozí hodnotu (zadanou prostřednictvím DefaultValueFactory vlastnosti), nemusí být tato možnost zadána na příkazovém řádku. V takovém případě výchozí hodnota poskytuje požadovanou hodnotu možnosti.

Argumenty

Argument je nepojmenovaný parametr, který lze předat příkazu. Následující příklad ukazuje argument pro build příkaz.

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

Při konfiguraci argumentu zadáte název argumentu (nepoužívá se k analýze, ale dá se použít k získání analyzovaných hodnot podle názvu nebo zobrazení nápovědy) a typu:

Argument<int> delayArgument = new("delay")
{
    Description = "An argument that is parsed as an int.",
    DefaultValueFactory = parseResult => 42
};
Argument<string> messageArgument = new("message")
{
    Description = "An argument that is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Arguments.Add(delayArgument);
rootCommand.Arguments.Add(messageArgument);

Výchozí hodnoty

Argumenty i možnosti můžou mít výchozí hodnoty, které platí, pokud není explicitně zadaný žádný argument. Například mnoho možností jsou implicitně Booleovské parametry s výchozí hodnotou true, když je název možnosti uveden 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
                                  ^-----------^

Argument, který je definován bez výchozí hodnoty, je považován za povinný argument.

Parsování chyb

Možnosti a argumenty mají očekávané typy, a pokud se hodnota nepodaří zpracovat, dojde k chybě. Například následující chyby příkazu, protože "silent" není jedna z platných hodnot pro --verbosity:

dotnet build --verbosity silent

Option<string> verbosityOption = new("--verbosity", "-v")
{
    Description = "Set the verbosity level.",
};
verbosityOption.AcceptOnlyFromAmong("quiet", "minimal", "normal", "detailed", "diagnostic");
RootCommand rootCommand = new() { verbosityOption };

ParseResult parseResult = rootCommand.Parse(args);
foreach (ParseError parseError in parseResult.Errors)
{
    Console.WriteLine(parseError.Message);
}

Argument 'silent' not recognized. Must be one of:
        'quiet'
        'minimal'
        'normal'
        'detailed'
        'diagnostic'

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ů

Na příkazovém řádku můžete zadat možnosti před argumenty nebo argumenty před možnostmi. 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 nejsou ekvivalentní; liší se v pořadí hodnot, které by mohly vést k různým výsledkům:

myapp argument1 argument2
myapp argument2 argument1

Přezdívky

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. Každý alias musí být explicitně zadán. Příkazy i možnosti zpřístupňují Aliases vlastnost. Option má konstruktor, který přijímá aliasy jako parametry, takže můžete definovat možnost s více aliasy na jednom řádku:

Option<bool> helpOption = new("--help", ["-h", "/h", "-?", "/?"]);
Command command = new("serialize") { helpOption };
command.Aliases.Add("serialise");

Doporučujeme minimalizovat počet aliasů, které definujete pro možnosti, a zejména se vyhnout definování určitých aliasů. Další informace naleznete v tématu Zkratky aliasů.

Citlivost na velikost 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 (CLI) nerozlišovalo malá a velká písmena, definujte aliasy pro různé verze zápisu 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 specifikuje rozdíl ve velikosti písmen různé funkce. Například git clean -X se chová jinak než git clean -x. Rozhraní příkazového řádku .NET je psáno malými písmeny.

Velikost 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 únikový 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 aplikacemessage 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 volitelných argumentů

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í.

Arita argumentu

Arita možnosti 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řuje minimální a maximální hodnotou, jak znázorňuje následující tabulka:

Minuta	Max.	Příklad platnosti	Příklad
0	0	Platný:	--soubor
		Neplatný:	--soubor a.json
		Neplatný:	--file a.json --file b.json
0	1	Platný:	--vlajka
		Platný:	--flag true
		Platný:	--příznak nepravda
		Neplatný:	--flag nepravdivé --flag nepravdivé
1	1	Platný:	--soubor a.json
		Neplatný:	--soubor
		Neplatný:	--file a.json --file b.json
0	n	Platný:	--soubor
		Platný:	--soubor a.json
		Platný:	--file a.json --file b.json
1	n	Platný:	--soubor a.json
		Platný:	--file a.json b.json
		Neplatný:	--soubor

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

• Zero - Nejsou povoleny žádné hodnoty.
• ZeroOrOne - Může mít jednu hodnotu nebo žádnou hodnotu.
• 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.

Pomocí vlastnosti můžete explicitně nastavit arity Arity , ale ve většině případů to není nutné. System.CommandLine automaticky určuje arity argumentu na základě typu argumentu:

Typ argumentu	Výchozí arity
Boolean	ArgumentArity.ZeroOrOne
Typy kolekcí	ArgumentArity.ZeroOrMore
Všechno ostatní	ArgumentArity.ExactlyOne

Překrytí nastavení

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 hodnota 2 byla předána příkazu myapp.

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

Více argumentů

Ve výchozím nastavení můžete při volání příkazu opakovaně použít název možnosti a zadat více argumentů pro možnost, která má maximální počet argumentů větší než jedna.

myapp --items one --items two --items three

Chcete-li povolit více argumentů bez opakování názvu volby, nastavte AllowMultipleArgumentsPerToken na true hodnotu. Toto nastavení umožňuje zadat následující příkazový řádek.

myapp --items one two three

Stejné nastavení má jiný účinek, pokud je maximální argument arity 1. Umožňuje opakovat možnost, ale přebírá pouze poslední hodnotu na řádku. V následujícím příkladu by se hodnota three předala aplikaci.

myapp --item one --item two --item three

Sdružování možností

POSIX doporučuje podporovat sdružování jednoznakových možností, označovaných také jako stacking. Sdružené možnosti jsou aliasy pro jednoznakové možnosti specifikované společně za jedinou pomlčkou. Pouze poslední možnost může zadat argument. 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 je obvykle bool, nevyžaduje zadání argumentu. Booleovské volby, někdy označované jako «flagi», 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 verze

Aplikace vytvořené na System.CommandLine automaticky poskytují číslo verze na základě volby --version použité s kořenovým příkazem. Napří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.

Chcete-li použít soubor odpovědi, zadejte název souboru s předponou @ kdekoli v řá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!", se považuje za jeden token, Dobré ráno!.
• 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.CommandLine zavádí syntaktický prvek označovaný jako direktiva reprezentovaná typem Directive . Například direktiva[diagram] je integrovaná direktiva. Když za název aplikace zahrnete [diagram] , System.CommandLine zobrazí se místo vyvolání aplikace příkazového řádku diagram výsledku analýzy:

dotnet [diagram] 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é:

• [diagram]
• [suggest]

Direktiva [diagram]

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 [diagram] direktiva, která umožňuje zobrazit náhled výsledku analýzy vstupu příkazu. Například:

myapp [diagram] --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.
• Pro možnost výsledku [ --delay !<not-an-int> ]! označuje chybu analýzy. Hodnotu not-an-int nelze pro možnost int analyzovat jako očekávaný typ. 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.

Navrhnout direktivu

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

dotnet [suggest] buil

build
build-server
msbuild

Viz také

• Pokyny k návrhu
• Pokyny k návrhu opensourcového rozhraní příkazového řádku
• Standardy GNU
• System.CommandLine přehled
• Kurz: Začínáme s System.CommandLine