Parancssori szintaxis áttekintése a következőhöz: System.CommandLine

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

Tokenek

System.CommandLinea parancssori bemenetet tokenekké elemzi, amelyek szóközök által tagolt 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 tokenektool, , install, --verbositydotnet-suggest--globalés quiet.

A jogkivonatok parancsként, beállításként vagy argumentumként vannak értelmezve. A meghívandó parancssori alkalmazás határozza meg, hogyan értelmezi a jogkivonatokat az első után. Az alábbi táblázat bemutatja, hogyan System.CommandLine értelmezi az előző példát:

Jogkivonat	Elemzés másként
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	Argumentum a beállításhoz --verbosity

A jogkivonatok szóközöket tartalmazhatnak, ha idézőjelek (") közé vannak zárva. Példa:

dotnet tool search "ef migrations add"

Parancsok

A parancssori beviteli parancsok olyan jogkivonatok, amelyek egy műveletet határoznak meg, vagy egy kapcsolódó műveletcsoportot határoznak meg. Példa:

• Az In dotnet runegy run 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érparancsok

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

Alparancsok

A legtöbb parancssori alkalmazás támogatja az alparancsokat, más néven igéket. A parancsnak például van egy run alparancsa, dotnet amelyet a beírással dotnet runhív meg.

Az alparancsok saját alparancsokkal rendelkezhetnek. Az in dotnet tool install, install a következő alparancsa tool: .

Beállítások

A beállítás egy elnevezett paraméter, amely átadható egy parancsnak. A POSIX CLI-k általában két kötőjellel (--) előtaggal előtagot adnak a beállításnak. 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élda:

msbuild /version
        ^------^

System.CommandLine A POSIX és a Windows előtag konvenciók egyaránt támogatottak. Amikor konfigurál egy beállítást, meg kell adnia a beállítás nevét, beleértve az előtagot is.

Argumentumok

Az argumentum egy beállításnak vagy parancsnak átadott érték. Az alábbi példák a beállítás argumentumát és a verbosity parancs argumentumát build mutatják be.

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

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

Az argumentumok olyan alapértelmezett értékekkel rendelkezhetnek, amelyek akkor érvényesek, ha nincs explicit módon megadva argumentum. Számos beállítás például implicit módon logikai paraméterek, amelyek alapértelmezett true értéke az, ha a beállítás neve a parancssorban van. A következő parancssori példák egyenértékűek:

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

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

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.

Az argumentumok lehetnek várt típusúak, és System.CommandLine hibaüzenetet jelenít meg, ha egy argumentum nem elemezhető a várt típusba. 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

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

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 parancssori beállítások előtt argumentumokat vagy argumentumokat adhat meg. 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 feltétlenül egyenértékűek:

myapp argument1 argument2
myapp argument2 argument1

Ezek a parancsok átadnak egy azonos értékeket tartalmazó listát a parancskezelő kódjának, de az értékek sorrendjében különböznek, ami eltérő eredményeket eredményezhet.

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.

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 érzéketlen legyen, definiáljon aliasokat a különböző casing alternatívákhoz. Lehetnek például --additional-probing-path aliasok --Additional-Probing-Path és --ADDITIONAL-PROBING-PATH.

Egyes parancssori eszközökben a casing különbsége a függvény különbségét határozza meg. Például másképp viselkedik, git clean -X mint git clean -xa . 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 -- jogkivonat

A POSIX-konvenciók a kettős kötőjeles (--) jogkivonatot feloldó mechanizmusként értelmezik. A kétkötőjeles jogkivonatot követő összes 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 myapp nincs --interactive lehetősége, a --interactive jogkivonat 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 kétkötőjeles jogkivonatot használja az argumentum értékének message "--interactive" értékre állításához:

myapp -- --interactive
      ^^

System.CommandLine támogatja ezt a két kötőjeles 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é teszi, hogy kihagyja az elválasztójelet egy karakteres beállítási alias megadásakor. 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	0	Érvényes:	--Zászló
		Érvényes:	--flag true
		Érvényes:	--flag false
		Érvénytelen:	--flag false --flag false
0	0	É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
0	N	Érvényes:	--fájl a.json
		Érvényes:	--fájl a.json b.json
		Érvénytelen:	--Fájl

System.CommandLineArgumentArity a következő értékekkel rendelkezik az aritás meghatározására:

• Zero - Nem engedélyezett értékek.
• ZeroOrOne - Lehet, hogy egy érték van, lehet, hogy nincsenek értékei.
• 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.

A típusból gyakran lehet következtetni az aritásra. Egy beállítás például int aritású ExactlyOne, a List<int> beállításnak pedig aritása OneOrMorevan.

Beállítás-felülbírálá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 az aritási maximum egynél több, konfigurálható úgy, System.CommandLine hogy több argumentumot fogadjon el egy beállításhoz a beállításnév ismétlése nélkül.

Az alábbi példában a parancsnak átadott lista az "a myapp ", "b", "c" és "d" szöveget tartalmazza:

myapp --list a b c --list d

Opciós kötegelés

A POSIX azt javasolja, hogy támogassa az egy karakterből álló beállítások, más néven a halmozások összekapcsolását. A csomagban szereplő beállítások egy karakteres beállítási aliasok, amelyek egyetlen kötőjel előtag után vannak megadva. 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)

