Syntaxübersicht: Befehle, Optionen und Argumente

2025-06-22

Wichtig

System.CommandLine befindet sich derzeit in DER VORSCHAU, und diese Dokumentation ist für Version 2.0 Beta 5 vorgesehen. Einige Informationen beziehen sich auf vorab veröffentlichte Produkte, die vor der Veröffentlichung erheblich geändert werden können. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

In diesem Artikel wird die Befehlszeilensyntax erläutert, die System.CommandLine erkennt. Die Informationen sind sowohl für Benutzer als auch Für Entwickler von .NET-Befehlszeilen-Apps nützlich, einschließlich der .NET CLI.

Token

System.CommandLine analysiert die Befehlszeileneingabe in Token, bei denen es sich um Zeichenfolgen handelt, die durch Leerzeichen getrennt sind. Betrachten Sie beispielsweise die folgende Befehlszeile:

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

Diese Eingabe wird von der dotnet Anwendung in Token tool, install, dotnet-suggest, --global, --verbosity und quiet umgewandelt.

Token werden als Befehle, Optionen oder Argumente interpretiert. Die App in der Befehlszeile, die aufgerufen wird, bestimmt, wie die Token nach dem ersten Token interpretiert werden. In der folgenden Tabelle wird gezeigt, wie System.CommandLine das vorherige Beispiel interpretiert wird:

Zeichen	Analysiert als
`tool`	Unterbefehl
`install`	Unterbefehl
`dotnet-suggest`	Argument für den Installationsbefehl
`--global`	Option für den Installationsbefehl
`--verbosity`	Option für den Installationsbefehl
`quiet`	Argument für `--verbosity` Option

