Syntaxöversikt: Kommandon, alternativ och argument

2025-06-19

Viktigt!

System.CommandLine är för närvarande i förhandsversion och den här dokumentationen gäller version 2.0 beta 5. Viss information gäller förhandsversionsprodukt som kan ändras avsevärt innan den släpps. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

Den här artikeln förklarar kommandoradssyntaxen som System.CommandLine känner igen. Informationen är användbar för både användare och utvecklare av .NET-kommandoradsappar, inklusive .NET CLI.

Tokener

System.CommandLine parsar kommandoradsindata i token, som är strängar avgränsade med blanksteg. Till exempel, överväg följande kommandorad:

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

Denna inmatning analyseras av dotnet-applikationen till tokens tool, install, dotnet-suggest, --global, --verbosity och quiet.

Token tolkas som kommandon, alternativ eller argument. Kommandoradsappen som anropas bestämmer hur token efter den första tolkas. I följande tabell visas hur System.CommandLine tolkar föregående exempel:

Bevis	Parsade som
`tool`	Underkommando
`install`	Underkommando
`dotnet-suggest`	Argument för installationskommando
`--global`	Alternativ för installationskommando
`--verbosity`	Alternativ för installationskommando
`quiet`	Argument för `--verbosity` alternativ

En token kan innehålla blanksteg om den är omsluten av citattecken ("). Här är ett exempel:

dotnet tool search "ef migrations add"

Kommandon

Ett kommando i kommandoradsinmatning är en token som specificerar en åtgärd eller definierar en grupp av relaterade åtgärder. Till exempel:

I dotnet run är run ett kommando som specificerar en handling.
I dotnet tool install, är install ett kommando som specificerar en åtgärd, och tool är ett kommando som specificerar en grupp av relaterade kommandon. Det finns andra verktygsrelaterade kommandon, till exempel tool uninstall, tool listoch tool update.

Rotkommando

Rotkommandot är det som anger namnet på appens körbara fil. Till exempel, kommandot dotnet specificerar dotnet.exe-exekverbara filen.

System.CommandLine.Command är den allmänna klassen för alla kommandon eller underkommandon, medan System.CommandLine.RootCommand är en specialiserad version som är avsedd för programmets rotinmatningspunkt och ärver alla funktioner System.CommandLine.Command i men lägger till rotspecifikt beteende och standardvärden, till exempel hjälpalternativ, versionsalternativ och förslagsdirektiv.

Underkommandon

De flesta kommandoradsprogram stöder underkommandon, även kallade verb. Till exempel har kommandot dotnet ett underkommando run som du anropar genom att ange dotnet run.

Underkommandon kan ha sina egna underkommandon. I dotnet tool install är install en underkommando till tool.

Du kan lägga till underkommandon enligt följande exempel:

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

Den innersta underkommandot i det här exemplet kan anropas så här:

myapp sub1 sub1a

Alternativ

Ett alternativ är en namngiven parameter som kan skickas till ett kommando. POSIX CLIs prefixar vanligtvis alternativnamnet med två bindestreck (--). Följande exempel visar två alternativ:

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

Som detta exempel illustrerar kan värdet av alternativet vara explicit (quiet för --verbosity) eller implicit (inget följer --global). Alternativ som inte har något värde angivet är vanligtvis Booleska parametrar som som standard är true om alternativet anges på kommandoraden.

För vissa Windows-kommandoradsappar identifierar du ett alternativ med hjälp av ett inledande snedstreck (/) med alternativnamnet. Till exempel:

msbuild /version
        ^------^

System.CommandLine stöder både POSIX- och Windows-prefixkonventioner.

När du konfigurerar ett alternativ anger du alternativnamnet, inklusive prefixet:

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

Om du vill lägga till ett alternativ i ett kommando och rekursivt till alla dess underkommandon System.CommandLine.Symbol.Recursive använder du egenskapen .

Obligatoriska alternativ

Vissa alternativ har obligatoriska argument. I .NET CLI --output kräver till exempel ett argument för mappnamn. Om argumentet inte tillhandahålls misslyckas kommandot. Om du vill göra ett alternativ obligatoriskt anger du dess System.CommandLine.Symbol.Required egenskap till true, som du ser i följande exempel:

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

Om ett obligatoriskt alternativ har ett standardvärde (anges via DefaultValueFactory egenskap) behöver alternativet inte anges på kommandoraden. I så fall ger standardvärdet det obligatoriska alternativvärdet.

Argumentpunkter

Ett argument är en namnlös parameter som kan skickas till ett kommando. I följande exempel visas ett argument för build kommandot.

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

När du konfigurerar ett argument anger du argumentnamnet (det används inte för parsning, men det kan användas för att hämta tolkade värden efter namn eller visa hjälp) och skriver:

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

Standardvärden

Både argument och alternativ kan ha standardvärden som gäller om inget argument uttryckligen anges. Till exempel är många alternativ implicit Boolean-parametrar med ett standardvärde på true när alternativets namn finns på kommandoraden. Följande exempel på kommandorader är likvärdiga:

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

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

Ett argument som definieras utan ett standardvärde behandlas som ett obligatoriskt argument.

Tolkningsfel

Alternativ och argument har förväntade typer och ett fel genereras när värdet inte kan parsas. Ett exempel är att följande kommando ger ett fel eftersom "silent" inte är ett av de giltiga värdena för --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'

Argument har också förväntningar på hur många värden som kan anges. Exempel ges i avsnittet om argumentens aritet.

Ordning av alternativ och argument

Du kan ange alternativ före argument eller argument före alternativ på kommandoraden. Följande kommandon är likvärdiga:

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

Alternativ kan anges i vilken ordning som helst. Följande kommandon är likvärdiga:

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

När det finns flera argument spelar ordningen roll. Följande kommandon är inte likvärdiga. de skiljer sig åt i ordningen på värdena, vilket kan leda till olika resultat:

myapp argument1 argument2
myapp argument2 argument1

Aliasnamn

I både POSIX och Windows är det vanligt att vissa kommandon och alternativ har aliaser. Dessa är vanligtvis kortformer som är enklare att skriva. Alias kan också användas för andra ändamål, till exempel för att simulera skiftlägeskänslighet och för att stödja alternativa stavningar av ett ord.

POSIX-kortformer har vanligtvis ett enda inledande bindestreck följt av ett enda tecken. Följande kommandon är likvärdiga:

dotnet build --verbosity quiet
dotnet build -v quiet

Den GNU-standarden rekommenderar automatiska alias. Det vill säga, du kan ange vilken del som helst av ett långformat kommando eller alternativnamn, och det kommer att accepteras. Detta beteende skulle göra följande kommandorader ekvivalenta:

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 stöder inte automatiska alias. Varje alias måste anges explicit. Både kommandon och alternativ exponerar en Aliases egenskap. Option har en konstruktor som accepterar alias som parametrar, så du kan definiera ett alternativ med flera alias på en enda rad:

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

Vi rekommenderar att du minimerar antalet alternativalias som du definierar och undviker att definiera vissa alias i synnerhet. För mer information, se Korta alias.

Skiftlägesberoende

Kommandon, alternativnamn och alias är som standard skiftlägeskänsliga enligt POSIX-konventionen, och System.CommandLine följer denna konvention. Om du vill att din CLI ska vara skiftlägesokänslig, definiera alias för de olika skiftlägealternativen. Kan till exempel --additional-probing-path ha alias --Additional-Probing-Path och --ADDITIONAL-PROBING-PATH.

I vissa kommandoradsverktyg anger en skillnad i hölje en skillnad i funktion. Till exempel git clean -X beter sig annorlunda än git clean -x. .NET CLI är i enbart små bokstäver.

Skiftlägeskänslighet gäller inte för argumentvärden för alternativ baserade på enumerationer. Enum-namn matchas oavsett versaler och gemener.

Token `--`

POSIX-konventionen tolkar dubbelstreck (--) tecken som en escape-mekanism. Allt som följer efter dubbelbindestrecks-tokenen tolkas som argument för kommandot. Den här funktionen kan användas för att skicka argument som ser ut som alternativ, eftersom den förhindrar att de tolkas som alternativ.

Anta att myapp tar ett message argument, och du vill att värdet av message ska vara --interactive. Den följande kommandoraden kan ge oväntade resultat.

myapp --interactive

Om myapp inte har något --interactive alternativ --interactive tolkas token som ett argument. Men om appen har ett --interactive alternativ tolkas dessa indata som refererar till det alternativet.

Den följande kommandoraden använder en dubbelstreckstoken för att ställa in värdet på message-argumentet till "--interactive":

myapp -- --interactive
      ^^

System.CommandLine stödjer denna dubbelstrecks-funktionalitet.

Avgränsare för alternativargument

System.CommandLine låter dig använda blanksteget "=" eller ":" som avgränsare mellan ett alternativnamn och dess argument. Till exempel, följande kommandon är likvärdiga:

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

Med en POSIX-konvention kan du utelämna avgränsare när du anger ett alternativalias med ett tecken. Till exempel, följande kommandon är likvärdiga:

myapp -vquiet
myapp -v quiet

System.CommandLine stöder den här syntaxen som standard.

Argumentaritet

Arityn på ett alternativs eller en kommands argument är antalet värden som kan passeras om det alternativet eller kommandot anges.

Arity uttrycks med ett minsta värde och ett största värde, som följande tabell illustrerar:

Min	Max	Exempel giltighet	Exempel
0	0	Giltig:	--fil
		Ogiltig:	--file a.json
		Ogiltig:	--file a.json --file b.json
0	1	Giltig:	--flagga
		Giltig:	--flagga sant
		Giltig:	--flagga falskt
		Ogiltig:	--flagga falskt --flagga falskt
1	1	Giltig:	--file a.json
		Ogiltig:	--fil
		Ogiltig:	--file a.json --file b.json
0	n	Giltig:	--fil
		Giltig:	--file a.json
		Giltig:	--file a.json --file b.json
1	n	Giltig:	--file a.json
		Giltig:	--file a.json b.json
		Ogiltig:	--fil

System.CommandLine har en System.CommandLine.ArgumentArity struct för att definiera aritet, med följande värden:

System.CommandLine.ArgumentArity.Zero - Inga värden tillåtna.
System.CommandLine.ArgumentArity.ZeroOrOne - Kan ha ett värde, kan sakna värden.
System.CommandLine.ArgumentArity.ExactlyOne - Måste ha ett värde.
System.CommandLine.ArgumentArity.ZeroOrMore - Kan ha ett värde, flera värden eller inga värden.
System.CommandLine.ArgumentArity.OneOrMore – Kan ha flera värden, måste ha minst ett värde.

Du kan explicit sätta aritet med hjälp av Arity egenskapen, men det behövs oftast inte. System.CommandLine avgör automatiskt argumentariteten baserat på argumenttypen:

Argumenttyp	Standardaritet
`Boolean`	`ArgumentArity.ZeroOrOne`
Samlingstyper	`ArgumentArity.ZeroOrMore`
Allt annat	`ArgumentArity.ExactlyOne`

Alternativ åsidosättningar

Om aritetsmaximaltalet är 1 kan System.CommandLine fortfarande konfigureras för att acceptera flera instanser av ett alternativ. I det fallet skriver den sista förekomsten av ett upprepat alternativ över alla tidigare förekomster. I följande exempel skulle värdet 2 skickas till myapp-kommandot.

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

Flera argument

När du anropar ett kommando kan du som standard upprepa ett alternativnamn för att ange flera argument för ett alternativ som har maximal aritet som är större än ett.

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

Om du vill tillåta flera argument utan att upprepa alternativnamnet anger du System.CommandLine.Option.AllowMultipleArgumentsPerToken till true. Med den här inställningen kan du ange följande kommandorad.

myapp --items one two three

Samma inställning har en annan effekt om maximal argumentaritet är 1. Det gör att du kan upprepa ett alternativ men tar bara det sista värdet på raden. I följande exempel skickas värdet three till appen.

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

Paketlösning

POSIX rekommenderar att du stöder sammanställning av enstaka teckenalternativ, även känd som stapling. Bundlade alternativ är alias för enstaka teckenalternativ som anges tillsammans efter ett enda bindestreck som prefix. Endast det sista alternativet kan ange ett argument. Till exempel är följande kommandorader likvärdiga:

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

Om ett argument tillhandahålls efter en alternativbunt, gäller det för det sista alternativet i bunten. Följande kommandorader är likvärdiga:

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

I båda varianterna i detta exempel skulle argumentet arg endast gälla för alternativet -c.

Booleska alternativ (flaggor)

Om true eller false överlämnas för ett alternativ med ett bool-argument, analyseras det som förväntat. Men ett alternativ vars argumenttyp är bool kräver vanligtvis inte att ett argument specificeras. Booleska alternativ, som ibland kallas "flaggor", har vanligtvis en aritet på System.CommandLine.ArgumentArity.ZeroOrOne. Förekomsten av alternativnamnet i kommandoraden, utan något argument som följer det, resulterar i ett standardvärde på true. Avsaknad av alternativnamn i kommandoradsinmatning resulterar i ett värde av false. Om kommandot myapp skriver ut värdet av ett booleskt alternativ som heter --interactive, skapar följande input följande output:

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

False
True
False
True

Versionsalternativ

Appar som bygger på System.CommandLine anger automatiskt versionsnumret som svar på det --version-alternativ som används med rotkommandot. Till exempel:

dotnet --version

6.0.100

Svarsfiler

En svarsfil är en fil som innehåller en uppsättning tokens för ett kommandoradsprogram. Svarsfiler är en funktion i System.CommandLine som är användbar i två scenarier:

Så här anropar du en kommandoradsapp genom att ange indata som är längre än terminalens teckengräns.
Så här anropar du samma kommando upprepade gånger utan att skriva om hela raden.

För att använda en svarfil, skriv in filnamnet med ett @-tecken före där du vill infoga kommandon, alternativ och argument i raden. Filändelsen .rsp är en vanlig konvention, men du kan använda vilken filändelse som helst.

Följande rader är likvärdiga.

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

Innehållet i sample1.rsp:

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

Innehållet i sample2.rsp:

--no-restore

Här är syntaxregler som bestämmer hur texten i en responsfil tolkas:

Token avgränsas av mellanslag. En rad som innehåller God morgon! behandlas som två tokens, God och morgon!.
Flera token inneslutna i citattecken tolkas som en enda token. En rad som innehåller "God morgon!" behandlas som en token, God morgon!.
All text mellan en # symbol och slutet av raden behandlas som en kommentar och ignoreras.
Tokens som är prefixade med @ kan hänvisa till ytterligare svarsfiler.
Svarsfilen kan ha flera rader med text. Raderna sammanfogas och tolkas som en sekvens av tecken.

Direktiv

System.CommandLine introducerar ett syntaktiskt element som kallas ett direktiv som representeras av System.CommandLine.Directive typ. Direktivet [diagram] är ett exempel. När du inkluderar [diagram] efter appens namn, visar System.CommandLine ett diagram av tolkningsresultatet istället för att starta kommandoradsappen.

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

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

Syftet med direktiven är att tillhandahålla övergripande funktioner som kan tillämpas i kommandoradsappar. Eftersom direktiv är syntaktiskt olika från appens egen syntax kan de tillhandahålla funktionalitet som gäller över flera appar.

En direktiv måste uppfylla följande syntaxregler:

Det är en symbol på kommandoraden som kommer efter appens namn men före några underkommandon eller alternativ.
Det är inneslutet i hakparenteser.
Den innehåller inte mellanslag.

En oigenkänd direktiv ignoreras utan att orsaka ett analysfel.

Ett direktiv kan inkludera ett argument, separerat från direktivnamnet med ett kolon.

Följande direktiv är inbyggda:

[diagram]
[suggest]

Direktivet `[diagram]`

Både användare och utvecklare kan ha nytta av att se hur en app tolkar en viss indata. En av standardfunktionerna i en System.CommandLine app är [diagram] direktivet, som låter dig förhandsgranska resultatet av att parsa kommandoindata. Till exempel:

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

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

I föregående exempel:

Kommandot (myapp), dess underalternativ och argumenten för dessa alternativ grupperas med hjälp av hakparenteser.
För alternativresultatet [ --delay !<not-an-int> ] indikerar ! ett parsningsfel. Värdet not-an-int för ett int alternativ kan inte parsas till den förväntade typen. Felet flaggas också av ! framför kommandot som innehåller det felade alternativet: ![ myapp....
För alternativresultatet *[ --fgcolor <White> ]angavs inte alternativet på kommandoraden, så den konfigurerade standardinställningen användes. White är det effektiva värdet för det här alternativet. Asterisken anger att värdet är standard.
???--> pekar på indata som inte matchades med något av appens kommandon eller alternativ.

Föreslå direktiv

Med [suggest] direktivet kan du söka efter kommandon när du inte känner till det exakta kommandot.

dotnet [suggest] buil

build
build-server
msbuild

Dela via