Szintaxis áttekintése: Parancsok, beállítások és argumentumok

Ez a cikk a felismert System.CommandLine parancssori szintaxist ismerteti. Az információk a .NET parancssori alkalmazások felhasználói és fejlesztői számára is hasznosak, beleértve a .NET CLI-t is.

Tokenek

System.CommandLine a parancssori bemenetet tokenekre bontja, amelyek szóközökkel elválasztott sztringek. Vegyük például a következő parancssort:

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

Ezt a bemenetet az dotnet alkalmazás tokenekre bontja: tool, install, dotnet-suggest, --global, --verbosity, és quiet.

A tokenek parancsokként, opciókként vagy argumentumokként értelmezhetők. A meghívott parancssori alkalmazás határozza meg, hogyan értelmezi az első után következő paramétereket. Az alábbi táblázat bemutatja, hogyan System.CommandLine értelmezi az előző példát:

Jelző	Elemzésként értelmezi
tool	Alparancs
install	Alparancs
dotnet-suggest	A telepítési parancs argumentuma
--global	A telepítési parancs lehetősége
--verbosity	A telepítési parancs lehetősége
quiet	Az opció melletti érv --verbosity

A tokenek szóközöket tartalmazhatnak, ha idézőjelek (") közé vannak zárva. Íme egy példa:

dotnet tool search "ef migrations add"

A szimbólumhierarchia (parancsok, beállítások, argumentumok) megbízható bemenetnek minősül; a tokenek értékei nem.

Parancsok

A parancssori bevitelben a parancs egy olyan kifejezés, amely egy feladatot specifikál, vagy egy kapcsolódó feladatcsoportot határoz meg. Például:

• A dotnet runrun egy olyan parancs, amely egy műveletet határoz meg.
• Az In dotnet tool installegy install olyan parancs, amely egy műveletet határoz meg, és tool egy parancs, amely a kapcsolódó parancsok egy csoportját adja meg. Vannak más eszközhöz kapcsolódó parancsok is, például tool uninstall: , tool listés tool update.

Gyökérparancs

A gyökérparancs adja meg az alkalmazás végrehajtható fájljának nevét. Például a dotnet parancs a dotnet.exe végrehajthatót adja meg.

Command a parancsok vagy alparancsok általános célú osztálya, míg RootCommand az alkalmazás gyökér belépési pontjának speciális verziója. RootCommand Örökli az összes funkciót, de hozzáadja a Command gyökérspecifikus viselkedést és az alapértelmezett beállításokat, például a Súgó lehetőséget, a Verzió beállítást és a Javaslat direktívát.

Alparancsok

A legtöbb parancssori alkalmazás támogatja az alparancsokat, más néven igéket. Például a dotnet parancsnak van egy run alparancsa, amelyet úgy hív meg, hogy beírja a dotnet run.

Az alparancsok saját alparancsokkal rendelkezhetnek. dotnet tool install, a install az tool alparancsa.

Az alábbi példában látható módon adhat hozzá alparancsokat:

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);

A példában szereplő legbelső alparancs a következőképpen hívható meg:

myapp sub1 sub1a

Beállítások

A beállítás egy elnevezett paraméter, amely átadható egy parancsnak. POSIX CLI-k általában két kötőjellel (--) látják el az opció nevét. Az alábbi példa két lehetőséget mutat be:

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

Ahogy ez a példa is mutatja, a beállítás értéke lehet explicit (quiet for --verbosity) vagy implicit (semmi sem követi --global). A megadott értékkel nem rendelkező beállítások általában logikai paraméterek, amelyek alapértelmezés szerint akkor jelennek meg true , ha a beállítás meg van adva a parancssorban.

Egyes Windows-parancssori alkalmazások esetében egy választójel (/) használatával azonosíthat egy lehetőséget a beállítás nevével. Például:

msbuild /version
        ^------^

System.CommandLine A POSIX és a Windows előtag konvenciók egyaránt támogatottak.

Egy beállítás konfigurálásakor meg kell adnia a beállítás nevét, beleértve az előtagot is:

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);