false Ha true egy argumentumot használó bool beállításhoz ad át vagy ad át, az a várt módon lesz elemezve. 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

A --help lehetőség

A parancssori alkalmazások általában lehetővé teszik az elérhető parancsok, beállítások és argumentumok rövid leírását. System.CommandLine automatikusan létrehoz egy súgókimenetet. Példa:

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.

Az alkalmazásfelhasználók különböző módokon kérhetnek segítséget a különböző platformokon, így a System.CommandLine beépített alkalmazások számos módon válaszolhatnak a segítségkérésre. A következő parancsok mind egyenértékűek:

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

A súgó kimenete nem feltétlenül jeleníti meg az összes elérhető parancsot, argumentumot és beállítást. Némelyik rejtett lehet, ami azt jelenti, hogy nem jelennek meg a súgó kimenetében, de megadható a parancssorban.

A --version 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élda:

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 System.CommandLine két esetben hasznosak:

• 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 parancsokat, beállításokat és argumentumokat beszúrni kívánt sorba egy @ előtaggal előtaggal rendelkező fájlnevet. 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:

• A jogkivonatok szóközök szerint vannak elválasztva. A Jó reggelt! elemet tartalmazó sort két jogkivonatként kezeljük: Jó és reggel!.
• Az idézőjelek közé foglalt több jogkivonatot egyetlen jogkivonatként értelmezi a rendszer. Egy sor, amely tartalmazza a "Jó reggelt!" egy jogkivonatként kezelik, 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.
• Az előtaggal ellátott @ jogkivonatok további válaszfájlokra is hivatkozhatnak.
• A válaszfájl több sornyi szöveget tartalmazhat. A sorok összefűzve és jogkivonatok sorozataként értelmezve lesznek.

Irányelvek

System.CommandLineirányelvnek nevezett szintaktikai elemet vezet be. Az [parse] irányelv egy példa. Ha az alkalmazás neve után szerepel [parse] , System.CommandLine a parancssori alkalmazás meghívása helyett megjeleníti az elemzés eredményének diagramját:

dotnet [parse] 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 jogkivonat 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:

• [parse]
• [suggest]

Az [parse] irányelv

A felhasználók és a fejlesztők is hasznosnak találhatják, hogy az alkalmazás hogyan értelmezi az adott bemenetet. Az alkalmazások egyik alapértelmezett funkciója System.CommandLine az [parse] irányelv, amely lehetővé teszi a parancsbemenet elemzésének eredményét. Példa:

myapp [parse] --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.
• A beállítás eredményében [ --delay !<not-an-int> ]az ! elemzési hiba jelenik meg. Egy beállítás értéke not-an-intint nem elemezhető a várt típushoz. 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.

Az [suggest] irányelv

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

Tervezési útmutató