Ein Token kann Leerzeichen enthalten, wenn es in Anführungszeichen (") eingeschlossen ist. Ein Beispiel:

dotnet tool search "ef migrations add"

Befehle

Ein Befehl in der Befehlszeileneingabe ist ein Token, das eine Aktion angibt oder eine Gruppe verwandter Aktionen definiert. Beispiel:

In dotnet run, run ist ein Befehl, der eine Aktion angibt.
In dotnet tool install, install ist ein Befehl, der eine Aktion angibt und tool ein Befehl ist, der eine Gruppe verwandter Befehle angibt. Es gibt weitere toolbezogene Befehle, z. B. tool uninstall, tool list und tool update.

Stammbefehl

Der Stammbefehl ist der Befehl, der den Namen der ausführbaren Datei der App angibt. Beispielsweise gibt der dotnet Befehl die dotnet.exe ausführbare Datei an.

System.CommandLine.Commandist die allgemeine Klasse für jeden Befehl oder Unterbefehl, während System.CommandLine.RootCommand es sich um eine spezielle Version handelt, die für den Stammeinstiegspunkt der Anwendung vorgesehen ist und alle Features erbt, die System.CommandLine.Command jedoch stammspezifisches Verhalten und Standardwerte wie Hilfeoption, Versionsoption und Vorschlagsdirektive hinzufügen.

Unterbefehle

Die meisten Befehlszeilen-Apps unterstützen Unterbefehle, auch als Verben bezeichnet. Beispielsweise verfügt der dotnet Befehl über einen run Unterbefehl, den Sie aufrufen, indem Sie folgendes eingeben dotnet run.

Unterbefehle können über eigene Unterbefehle verfügen. In dotnet tool install, install ist ein Unterbefehl von tool.

Sie können Unterbefehle hinzufügen, wie im folgenden Beispiel gezeigt:

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

Der innerste Unterbefehl in diesem Beispiel kann wie folgt aufgerufen werden:

myapp sub1 sub1a

Optionen

Eine Option ist ein benannter Parameter, der an einen Befehl übergeben werden kann. POSIX CLIs präfixen in der Regel den Optionsnamen mit zwei Bindestrichen (--). Das folgende Beispiel zeigt zwei Optionen:

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

Wie in diesem Beispiel dargestellt, kann der Wert der Option explizit (quiet für --verbosity) oder implizit (nichts folgt --global) sein. Optionen, für die kein Wert angegeben ist, sind in der Regel boolesche Parameter, die standardmäßig auf true gesetzt werden, wenn die Option in der Befehlszeile angegeben wird.

Bei einigen Windows-Befehlszeilen-Apps identifizieren Sie eine Option mithilfe eines führenden Schrägstrichs (/) mit dem Optionsnamen. Beispiel:

msbuild /version
        ^------^

System.CommandLine unterstützt sowohl POSIX- als auch Windows-Präfixkonventionen.

Wenn Sie eine Option konfigurieren, geben Sie den Optionsnamen einschließlich des Präfixes an:

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

Zum Hinzufügen einer Option zu einem Befehl und rekursiv zu allen unterbefehlen verwenden Sie die System.CommandLine.Symbol.Recursive Eigenschaft.

Erforderliche Optionen

Einige Optionen weisen erforderliche Argumente auf. In der .NET CLI erfordert --output z. B. ein Argument für den Ordnernamen. Wenn das Argument nicht angegeben wird, schlägt der Befehl fehl. Um eine Option erforderlich zu machen, legen Sie ihre System.CommandLine.Symbol.Required Eigenschaft auf true, wie im folgenden Beispiel gezeigt:

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

Wenn eine erforderliche Option über einen Standardwert (über die Eigenschaft angegeben DefaultValueFactory ) verfügt, muss die Option nicht in der Befehlszeile angegeben werden. In diesem Fall stellt der Standardwert den erforderlichen Optionswert bereit.

Argumente

Ein Argument ist ein unbenannter Parameter, der an einen Befehl übergeben werden kann. Das folgende Beispiel zeigt ein Argument für den build Befehl.

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

Wenn Sie ein Argument konfigurieren, geben Sie den Argumentnamen an (es wird nicht für die Analyse verwendet, kann aber zum Abrufen analysierter Werte nach Name oder Anzeigen von Hilfe) und Typ verwendet werden:

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

Standardwerte

Sowohl Argumente als auch Optionen können Standardwerte aufweisen, die angewendet werden, wenn kein Argument explizit bereitgestellt wird. Viele Optionen sind z. B. implizit boolesche Parameter mit einer Standardeinstellung, true wenn sich der Optionsname in der Befehlszeile befindet. Die folgenden Befehlszeilenbeispiele sind gleichwertig:

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

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

Ein Argument, das ohne Standardwert definiert ist, wird als erforderliches Argument behandelt.

Analysefehler

Optionen und Argumente haben erwartete Typen, und ein Fehler wird erzeugt, wenn der Wert nicht analysiert werden kann. Beispiel: Der folgende Befehl führt zu einem Fehler, da "silent" kein gültiger Wert für --verbosity ist.

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'

Argumente haben auch Erwartungen darüber, wie viele Werte bereitgestellt werden können. Beispiele werden im Abschnitt zu Argumentarität bereitgestellt.

Reihenfolge der Optionen und Argumente

Sie können Optionen vor Argumenten oder Argumenten vor Optionen in der Befehlszeile bereitstellen. Die folgenden Befehle sind gleichwertig:

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

Optionen können in beliebiger Reihenfolge angegeben werden. Die folgenden Befehle sind gleichwertig:

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

Wenn mehrere Argumente vorhanden sind, spielt die Reihenfolge eine Rolle. Die folgenden Befehle sind nicht gleichwertig. sie unterscheiden sich in der Reihenfolge der Werte, die zu unterschiedlichen Ergebnissen führen können:

myapp argument1 argument2
myapp argument2 argument1

Decknamen

In POSIX und Windows ist es üblich, dass einige Befehle und Optionen Aliase haben. Dies sind in der Regel kurze Formen, die einfacher zu eingeben sind. Aliase können auch für andere Zwecke verwendet werden, z. B. zum Simulieren der Groß -/Kleinschreibung und zur Unterstützung alternativer Schreibweisen eines Worts.

POSIX-Kurzformen weisen in der Regel einen einzigen führenden Bindestrich auf, gefolgt von einem einzelnen Zeichen. Die folgenden Befehle sind gleichwertig:

dotnet build --verbosity quiet
dotnet build -v quiet

Der GNU-Standard empfiehlt automatische Aliase. Das heißt, Sie können einen beliebigen Teil eines Long-Form-Befehls oder eines Optionsnamens eingeben, der akzeptiert wird. Dieses Verhalten macht die folgenden Befehlszeilen gleichwertig:

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 unterstützt keine automatischen Aliase. Jeder Alias muss explizit angegeben werden. Sowohl Befehle als auch Optionen machen eine Aliases Eigenschaft verfügbar. Option verfügt über einen Konstruktor, der Aliase als Parameter akzeptiert, sodass Sie eine Option mit mehreren Aliasen in einer einzelnen Zeile definieren können:

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

Es wird empfohlen, die Anzahl der von Ihnen definierten Optionsalias zu minimieren und bestimmte Aliase insbesondere zu vermeiden. Weitere Informationen finden Sie unter Kurzformaliasen.

Groß- und Kleinschreibung

Bei Befehls- und Optionsnamen sowie Aliasen wird standardmäßig gemäß der POSIX-Konvention die Groß-/Kleinschreibung beachtet, und System.CommandLine folgt dieser Konvention. Wenn Sie möchten, dass Ihre Befehlszeilenschnittstelle die Groß- und Kleinschreibung nicht beachtet, definieren Sie Aliase für die verschiedenen Alternativen der Groß-/Kleinschreibung. Beispielsweise könnte --additional-probing-path Aliase --Additional-Probing-Path und --ADDITIONAL-PROBING-PATH haben.

In einigen Befehlszeilentools weist ein Unterschied in der Groß-/Kleinschreibung auf einen Unterschied in der Funktion hin. Zum Beispiel verhält sich git clean -X anders als git clean -x. Die .NET CLI wird komplett in Kleinbuchstaben geschrieben.

Die Groß- und Kleinschreibung wird bei Argumenten für Optionen, die auf Enumerationen basieren, nicht beachtet. Enumerationsnamen werden unabhängig von der Groß-/Kleinschreibung abgeglichen.

`--`-Token

Die POSIX-Konvention interpretiert das Token mit doppeltem Bindestrich (--) als Escapemechanismus. Alles, was auf das Doppelstrich-Token folgt, wird als Argument für den Befehl interpretiert. Diese Funktionalität kann verwendet werden, um Argumente zu übermitteln, die wie Optionen aussehen, da sie daran gehindert werden, als Optionen interpretiert zu werden.

Angenommen, myapp akzeptiert ein message Argument, und Sie möchten, dass der Wert message sein --interactivesoll. Die folgende Befehlszeile kann unerwartete Ergebnisse liefern.

myapp --interactive

Wenn myapp keine --interactive Option vorhanden ist, wird das --interactive Token als Argument interpretiert. Wenn die App jedoch über eine --interactive Option verfügt, wird diese Eingabe als Verweis auf diese Option interpretiert.

Die folgende Befehlszeile verwendet das Doppelstrichtoken, um den Wert des message Arguments auf "--interactive" festzulegen:

myapp -- --interactive
      ^^

System.CommandLine unterstützt diese Doppelstrichfunktion.

Trennzeichen für Optionsargumente

System.CommandLine ermöglicht ihnen, ein Leerzeichen, "=" oder ":" als Trennzeichen zwischen einem Optionsnamen und dessen Argument zu verwenden. Die folgenden Befehle sind z. B. gleichwertig:

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

Mit einer POSIX-Konvention können Sie das Trennzeichen weglassen, wenn Sie einen Single-Character-Optionsalias angeben. Die folgenden Befehle sind z. B. gleichwertig:

myapp -vquiet
myapp -v quiet

System.CommandLine unterstützt diese Syntax standardmäßig.

Argumentarität

Die Arity eines Arguments einer Option oder eines Befehls beschreibt die Anzahl der Werte, die übergeben werden können, wenn diese Option oder dieser Befehl angegeben ist.

Arity wird mit einem Minimalwert und einem Maximalwert ausgedrückt, wie die folgende Tabelle veranschaulicht:

Min	Max.	Gültigkeit des Beispiels	Beispiel
0	0	Gültig:	--Datei
		Ungültig:	--file a.json
		Ungültig:	--file a.json --file b.json
0	1	Gültig:	--Flagge
		Gültig:	--flag true
		Gültig:	--flag false
		Ungültig:	--flag false --flag false
1	1	Gültig:	--file a.json
		Ungültig:	--Datei
		Ungültig:	--file a.json --file b.json
0	n	Gültig:	--Datei
		Gültig:	--file a.json
		Gültig:	--file a.json --file b.json
1	n	Gültig:	--file a.json
		Gültig:	--file a.json b.json
		Ungültig:	--Datei

System.CommandLine weist eine System.CommandLine.ArgumentArity Struktur zum Definieren von Arität mit den folgenden Werten auf:

System.CommandLine.ArgumentArity.Zero - Es sind keine Werte zulässig.
System.CommandLine.ArgumentArity.ZeroOrOne - Kann einen Wert haben oder keine Werte.
System.CommandLine.ArgumentArity.ExactlyOne - Muss einen Wert aufweisen.
System.CommandLine.ArgumentArity.ZeroOrMore - Kann einen Wert, mehrere Werte oder keine Werte aufweisen.
System.CommandLine.ArgumentArity.OneOrMore - Kann mehrere Werte aufweisen, muss mindestens einen Wert aufweisen.

Sie können die Arität explizit mithilfe der Arity Eigenschaft festlegen, aber in den meisten Fällen ist dies nicht erforderlich. System.CommandLine bestimmt automatisch die Argumentarität basierend auf dem Argumenttyp:

Argumenttyp	Standardarrität
`Boolean`	`ArgumentArity.ZeroOrOne`
Auflistungstypen	`ArgumentArity.ZeroOrMore`
Alle anderen	`ArgumentArity.ExactlyOne`

Außerkraftsetzung von Optionen

Wenn das Aritätsmaximum 1 ist, kann System.CommandLine weiterhin so konfiguriert werden, dass mehrere Instanzen einer Option akzeptiert werden. In diesem Fall überschreibt die letzte Instanz einer wiederholten Option alle früheren Instanzen. Im folgenden Beispiel wird der Wert 2 an den myapp Befehl übergeben.

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

Mehrere Argumente

Wenn Sie einen Befehl aufrufen, können Sie standardmäßig einen Optionsnamen wiederholen, um mehrere Argumente für eine Option anzugeben, die die maximale Arität größer als eins hat.

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

Um mehrere Argumente zuzulassen, ohne den Optionsnamen zu wiederholen, legen Sie diesen System.CommandLine.Option.AllowMultipleArgumentsPerToken auf true. Mit dieser Einstellung können Sie die folgende Befehlszeile eingeben.

myapp --items one two three

Die gleiche Einstellung hat einen anderen Effekt, wenn die maximale Argumentarität 1 ist. Sie können eine Option wiederholen, aber nur den letzten Wert in der Zeile verwenden. Im folgenden Beispiel wird der Wert three an die App übergeben.

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

Bündelung von Optionen

POSIX empfiehlt, die Bündelung von Einzelzeichenoptionen, auch als Stapeln bezeichnet, zu unterstützen. Gebündelte Optionen sind Optionsaliase für einzelne Zeichen, die zusammen nach einem einzelnen Bindestrichpräfix angegeben werden. Nur die letzte Option kann ein Argument angeben. Die folgenden Befehlszeilen sind z. B. gleichwertig:

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

Wenn ein Argument nach einem Optionsbundle bereitgestellt wird, gilt es für die letzte Option im Bündel. Die folgenden Befehlszeilen sind gleichwertig:

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

In beiden Varianten in diesem Beispiel würde das Argument arg nur für die Option -cgelten.

Boolesche Optionen (Flags)

Wenn für eine Option mit einem true-Argument false oder bool übergeben wird, wird sie wie erwartet analysiert. Eine Option, deren Argumenttyp bool ist, erfordert normalerweise keine Angabe eines Arguments. Boolesche Optionen, manchmal auch als "Flags" bezeichnet, weisen in der Regel eine Arität von System.CommandLine.ArgumentArity.ZeroOrOne auf. In der Befehlszeile führt das Vorhandensein des Optionsnamens ohne nachfolgendes Argument zu einem Standardwert von true. Das Fehlen des Optionsnamens in der Befehlszeileneingabe führt zu einem Wert von false. Wenn der myapp Befehl den Wert einer booleschen Option mit dem Namen --interactiveausgibt, erstellt die folgende Eingabe die folgende Ausgabe:

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

False
True
False
True

Option "Version"

Apps, die auf der System.CommandLine Basis erstellt wurden, stellen automatisch die Versionsnummer als Reaktion auf die --version Option bereit, die mit dem Stammbefehl verwendet wird. Beispiel:

dotnet --version

6.0.100

Antwortdateien

Eine Antwortdatei ist eine Datei, die einen Satz von Token für eine Befehlszeilen-App enthält. Antwortdateien sind eine Funktion von System.CommandLine, die in zwei Szenarien nützlich ist:

So rufen Sie eine Befehlszeilen-App auf, indem Sie Eingaben angeben, die länger als die Zeichengrenze des Terminals sind.
Wenn Sie denselben Befehl wiederholt aufrufen möchten, ohne die gesamte Zeile neu eingeben zu müssen.

Wenn Sie eine Antwortdatei verwenden möchten, geben Sie den Dateinamen ein, dem ein @ Zeichen vorangestellt ist, an der Stelle, an der Sie Befehle, Optionen und Argumente einfügen möchten. Die RSP-Dateierweiterung ist eine gängige Konvention, Sie können jedoch jede Dateierweiterung verwenden.

Die folgenden Zeilen sind gleichwertig:

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

Inhalt von sample1.rsp:

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

Inhalt von sample2.rsp:

--no-restore

Hier sind Syntaxregeln, die bestimmen, wie der Text in einer Antwortdatei interpretiert wird:

Tokens werden durch Leerzeichen getrennt. Eine Zeile, die Guten Morgen enthält! wird als zwei Token behandelt: "Gut " und "Morgen!".
Mehrere in Anführungszeichen eingeschlossene Token werden als ein einzelnes Token interpretiert. Eine Zeile, die "Guten Morgen!" enthält, wird als ein Token behandelt, Guten Morgen!.
Jeder Text zwischen einem # Symbol und dem Ende der Zeile wird als Kommentar behandelt und ignoriert.
Token mit Präfix @ können auf zusätzliche Antwortdateien verweisen.
Die Antwortdatei kann mehrere Textzeilen enthalten. Die Zeilen werden verkettet und als Abfolge von Token interpretiert.

Anweisungen

System.CommandLine führt ein syntaktisches Element ein, das als Direktive bezeichnet wird, die vom System.CommandLine.Directive Typ dargestellt wird. Die [diagram] Direktive ist ein Beispiel. Wenn Sie [diagram] nach dem Namen der App einschließen, wird System.CommandLine ein Diagramm des Analyseergebnisses angezeigt, anstatt die Befehlszeilen-App aufzurufen.

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

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

Der Zweck von Direktiven besteht darin, übergreifende Funktionen bereitzustellen, die für befehlszeilenübergreifende Apps gelten können. Da direktiven sich syntaktisch von der eigenen Syntax der App unterscheiden, können sie Funktionen bereitstellen, die für alle Apps gelten.

Eine Direktive muss den folgenden Syntaxregeln entsprechen:

Es ist ein Token in der Befehlszeile, das nach dem Namen der App, aber vor allen Unterbefehlen oder Optionen kommt.
Sie ist in eckige Klammern eingeschlossen.
Sie enthält keine Leerzeichen.

Eine nicht erkannte Direktive wird ignoriert, ohne einen Analysefehler zu verursachen.

Eine Direktive kann ein Argument enthalten, getrennt vom Direktivennamen durch einen Doppelpunkt.

Die folgenden Direktiven sind integriert:

[diagram]
[suggest]

Die `[diagram]` -Direktive

Sowohl Benutzer als auch Entwickler finden es möglicherweise hilfreich, um zu sehen, wie eine App eine bestimmte Eingabe interpretiert. Eines der Standardfeatures einer System.CommandLine App ist die [diagram] Direktive, mit der Sie das Ergebnis der Analyse von Befehlseingaben in der Vorschau anzeigen können. Beispiel:

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

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

Im vorherigen Beispiel:

Der Befehl (myapp), die untergeordneten Optionen und die Argumente für diese Optionen werden mit eckigen Klammern gruppiert.
Für das Optionsergebnis [ --delay !<not-an-int> ]gibt dies ! einen Analysefehler an. Der Wert not-an-int für eine int Option kann nicht auf den erwarteten Typ analysiert werden. Der Fehler wird auch durch ! vor dem Befehl gekennzeichnet, der die fehlerhafte Option enthält: ![ myapp....
Für das Optionsergebnis *[ --fgcolor <White> ]wurde die Option in der Befehlszeile nicht angegeben, sodass der konfigurierte Standardwert verwendet wurde. White ist der effektive Wert für diese Option. Das Sternchen gibt an, dass der Wert der Standardwert ist.
???--> verweist auf Eingaben, die nicht mit den Befehlen oder Optionen der App übereinstimmen.

Direktive vorschlagen

Mit der [suggest] Direktive können Sie nach Befehlen suchen, wenn Sie den genauen Befehl nicht kennen.

dotnet [suggest] buil

build
build-server
msbuild

Freigeben über