Ha egy parancshoz szeretne hozzáadni egy lehetőséget, és rekurzív módon szeretné hozzáadni az összes alparancsot, használja a tulajdonságot System.CommandLine.Symbol.Recursive .

Kötelező beállítások

Egyes beállításokhoz kötelező argumentumok tartoznak. A .NET parancssori felületén --output például szükség van egy mappanév argumentumára. Ha az argumentum nincs megadva, a parancs meghiúsul. Ha kötelezővé szeretné tenni egy beállítást, állítsa be annak Required tulajdonságát true-re, ahogy az a következő példában látható:

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

Ha egy kötelező beállítás alapértelmezett (a DefaultValueFactory tulajdonságon keresztül megadott) értékkel rendelkezik, a beállítást nem kell megadni a parancssorban. Ebben az esetben az alapértelmezett érték adja meg a szükséges beállításértéket.

Érvek

Az argumentum egy meg nem nevezett paraméter, amely átadható egy parancsnak. Az alábbi példa a parancs argumentumát build mutatja be.

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

Argumentum konfigurálásakor meg kell adnia az argumentum nevét (az elemzéshez nem használható, de használható az elemzési értékek név vagy súgó megjelenítéséhez) és írja be a következőt:

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);

Alapértelmezett értékek

Az argumentumok és a beállítások is lehetnek alapértelmezett értékek, amelyek akkor érvényesek, ha nincs explicit argumentum megadva. Például számos beállítás implicit módon logikai paraméterként működik, amelyek alapértelmezett true értéket vesznek fel, amikor a beállítás neve a parancssorban szerepel. A következő parancssori példák egyenértékűek:

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

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

Az alapértelmezett érték nélkül definiált argumentumok kötelező argumentumként lesznek kezelve.

Elemzési hibák

Az opciók és argumentumok elvárt típusokkal rendelkeznek, és hiba keletkezik, ha az érték nem értelmezhető. A következő parancshibák például azért lépnek fel, mert a "csendes" nem az érvényes értékek egyike a következőhöz --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'

Az argumentumok azzal kapcsolatban is elvárásokat támasztanak, hogy hány érték adható meg. Példákat az argumentum-aritásról szóló szakaszban olvashat.

Beállítások és argumentumok sorrendje

A parancssoron megadhat opciókat az argumentumok előtt vagy az argumentumokat az opciók előtt. A következő parancsok egyenértékűek:

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

A beállítások tetszőleges sorrendben megadhatók. A következő parancsok egyenértékűek:

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

Ha több argumentum is van, a sorrend számít. A következő parancsok nem egyenértékűek; az értékek sorrendjében különböznek, ami eltérő eredményekhez vezethet:

myapp argument1 argument2
myapp argument2 argument1

Aliasok

A POSIX-ban és a Windowsban is gyakori, hogy egyes parancsok és beállítások aliasokkal rendelkeznek. Ezek általában rövid űrlapok, amelyeket könnyebb begépelni. Az aliasok más célokra is használhatók, például a kis- és nagybetűk érzéketlenségének szimulálására és egy szó alternatív helyesírásának támogatására.

A POSIX rövid űrlapok általában egyetlen kezdő kötőjelet, majd egy karaktert követnek. A következő parancsok egyenértékűek:

dotnet build --verbosity quiet
dotnet build -v quiet

A GNU szabvány automatikus aliasokat javasol. Ez azt jelent, hogy a hosszú formátumú parancs vagy beállításnév bármely részét beírhatja, és a rendszer elfogadja. Ez a viselkedés a következő parancssorokat egyenértékűvé teszi:

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 nem támogatja az automatikus aliasokat. Minden aliast explicit módon kell megadni. A parancsok és a beállítások egyaránt elérhetővé teszik a tulajdonságot Aliases . Option van egy konstruktor, amely paraméterekként fogadja el az aliasokat, így egyetlen sorban több aliast is megadhat:

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