A következő szakaszok útmutatást nyújtanak, amelyeket a parancssori felület tervezésekor ajánlott követni. Gondolja át, hogy az alkalmazás mit vár el a parancssorban, hasonlóan ahhoz, amit egy REST API-kiszolgáló elvár az URL-címben. A REST API-k konzisztens szabályai teszik őket könnyen használhatóvá az ügyfélalkalmazás-fejlesztők számára. Ugyanígy a parancssori alkalmazások felhasználóinak is jobb élményben lesz része, ha a PARANCSSOR-kialakítás a gyakori mintákat követi.

A parancssori felület létrehozása után nehéz módosítani, különösen akkor, ha a felhasználók a parancssori felületet olyan szkriptekben használták, amelyeket várhatóan továbbra is futtatni fognak. Az irányelveket a .NET CLI után fejlesztettük ki, és nem mindig követi ezeket az irányelveket. Frissítjük a .NET parancssori felületet, ahol a kompatibilitástörő módosítások bevezetése nélkül is megtehetjük. Erre a munkára példa a .NET 7 új kialakítása dotnet new .

Parancsok és alparancsok

Ha egy parancs alparancsokkal rendelkezik, a parancsnak területként vagy az alparancsok csoportosítási azonosítójaként kell működnie a művelet megadása helyett. Az alkalmazás meghívásakor meg kell adnia a csoportosítási parancsot és annak egyik alparancsát. Próbálkozzon például a futtatással dotnet tool, és hibaüzenet jelenik meg, mert a tool parancs csak az eszközhöz kapcsolódó alparancsok egy csoportját azonosítja, például install és list. Futtathat dotnet tool install, de dotnet tool önmagában nem lenne teljes.

A területek meghatározásának egyik módja a felhasználók számára az, hogy rendszerezi a súgó kimenetét.

A parancssori felületen belül gyakran van implicit terület. A .NET CLI-ben például az implicit terület a projekt, a Docker CLI-ben pedig a kép. Ennek eredményeképpen terület nélkül is használható dotnet build . Fontolja meg, hogy a parancssori felület rendelkezik-e implicit területtel. Ha igen, fontolja meg, hogy engedélyezi-e a felhasználó számára, hogy opcionálisan belefoglalja vagy kihagyja azt, ahogy az ésdocker image build.docker build Ha opcionálisan engedélyezi, hogy a felhasználó begépelje az implicit területet, automatikusan súgóval és lapkiegészítéssel is rendelkezik a parancsok csoportosításához. Adja meg az implicit csoport opcionális használatát két olyan parancs definiálásával, amelyek ugyanazt a műveletet hajtják végre.

Beállítások paraméterekként

A beállításoknak paramétereket kell megadniuk a parancsokhoz, nem pedig maguknak a műveleteknek a megadását. Ez egy ajánlott tervezési elv, bár nem mindig követi System.CommandLine (--help súgóinformációkat jelenít meg).

Rövid formátumú aliasok

Általában azt javasoljuk, hogy minimalizálja a definiált rövid formátumú beállítási aliasok számát.

Különösen kerülje az alábbi aliasok használatát a .NET CLI-ben és más .NET parancssori alkalmazásokban használttól eltérő módon:

• -i for --interactive.

  Ez a beállítás jelzi a felhasználónak, hogy lehetséges, hogy a rendszer bemeneteket kér a parancs által megválaszolandó kérdésekhez. Például egy felhasználónév kérése. Előfordulhat, hogy a parancssori felület szkriptekben is használható, ezért körültekintően kérje meg a kapcsolót nem használó felhasználókat.

• -o for --output.

  Egyes parancsok a végrehajtásuk eredményeként hoznak létre fájlokat. Ezzel a beállítással meghatározhatja, hogy hol találhatók ezek a fájlok. Azokban az esetekben, amikor egyetlen fájl jön létre, ennek a beállításnak fájlelérési útnak kell lennie. Olyan esetekben, amikor sok fájl jön létre, ennek a beállításnak könyvtár elérési útnak kell lennie.

• -v for --verbosity.

  A parancsok gyakran biztosítanak kimenetet a konzolon lévő felhasználónak; ezzel a beállítással adhatja meg a felhasználói kérések kimenetének mennyiségét. További információ: A --verbosity lehetőség a cikk későbbi részében.

Vannak olyan aliasok is, amelyek általános használata a .NET CLI-re korlátozódik. Ezeket az aliasokat más lehetőségekhez is használhatja az alkalmazásokban, de vegye figyelembe a félreértések lehetőségét.

• -c a következőhöz: --configuration

  Ez a beállítás gyakran egy nevesített buildkonfigurációra hivatkozik, például Debug vagy Release. A konfigurációhoz bármilyen nevet használhat, de a legtöbb eszköz ezek valamelyikét várja. Ezt a beállítást gyakran használják más tulajdonságok konfigurálására úgy, hogy az ésszerű legyen az adott konfigurációhoz – például kevesebb kódoptimalizálást végez a Debug konfiguráció létrehozásakor. Ezt a lehetőséget akkor érdemes megfontolni, ha a parancs különböző működési módokat tartalmaz.

• -f a következőhöz: --framework

  Ez a beállítás egyetlen cél-keretrendszer-moniker (TFM) kiválasztására szolgál, ezért ha a CLI-alkalmazás eltérő viselkedést mutat a TFM kiválasztása alapján, akkor támogatnia kell ezt a jelzőt.

• -p a következőhöz: --property

  Ha az alkalmazás végül meghívja az MSBuild alkalmazást, a felhasználónak gyakran valamilyen módon kell testre szabnia a hívást. Ez a beállítás lehetővé teszi, hogy az MSBuild-tulajdonságok meg legyenek adva a parancssorban, és továbbíthatók a mögöttes MSBuild hívásnak. Ha az alkalmazás nem használja az MSBuild szolgáltatást, de kulcs-érték párokra van szüksége, fontolja meg ugyanezt a beállításnevet a felhasználók elvárásainak kihasználásához.

• -r a következőhöz: --runtime

  Ha az alkalmazás különböző futtatókörnyezeteken futhat, vagy futtatókörnyezet-specifikus logikával rendelkezik, fontolja meg a beállítás támogatását a futtatókörnyezet azonosítójának megadásához. Ha az alkalmazás támogatja a --runtime alkalmazást, fontolja meg a támogatás és --arch a támogatás --os használatát is. Ezekkel a beállításokkal csak az operációs rendszert vagy a RID architektúrarészeit adhatja meg, így a rész nem lesz meghatározva az aktuális platformról. További információ: dotnet publish.

Rövid nevek

A parancsok, beállítások és argumentumok nevét a lehető legrövidebb és legkönnyebben írhatóvá teheti. Ha például elég egyértelmű, class ne hajtsa végre a parancsot classification.

Kisbetűs nevek

Csak kisbetűs nevek definiálása, kivéve, ha nagybetűs aliasokat is megadhat, hogy a parancsok és a beállítások ne legyenek érzéketlenek.

Kebab-kis- és nagybetűk neve

A szavak megkülönböztetéséhez használjon kebab-esetet . Például: --additional-probing-path.

Pluralizálás

Egy alkalmazáson belül konzisztensnek kell lennie a pluralizálásban. Ne keverje például a többes számokat és a többes számneveket olyan beállításokhoz, amelyek több értékkel is rendelkezhetnek (a maximális aritás nagyobb egynél):

Beállításnevek	Konzisztencia
--additional-probing-paths és --sources	✔️
--additional-probing-path és --source	✔️
--additional-probing-paths és --source	❌
--additional-probing-path és --sources	❌

Igék és főnevek

Használjon főnevek helyett parancsokat a műveletekre hivatkozó parancsokhoz (alparancsokat nem tartalmazó parancsokhoz), például: dotnet workload remove, nem dotnet workload removal. És használjon főneveket az igék helyett a lehetőségekhez, például: --configuration, nem --configure.

A --verbosity lehetőség

System.CommandLine az alkalmazások általában olyan --verbosity lehetőséget kínálnak, amely meghatározza, hogy a rendszer mennyi kimenetet küld a konzolnak. A standard öt beállítás a következő:

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

Ezek a szokásos nevek, de a meglévő alkalmazások néha az ésTrace, Debugvagy Verbose a helyett Diagnostichasználják SilentQuietőket.