Javasoljuk, hogy minimalizálja a definiált beállítási aliasok számát, és kerülje bizonyos aliasok definiálását. További információ: Rövid formátumú aliasok.

Kis- és nagybetűk érzékenysége

A parancs- és beállításnevek és aliasok alapértelmezés szerint megkülönböztetik a kis- és nagybetűket a POSIX-konvenciónak megfelelően, és System.CommandLine ezt az egyezményt követi. Ha azt szeretné, hogy a parancssori felület (CLI) kis- és nagybetű érzéketlen legyen, definiáljon aliasokat a különböző betűméret alternatívákhoz. Lehetnek például --additional-probing-path aliasok --Additional-Probing-Path és --ADDITIONAL-PROBING-PATH.

Egyes parancssori eszközökben a kis- és nagybetűk különbsége különböző funkciót jelöl. Például a git clean -X másképp viselkedik, mint a git clean -x. A .NET parancssori felület kisbetűs.

A kis- és nagybetűk érzékenysége nem vonatkozik az argumentumértékekre az enumeráláson alapuló beállítások esetében. Az enumerálási nevek a burkolattól függetlenül megegyeznek.

A -- token

A POSIX-konvenciók a kettős kötőjeles (--) tokent kitörési mechanizmusként értelmezik. A kettős kötőjelet követő minden elem a parancs argumentumaként lesz értelmezve. Ezzel a funkcióval olyan argumentumokat küldhet be, amelyek a beállításokhoz hasonlóan néznek ki, mivel megakadályozza, hogy azok beállításokként legyenek értelmezve.

Tegyük fel, hogy a myapp argumentumot message vesz fel, és azt szeretné, hogy az érték message legyen --interactive. Az alábbi parancssor váratlan eredményeket adhat.

myapp --interactive

Ha a myapp nem rendelkezik --interactive opcióval, akkor a --interactive token argumentumként lesz értelmezve. Ha azonban az alkalmazás rendelkezik egy --interactive lehetőséggel, a rendszer ezt a bemenetet az adott beállításra hivatkozóként értelmezi.

Az alábbi parancssor a dupla kötőjelű kapcsolót használja az message argumentum értékének "--interactive"-ra állításához.

myapp -- --interactive
      ^^

System.CommandLine támogatja ezt a dupla kötőjel funkciót.

Option-argument határolók

System.CommandLine lehetővé teszi, hogy szóközt, "=" vagy ":" karaktert használjon a választógomb neve és argumentuma közötti elválasztóként. A következő parancsok például egyenértékűek:

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

A POSIX-konvenciók lehetővé teszik, hogy kihagyja a határolót, amikor egyetlen karakterből álló opció alias-t ad meg. A következő parancsok például egyenértékűek:

myapp -vquiet
myapp -v quiet

System.CommandLine alapértelmezés szerint támogatja ezt a szintaxist.

Argumentum-aritás

Egy beállítás vagy parancs argumentumának aritása az adott beállítás vagy parancs megadása esetén átadható értékek száma.

Az aritás minimális értékkel és maximális értékkel van kifejezve, ahogyan az alábbi táblázat szemlélteti:

Min	Max	Példa érvényessége	Példa
0	0	Érvényes:	--fájl
		Érvénytelen:	--fájl a.json
		Érvénytelen:	--file a.json --file b.json
0	1	Érvényes:	--zászló
		Érvényes:	--flag true
		Érvényes:	--zászló hamis
		Érvénytelen:	--flag false --flag false
1	1	Érvényes:	--fájl a.json
		Érvénytelen:	--fájl
		Érvénytelen:	--file a.json --file b.json
0	n	Érvényes:	--fájl
		Érvényes:	--fájl a.json
		Érvényes:	--file a.json --file b.json
1	n	Érvényes:	--fájl a.json
		Érvényes:	--fájl a.json b.json
		Érvénytelen:	--fájl

System.CommandLine rendelkezik egy ArgumentArity struktúrával az aritás meghatározására, a következő értékekkel:

• Zero - Nem engedélyezett értékek.
• ZeroOrOne - Lehet egy érték, vagy nincs érték.
• ExactlyOne - Egy értékkel kell rendelkeznie.
• ZeroOrMore - Lehet egy érték, több érték, vagy nincs érték.
• OneOrMore - Több érték is lehet; legalább egy értékkel kell rendelkeznie.

Az Arity tulajdonság használatával explicit módon beállíthatja az aritást, de a legtöbb esetben erre nincs szükség. System.CommandLine automatikusan meghatározza az argumentum-aritást az argumentumtípus alapján:

Argumentum típusa	Alapértelmezett aritás
Boolean	ArgumentArity.ZeroOrOne
Gyűjteménytípusok	ArgumentArity.ZeroOrMore
Minden más	ArgumentArity.ExactlyOne

Opció-felülírások

Ha az aritás maximuma 1, akkor is konfigurálható úgy, System.CommandLine hogy egy lehetőség több példányát is elfogadja. Ebben az esetben az ismétlődő beállítás utolsó példánya felülírja a korábbi példányokat. Az alábbi példában a 2 érték lesz átadva a myapp parancsnak.

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

Több argumentum

Ha parancsot hív meg, alapértelmezés szerint megismételhet egy beállításnevet, hogy több argumentumot adjon meg egynél nagyobb aritású beállításhoz.

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

Ha több argumentumot szeretne engedélyezni a beállításnév megismétlése nélkül, állítsa a következőre AllowMultipleArgumentsPerTokentrue: . Ezzel a beállítással a következő parancssort adhatja meg.

myapp --items one two three

Ugyanez a beállítás eltérő hatással van, ha a maximális argumentum-aritás 1. Lehetővé teszi egy lehetőség ismétlését, de csak az utolsó értéket veszi fel a sorban. Az alábbi példában az érték three az alkalmazásnak lesz átadva.

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

Opciós kötegelés

A POSIX azt javasolja, hogy támogassa az egy karakteres opciók csoportosítását, amely más néven halmozás. Az összecsomagolt opciók olyan egy karakteres opció aliasok, amelyeket egyetlen kötőjellel ellátott előtag után adnak meg. Argumentumot csak az utolsó beállítás adhat meg. A következő parancssorok például egyenértékűek:

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

Ha egy beállításcsomag után argumentumot ad meg, az a csomag utolsó lehetőségére vonatkozik. A következő parancssorok egyenértékűek:

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

A példában szereplő mindkét változatban az argumentum arg csak a beállításra -cvonatkozik.

Logikai beállítások (jelzők)

true vagy false átadása esetén egy bool argumentumot használó beállításhoz, az a várt módon kerül feldolgozásra. De egy olyan beállítás, amelynek argumentumtípusa bool általában nem követel meg argumentumot. A logikai beállítások, más néven "jelzők" általában aritást adnak ZeroOrOne. A beállításnév jelenléte a parancssorban argumentum nélkül a következő alapértelmezett értéket trueeredményezi: . A parancssori bemenetben a beállításnév hiánya a következő értéket falseeredményezi: . Ha a myapp parancs egy logikai --interactivebeállítás értékét nyomtatja ki, az alábbi bemenet a következő kimenetet hozza létre:

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

False
True
False
True

Verzióbeállítás

A beépített System.CommandLine alkalmazások automatikusan adják meg a verziószámot a --version gyökérparancshoz használt beállításra válaszul. Például:

dotnet --version

6.0.100

Válaszfájlok

A válaszfájl olyan fájl, amely egy parancssori alkalmazás jogkivonatait tartalmazza. A válaszfájlok a System.CommandLine egy jellemzője, amely két esetben hasznos:

• Parancssori alkalmazás meghívása a terminál karakterkorlátját meghaladó bemenet megadásával.
• Ha ugyanazt a parancsot többször is meg szeretné hívni a teljes sor újraformázása nélkül.

Válaszfájl használatához írja be a fájlnevet @ előtaggal bárhová a sorba, ahol parancsokat, beállításokat és argumentumokat kíván beszúrni. Az .rsp fájlkiterjesztés általános konvenció, de bármilyen fájlkiterjesztést használhat.

A következő sorok egyenértékűek:

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

A sample1.rsp tartalma:

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

A sample2.rsp tartalma:

--no-restore

Az alábbi szintaxisszabályok határozzák meg a válaszfájl szövegének értelmezését:

• Az elemek szóközökkel vannak elválasztva. A Jó reggelt! elemet tartalmazó sort két elemként kezeljük: Jó és reggelt!.
• Az idézőjelek közé foglalt több token egyetlen tokenként van értelmezve. A "Jó reggelt!" szöveget tartalmazó sort egy egységként kezeljük, Jó reggelt!.
• A szimbólumok és a sor vége közötti # szövegeket megjegyzésként kezeli a rendszer, és figyelmen kívül hagyja.
• A @ előtaggal rendelkező tokenek további válaszfájlokra is hivatkozhatnak.
• A válaszfájl több sornyi szöveget tartalmazhat. A sorok össze vannak fűzve, és tokenek sorozataként vannak értelmezve.

Irányelvek

System.CommandLinea típus által képviselt Directive nevezett szintaktikai elemet vezet be. Például, a [diagram] irányelv egy beépített irányelv. Ha az alkalmazás neve után szerepel [diagram] , System.CommandLine a parancssori alkalmazás meghívása helyett megjeleníti az elemzés eredményének diagramját:

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

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

Az irányelvek célja, hogy olyan átfogó funkciókat biztosítson, amelyek a parancssori alkalmazásokra alkalmazhatók. Mivel az irányelvek szintaktikailag különböznek az alkalmazás saját szintaxisától, az alkalmazásokra vonatkozó funkciókat biztosíthatnak.

Az irányelvnek meg kell felelnie a következő szintaxisszabályoknak:

• Ez egy kulcs a parancssorban, amely az alkalmazás neve után, de az alparancsok vagy beállítások előtt található.
• Szögletes zárójelek közé van zárva.
• Nem tartalmaz szóközöket.

A nem felismert irányelveket a rendszer elemzési hiba nélkül figyelmen kívül hagyja.

Az irányelv tartalmazhat egy argumentumot, amelyet kettőspont választ el az irányelv nevétől.

A következő irányelvek vannak beépítve:

• [diagram]
• [suggest]

Az [diagram] irányelv

A felhasználók és a fejlesztők is hasznosnak találhatják, hogy egy alkalmazás hogyan értelmezi az adott bemenetet. Egy System.CommandLine alkalmazás egyik alapértelmezett funkciója az [diagram] irányelv, amely lehetővé teszi a parancsbemenet elemzési eredményének előnézetét. Például:

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

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

Az előző példában:

• A parancs (myapp), a gyermekbeállítások és a beállítások argumentumai szögletes zárójelek szerint vannak csoportosítva.
• Az opció eredményének esetében [ --delay !<not-an-int> ] az ! elemzési hibára utal. A(z) not-an-int opció int értéke nem értelmezhető a várt típusra. A hibát a hibaüzenetet tartalmazó parancs előtt is megjelöli ! a rendszer: ![ myapp....
• A beállítás eredményéhez *[ --fgcolor <White> ]a beállítás nem lett megadva a parancssorban, ezért a konfigurált alapértelmezett beállítás lett használva. White a beállítás érvényes értéke. A csillag azt jelzi, hogy az érték az alapértelmezett érték.
• ???--> olyan bemenetre mutat, amely nem felelt meg az alkalmazás egyik parancsának vagy beállításának sem.

Javaslat irányelvre

Az [suggest] irányelv lehetővé teszi a parancsok keresését, ha nem tudja a pontos parancsot.

dotnet [suggest] buil

build
build-server
msbuild

Lásd még

• Tervezési útmutató
• Nyílt forráskódú parancssori felület tervezési útmutatója
• GNU-szabványok
• System.CommandLine áttekintés
• Oktatóanyag: Első lépések System.CommandLine