Minden alkalmazás saját feltételeket határoz meg, amelyek meghatározzák, hogy mi jelenjen meg az egyes szinteken. Egy alkalmazásnak általában csak három szintre van szüksége:

• Quiet
• Normál
• Diagnosztika

Ha egy alkalmazásnak nincs szüksége öt különböző szintre, a beállításnak továbbra is ugyanazt az öt beállítást kell meghatároznia. Ebben az esetbenMinimal, és Normal ugyanazt a kimenetet hozza létre, és DiagnosticDetailed hasonlóképpen ugyanaz lesz. Ez lehetővé teszi, hogy a felhasználók egyszerűen beírják, amit ismernek, és a legjobb illeszkedést használják.

Az elvárás Quiet az, hogy a konzolon ne jelenjen meg kimenet. Ha azonban egy alkalmazás interaktív módot kínál, az alkalmazásnak az alábbi lehetőségek egyikét kell elvégeznie:

• Ha meg van adva, akkor is --verbosity megjelenik a bemenet --interactive kéréseQuiet.
• Tiltsa le a használatot --verbosity Quiet és --interactive együtt.

Ellenkező esetben az alkalmazás a bemenetre vár anélkül, hogy elmondaná a felhasználónak, hogy mire vár. Úgy tűnik, hogy az alkalmazás lefagyott, és a felhasználónak fogalma sincs arról, hogy az alkalmazás a bemenetre vár.

Ha aliasokat definiál, argumentum nélkül használjon -v--verbosity és hozzon létre -v egy aliast a következőhöz --verbosity Diagnostic: . A következőhöz használható -q--verbosity Quiet: .

A .NET CLI és a POSIX konvenciók

A .NET CLI nem követi következetesen az összes POSIX-konvenciót.

Dupla kötőjel

A .NET CLI számos parancsa rendelkezik a kétkötőjeles jogkivonat speciális implementációval. Az alábbi -- jogkivonatok esetében dotnet tool rundotnet rundotnet watcha rendszer átadja a parancs által futtatott alkalmazást. Példa:

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

Ebben a példában a --project parancsot a rendszer átadja a dotnet run parancsnak, és az --message argumentummal rendelkező beállítás parancssori beállításként lesz átadva a myappnak a futtatáskor.

A -- jogkivonat nem mindig szükséges a beállításoknak a használatával dotnet runfuttatott alkalmazásoknak való átadásához. A dupla kötőjel nélkül a dotnet run parancs automatikusan átadja a futtatott alkalmazásnak azokat a beállításokat, amelyek nem ismerhetők fel önmagára dotnet run vagy az MSBuildre való alkalmazásként. Ezért a következő parancssorok egyenértékűek, mert dotnet run nem ismeri fel az argumentumokat és a beállításokat:

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

Az argumentumok elválasztó elemének kihagyása

A .NET CLI nem támogatja a POSIX-konvenciót, amely lehetővé teszi, hogy kihagyja a határolójelet egy karakteres beállítási alias megadásakor.

Több argumentum a beállításnév megismétlése nélkül

A .NET CLI nem fogad el több argumentumot egy beállításhoz a beállításnév megismétlése nélkül.

Logikai beállítások

A .NET CLI-ben egyes logikai beállítások ugyanazt a viselkedést eredményezik, amikor átadja false a bérletet, mint az átadáskor true. Ez a viselkedés akkor jelentkezik, ha a lehetőséget megvalósító .NET CLI-kód csak a beállítás meglétét vagy hiányát ellenőrzi, figyelmen kívül hagyva az értéket. Példa a --no-restore parancsra dotnet build . A pass no-restore false és a visszaállítási művelet ugyanúgy lesz kihagyva, mint a megadott no-restore true vagy no-restorea .

Kebab-eset

Bizonyos esetekben a .NET CLI nem használ kebab-esetet parancsok, beállítások vagy argumentumok neveihez. Van például egy .NET CLI-beállítás, amely ahelyett --additional-probing-pathvan elnevezve--additionalprobingpath.

Lásd még

• 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