Übersicht über die Befehlszeilensyntax für System.CommandLine

Artikel
06/26/2023

Wichtig

System.CommandLine befindet sich derzeit in der VORSCHAU, und diese Dokumentation gilt für Version 2.0 Beta 4. Einige Informationen beziehen sich auf Vorabversionen des Produkts, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

In diesem Artikel wird die Befehlszeilensyntax erläutert, die von System.CommandLine erkannt wird. 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, die durch Leerzeichen getrennte Zeichenfolgen sind. Nehmen wir z. B. die folgende Befehlszeile:

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

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

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:

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

Ein Token kann Leerzeichen enthalten, wenn es in Anführungszeichen eingeschlossen ist ("). Hier sehen Sie 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. Zum Beispiel:

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

Stammbefehle

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

Unterbefehle

Die meisten Apps für die Befehlszeile unterstützen Unterbefehle, auch bekannt als Verben. Der dotnet-Befehl hat z. B. einen Unterbefehl run, den Sie durch Eingabe von dotnet run aufrufen.

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

Optionen

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

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

Wie dieses Beispiel zeigt, kann der Wert der Option explizit (quiet für --verbosity) oder implizit (nichts folgt auf --global) sein. Optionen, für die kein Wert angegeben ist, sind in der Regel boolesche Parameter, die standardmäßig true lauten, 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. Zum 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.

Argumente

Ein Argument ist ein Wert, der an eine Option oder einen Befehl übergeben wird. Die folgenden Beispiele zeigen ein Argument für die Option verbosity und ein Argument für den Befehl build.

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

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

Argumente können Standardwerte aufweisen, die angewendet werden, wenn kein Argument explizit angegeben wird. Viele Optionen sind beispielsweise implizit boolesche Parameter mit einem Standardwert von 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
                                  ^-----------^

Für einige Optionen sind Argumente erforderlich. In der .NET CLI erfordert --output z. B. ein Argument für den Ordnernamen. Wenn das Argument nicht angegeben wird, tritt bei dem Befehl ein Fehler auf.

Argumente können erwartete Typen aufweisen, und System.CommandLine zeigt eine Fehlermeldung an, wenn ein Argument nicht in den erwarteten Typ analysiert werden kann. Beispielsweise ist der folgende Befehl fehlerhaft, da „silent“ nicht zu den gültigen Werten für --verbosity gehört:

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

Argumente haben auch Erwartungen dahingehend, wie viele Werte bereitgestellt werden können. Beispiele finden Sie im Abschnitt zur Argumentarität.

Reihenfolge der Optionen und Argumente

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

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

Die 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 es mehrere Argumente gibt, spielt die Reihenfolge eine Rolle. Die folgenden Befehle sind nicht unbedingt gleichwertig:

myapp argument1 argument2
myapp argument2 argument1

Diese Befehle übergeben eine Liste mit denselben Werten an den Befehlshandlercode, unterscheiden sich aber in der Reihenfolge der Werte, was zu unterschiedlichen Ergebnissen führen kann.

Aliase

Sowohl unter POSIX als auch unter Windows ist es üblich, dass einige Befehle und Optionen Aliase haben. Dies sind in der Regel Kurzformen, die leichter einzugeben sind. Aliase können auch für andere Zwecke verwendet werden, z. B. um die nicht Beachtung der Groß-/Kleinschreibung zu simulieren und um alternative Schreibweisen eines Worts zu unterstützen.

POSIX-Kurzformen haben in der Regel einen einzelnen führenden Bindestrich, 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 Befehls oder Optionsnamens in der langen Form eingeben und er wird akzeptiert. Durch dieses Verhalten würden die folgenden Befehlszeilen gleichwertig werden:

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.

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 die 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. Beispielsweise verhält sich git clean -X anders als git clean -x. Die .NET CLI verwendet die Kleinschreibung.

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 Doppelstrichtoken (--) als Escapemechanismus. Alles, was auf das Doppelstrichtoken folgt, wird als Argument für den Befehl interpretiert. Diese Funktion kann verwendet werden, um Argumente zu übermitteln, die wie Optionen aussehen, da sie verhindert, dass sie als Optionen interpretiert werden.

Angenommen, myapp übernimmt ein message-Argument und Sie möchten, dass der Wert von message entsprechend --interactive ist. Die folgende Befehlszeile kann zu unerwarteten Ergebnissen führen.

myapp --interactive

Wenn myapp keine --interactive-Option hat, wird das --interactive-Token als Argument interpretiert. Wenn die App jedoch eine --interactive-Option aufweist, 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 es Ihnen, ein Leerzeichen, „=“ oder „:“ als Trennzeichen zwischen einem Optionsnamen und seinem 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 Optionsalias angeben, der aus einem einzelnen Zeichen besteht. Die folgenden Befehle sind z. B. gleichwertig:

myapp -vquiet
myapp -v quiet

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

Argumentarität

Die Arität oder „Stelligkeit“ eines Options- oder Befehlsarguments ist die Anzahl der Werte, die übergeben werden können, wenn diese Option oder dieser Befehl angegeben ist.

Die Arität wird durch einen Mindest- und einen Höchstwert ausgedrückt, wie die folgende Tabelle veranschaulicht:

Min	Max	Beispiel: Gültigkeit	Beispiel
0	0	Gültig:	--file
		Ungültig:	--file a.json
		Ungültig:	--file a.json --file b.json
0	1	Gültig:	--flag
		Gültig:	--flag true
		Gültig:	--flag false
		Ungültig:	--flag false --flag false
1	1	Gültig:	--file a.json
		Ungültig:	--file
		Ungültig:	--file a.json --file b.json
0	n	Gültig:	--file
		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:	--file

System.CommandLine hat eine ArgumentArity-Struktur zur Definition der Arität mit den folgenden Werten:

Zero – Keine Werte zulässig.
ZeroOrOne – Kann einen Wert haben, kann keine Werte haben.
ExactlyOne – Muss einen Wert haben.
ZeroOrMore – Kann einen Wert, mehrere Werte oder keine Werte haben.
OneOrMore – Kann mehrere Werte haben, muss aber mindestens einen Wert haben.

Ein Rückschluss auf die Arität ist häufig über den Typ möglich. Beispielsweise hat eine int-Option die Arität ExactlyOne und eine List<int>-Option die Arität OneOrMore aufweisen.

Außerkraftsetzung von Optionen

Wenn der Höchstwert für die Arität 1 ist, kann System.CommandLine trotzdem so konfiguriert werden, dass es mehrere Instanzen einer Option akzeptiert. In diesem Fall überschreibt die letzte Instanz einer wiederholten Option alle früheren Instanzen. Im folgenden Beispiel würde der Wert 2 an den myapp-Befehl übergeben werden.

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

Mehrere Argumente

Wenn der Höchstwert für die Arität mehr als eins beträgt, kann System.CommandLine so konfiguriert werden, dass mehrere Argumente für eine Option akzeptiert werden, ohne den Optionsnamen zu wiederholen.

Im folgenden Beispiel würde die an den Befehl myapp übergebene Liste „a“, „b“, „c“ und „d“ enthalten:

myapp --list a b c --list d

Bündeln von Optionen

POSIX empfiehlt, dass Sie die Bündelung von Optionen unterstützen, die ein einzelnes Zeichen umfassen, auch bekannt als Stapelung. 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 Optionsbündel angegeben 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 -c gelten.

Boolesche Optionen (Flags)

Wenn true oder false für eine Option mit einem bool-Argument übergeben wird, erfolgt die Analyse erwartungsgemäß. Aber eine Option, deren Argumenttyp bool ist, erfordert normalerweise keine Angabe eines Arguments. Boolesche Optionen, die manchmal auch als „Flags“ bezeichnet werden, haben in der Regel eine Arität von ZeroOrOne. Das Vorhandensein des Optionsnamens in der Befehlszeile, ohne dass ein Argument folgt, führt zu dem Standardwert true. Das Fehlen des Optionsnamens in der Befehlszeileneingabe führt zu einem Wert von false. Wenn der Befehl myapp den Wert einer booleschen Option namens --interactive ausgibt, erstellt die folgende Eingabe die folgende Ausgabe:

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

False
True
False
True

--help-Option

Apps für die Befehlszeile bieten in der Regel eine Option zur Anzeige einer kurzen Beschreibung der verfügbaren Befehle, Optionen und Argumente. System.CommandLine generiert automatisch eine Hilfeausgabe. Zum Beispiel:

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.

Benutzer von Apps sind möglicherweise daran gewöhnt, auf verschiedenen Plattformen auf unterschiedliche Weise Hilfe anzufordern, sodass in der System.CommandLine erstellte Apps auf viele Arten der Anforderung von Hilfe reagieren. Die folgenden Befehle sind alle gleichwertig:

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

In der Hilfeausgabe werden nicht unbedingt alle verfügbaren Befehle, Argumente und Optionen angezeigt. Einige von ihnen können ausgeblendet sein, d. h. sie werden nicht in der Hilfeausgabe angezeigt, können aber in der Befehlszeile angegeben werden.

--version-Option

Apps, die für die System.CommandLine erstellt wurden, liefern die Versionsnummer automatisch als Antwort auf die --version-Option, die mithilfe des root-Befehls verwendet wird. Zum Beispiel:

dotnet --version

6.0.100

MSBuild-Antwortdateien

Eine Antwortdatei ist eine Datei, die eine Reihe von Token für eine Befehlszeilen-App enthält. Antwortdateien sind ein Feature der System.CommandLine, das in zwei Szenarien nützlich ist:

Zum Aufrufen einer App in der Befehlszeile durch Angabe einer Eingabe, die länger ist als das Zeichenlimit des Terminals.
Zum wiederholten Aufrufen desselben Befehls, ohne die gesamte Zeile erneut einzugeben.

Um eine Antwortdatei zu verwenden, geben Sie den Dateinamen mit einem vorangestellten @-Zeichen an der Stelle in der Zeile ein, an der Sie Befehle, Optionen und Argumente einfügen möchten. Die RSP-Dateierweiterung ist eine gängige Konvention, aber Sie können jede beliebige Dateierweiterung verwenden.

Die nachfolgenden Zeilen sind identisch:

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 finden Sie Syntaxregeln, die bestimmen, wie der Text in einer Antwortdatei interpretiert wird:

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

Anweisungen

System.CommandLine führt ein syntaktisches Element namens Direktive ein. Die [parse]-Direktive ist ein Beispiel dafür. Wenn Sie [parse] nach dem Namen der App einfügen, zeigt System.CommandLine ein Diagramm des Analyseergebnisses an, anstatt die Befehlszeilen-App aufzurufen:

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

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

Der Zweck von Direktiven ist es, übergreifende Funktionen bereitzustellen, die in allen Befehlszeilen-Apps angewendet werden können. Da sich die Direktiven syntaktisch von der eigenen Syntax der App unterscheiden, können sie Funktionen bereitstellen, die App-übergreifend gelten.

Eine Direktive muss den folgenden Syntaxregeln entsprechen:

Es ist ein Token in der Befehlszeile, das hinter dem Namen der App, aber vor allen Unterbefehlen oder Optionen steht.
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, das durch einen Doppelpunkt vom Direktivennamen getrennt ist.

Die folgenden Direktiven sind integriert:

[parse]
[suggest]

Die `[parse]` -Direktive

Sowohl Benutzer als auch Entwickler können es nützlich finden, zu sehen, wie eine App eine bestimmte Eingabe interpretiert. Eines der standardmäßigen Features einer System.CommandLine-App ist die [parse]-Direktive, mit der Sie das Ergebnis der Analyse der Befehlseingabe in der Vorschau anzeigen können. Beispiel:

myapp [parse] --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), seine untergeordneten Optionen und die Argumente für diese Optionen werden mithilfe von eckigen Klammern gruppiert.
Für das Optionsergebnis [ --delay !<not-an-int> ] zeigt ! 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 nicht in der Befehlszeile angegeben, sodass der konfigurierte Standardwert verwendet wurde. White ist der effektive Wert für diese Option. Das Sternchen zeigt an, dass der Wert der Standardwert ist.
???--> verweist auf eine Eingabe, die nicht mit einem der Befehle oder einer der Optionen der App übereinstimmt.

Die `[suggest]` -Direktive

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

dotnet [suggest] buil

build
build-server
msbuild

Entwurfsleitfäden

In den folgenden Abschnitten finden Sie Hinweise, die Sie beim Entwurf einer CLI beachten sollten. Stellen Sie sich das, was Ihre App in der Befehlszeile erwartet, ähnlich vor wie das, was ein REST-API-Server in der URL erwartet. Konsistente Regeln für REST-APIs machen diese für die Entwickler von Client-Apps leicht nutzbar. Genauso werden die Benutzer Ihrer Befehlszeilen-Apps eine bessere Erfahrung haben, wenn der CLI-Entwurf gemeinsamen Mustern folgt.

Wenn Sie einmal eine CLI erstellt haben, ist es schwer zu ändern, insbesondere wenn Ihre Benutzer Ihre CLI in Skripts verwendet haben, von denen sie erwarten, dass sie weiterhin ausgeführt werden. Die hier aufgeführten Richtlinien wurden nach der .NET CLI entwickelt und folgen nicht immer diesen Richtlinien. Wir aktualisieren die .NET CLI dort, wo es möglich ist, ohne Breaking Changes vorzunehmen. Ein Beispiel für diese Arbeit ist der neue Entwurf für dotnet new in .NET 7.

Befehle und Unterbefehle

Wenn ein Befehl Unterbefehle aufweist, sollte der Befehl als Bereich oder als Gruppierungsbezeichner für die Unterbefehle fungieren, anstatt eine Aktion anzugeben. Wenn Sie die App aufrufen, geben Sie den Gruppierungsbefehl und einen seiner Unterbefehle an. Wenn Sie z. B. versuchen, dotnet tool auszuführen, erhalten Sie eine Fehlermeldung, da der Befehl tool nur eine Gruppe von toolbezogenen Unterbefehlen identifiziert, z. B. install und list. Sie können dotnet tool install ausführen, aber dotnet tool allein wäre unvollständig.

Eine der Möglichkeiten zum Definieren von Bereichen hilft Ihren Benutzern dabei, die Hilfeausgabe zu organisieren.

Innerhalb einer CLI gibt es häufig einen impliziten Bereich. In der .NET CLI ist der implizite Bereich z. B. das Projekt und in der Docker-CLI das Image. Folglich können Sie dotnet build verwenden, ohne einen Bereich einzuschließen. Überlegen Sie, ob Ihre CLI über einen impliziten Bereich verfügt. Wenn dies der Fall ist, sollten Sie überlegen, ob Sie dem Benutzer die Möglichkeit geben, sie optional einzuschließen oder wegzulassen, wie in docker build und docker image build. Wenn Sie optional zulassen, dass der implizite Bereich von Ihrem Benutzer typisiert wird, verfügen Sie auch automatisch über Hilfe und Vervollständigung mit der TAB-TASTE für diese Gruppierung von Befehlen. Stellen Sie die optionale Verwendung der impliziten Gruppe bereit, indem Sie zwei Befehle definieren, die denselben Vorgang ausführen.

Optionen als Parameter

Optionen sollten Parameter für Befehle bereitstellen, anstatt selbst Aktionen anzugeben. Dies ist ein empfohlenes Entwurfsprinzip, auch wenn es nicht immer von System.CommandLine befolgt wird (--help zeigt Hilfeinformationen an).

Kurzformaliase

Im Allgemeinen empfehlen wir Ihnen, die Anzahl der von Ihnen definierten Kurzformaliase für Optionen zu minimieren.

Vermeiden Sie es insbesondere, einen der folgenden Aliase anders zu verwenden, als es in der .NET CLI und anderen .NET-Befehlszeilen-Apps üblich ist:

-i für --interactive.

Diese Option signalisiert dem Benutzer, dass er möglicherweise aufgefordert wird, Eingaben auf Fragen vorzunehmen, die für den Befehl beantwortet werden müssen. Beispielsweise die Aufforderung zur Eingabe eines Benutzernamens. Ihre CLI kann in Skripts verwendet werden. Seien Sie daher vorsichtig, wenn Sie Benutzer auffordern, die diesen Schalter nicht angegeben haben.
-o für --output.

Einige Befehle erzeugen Dateien als Ergebnis ihrer Ausführung. Verwenden Sie diese Option, um zu bestimmen, wo diese Dateien gespeichert werden sollen. In Fällen, in denen eine einzelne Datei erstellt wird, sollte diese Option ein Dateipfad sein. In Fällen, in denen viele Dateien erstellt werden, sollte diese Option ein Verzeichnispfad sein.
-v für --verbosity.

Befehle stellen dem Benutzer häufig eine Ausgabe auf der Konsole bereit. Diese Option wird verwendet, um die Menge der vom Benutzer angeforderten Ausgabe festzulegen. Weitere Informationen finden Sie unter --verbosity-Option weiter unten in diesem Artikel.

Es gibt auch einige Aliase, deren allgemeine Verwendung auf die .NET CLI beschränkt ist. Sie können diese Aliase für andere Optionen in Ihren Apps verwenden, aber seien Sie sich der Möglichkeit von Verwechslungen bewusst.

-c für --configuration

Diese Option bezieht sich oft auf eine benannte Buildkonfiguration wie Debug oder Release. Sie können einen beliebigen Namen für eine Konfiguration verwenden, aber die meisten Tools erwarten einen dieser Namen. Diese Einstellung wird häufig verwendet, um andere Eigenschaften so zu konfigurieren, dass sie für diese Konfiguration sinnvoll sind – z. B. weniger Codeoptimierung beim Erstellen der Debug-Konfiguration. Ziehen Sie diese Option in Betracht, wenn Ihr Befehl über unterschiedliche Betriebsmodi verfügt.
-f für --framework

Diese Option wird verwendet, um einen einzelnen Zielframeworkmoniker (Target Framework Moniker, TFM) für die Ausführung auszuwählen, sodass Sie dieses Flag unterstützen sollten, wenn Ihre CLI-Anwendung je nach ausgewähltem TFM ein unterschiedliches Verhalten aufweist.
-p für --property

Wenn Ihre Anwendung schließlich MSBuild aufruft, muss der Benutzer diesen Aufruf oft in irgendeiner Weise anpassen. Mit dieser Option können MSBuild-Eigenschaften in der Befehlszeile angegeben und an den zugrunde liegenden MSBuild-Aufruf weitergegeben werden. Wenn Ihre App MSBuild nicht verwendet, aber eine Reihe von Schlüssel-Wert-Paaren benötigt, sollten Sie denselben Optionsnamen verwenden, um die Erwartungen der Benutzer zu erfüllen.
-r für --runtime

Wenn Ihre Anwendung unter verschiedenen Runtimes ausgeführt werden kann oder eine Runtime-spezifische Logik aufweist, sollten Sie diese Option als Möglichkeit zur Angabe eines Runtimebezeichners unterstützen. Wenn Ihre App --runtime unterstützt, sollten Sie auch --os und --arch unterstützen. Mit diesen Optionen können Sie nur die Teile des Betriebssystems oder der Architektur des RIDs angeben, wobei der nicht angegebene Teil von der aktuellen Plattform bestimmt wird. Weitere Informationen finden Sie unter dotnet publish.

Kurze Namen

Sorgen Sie dafür, dass die Namen für Befehle, Optionen und Argumente so kurz wie möglich werden und möglichst leicht zu buchstabieren sind. Wenn z. B. class eindeutig genug ist, machen Sie den Befehl nicht zu classification.

Namen in Kleinbuchstaben

Definieren Sie Namen nur in Kleinbuchstaben. Sie können jedoch Aliase in Großbuchstaben erstellen, damit die Groß-/Kleinschreibung für Befehle oder Optionen nicht beachtet werden muss.

Kebab Case-Namen

Verwenden Sie die Kebab Case-Variante, um Wörter zu unterscheiden. Beispiel: --additional-probing-path.

Pluralisierung

Achten Sie innerhalb einer App auf eine einheitliche Pluralisierung. Mischen Sie z. B. keine Plural- und Singularnamen für Optionen, die mehrere Werte besitzen können (maximale Arität größer als eins):

Optionsnamen	Konsistenz
`--additional-probing-paths` und `--sources`	✔️
`--additional-probing-path` und `--source`	✔️
`--additional-probing-paths` und `--source`	❌
`--additional-probing-path` und `--sources`	❌

Verben im Vergleich zu Substantiven

Verwenden Sie Verben anstelle von Substantiven für Befehle, die sich auf Aktionen beziehen (ohne untergeordnete Unterbefehle), z. B: dotnet workload remove, nicht dotnet workload removal. Und verwenden Sie für Optionen z. B. eher Substantive als Verben: --configuration, nicht --configure.

`--verbosity`-Option

System.CommandLine-Anwendungen bieten in der Regel eine --verbosity-Option, die angibt, wie umfangreich die an die Konsole gesendete Ausgabe wird. Hier sind die fünf Standardeinstellungen:

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

Dies sind die Standardnamen, aber bestehende Apps verwenden manchmal Silent anstelle von Quiet und Trace, Debug oder Verbose anstelle von Diagnostic.

Jede App definiert ihre eigenen Kriterien, die bestimmen, was auf jeder Ebene angezeigt wird. In der Regel benötigt eine App nur drei Ebenen:

Quiet
Normal
Diagnose

Wenn eine App nicht fünf verschiedene Ebenen benötigt, sollte die Option dennoch die gleichen fünf Einstellungen definieren. In diesem Fall erzeugen Minimal und Normal die gleiche Ausgabe, und Detailed und Diagnostic sind ebenfalls gleich. So können Ihre Benutzer einfach das eingeben, womit sie vertraut sind, und es wird die beste Lösung verwendet.

Die Erwartung für Quiet ist, dass keine Ausgabe auf der Konsole angezeigt wird. Wenn eine App jedoch einen interaktiven Modus bietet, sollte die App eine der folgenden Alternativen bereitstellen:

Die Anzeige fordert zur Eingabe auf, wenn --interactive angegeben wird, auch wenn --verbosity entsprechend Quiet ist.
Verbieten Sie die gemeinsame Verwendung von --verbosity Quiet und --interactive.

Andernfalls wartet die App auf Eingaben, ohne dem Benutzer mitzuteilen, worauf sie wartet. Es wird den Anschein erwecken, als sei Ihre Anwendung eingefroren und der Benutzer hat keine Ahnung, dass die Anwendung auf eine Eingabe wartet.

Wenn Sie Aliasnamen definieren, verwenden Sie -v für --verbosity und machen -v ohne Argument zu einem Alias für --verbosity Diagnostic. Verwenden Sie -q für --verbosity Quiet.

.NET CLI und POSIX-Konventionen

Die .NET CLI hält sich nicht konsequent an alle POSIX-Konventionen.

Doppelter Bindestrich

Mehrere Befehle in der .NET CLI weisen eine spezielle Implementierung des Doppelstrichtokens auf. Im Falle von dotnet run, dotnet watch und dotnet tool run werden die Token, die auf -- folgen, an die App übergeben, die vom Befehl ausgeführt wird. Zum Beispiel:

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

In diesem Beispiel wird die Option --project an den Befehl dotnet run übergeben, und die Option --message mit ihrem Argument wird als Befehlszeilenoption an myapp übergeben, wenn sie ausgeführt wird.

Das ---Token ist nicht immer erforderlich, um Optionen an eine App zu übergeben, die Sie mithilfe von dotnet run ausführen. Ohne den doppelten Bindestrich gibt der Befehl dotnet run automatisch alle Optionen an die auszuführende App weiter, die nicht als für dotnet run selbst oder für MSBuild zutreffend erkannt werden. Die folgenden Befehlszeilen sind also gleichwertig, da dotnet run die Argumente und Optionen nicht erkennt:

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

Weglassen des Option-zu-Argument-Trennzeichens

Die .NET CLI unterstützt nicht die POSIX-Konvention, die es Ihnen gestattet, das Trennzeichen wegzulassen, wenn Sie einen Optionsalias angeben, der aus einem Zeichen besteht.

Mehrere Argumente ohne Wiederholung des Optionsnamens

Die .NET CLI akzeptiert nicht mehrere Argumente für eine Option, ohne den Optionsnamen zu wiederholen.

Boolesche Optionen

In der .NET CLI führen einige boolesche Optionen zu demselben Verhalten, wenn Sie false übergeben, wie wenn Sie true übergeben. Dieses Verhalten tritt auf, wenn der .NET CLI-Code, der die Option implementiert, nur auf das Vorhandensein oder Fehlen der Option prüft und den Wert ignoriert. Ein Beispiel ist --no-restore für den Befehl dotnet build. Wenn Sie no-restore false eingeben, wird der Wiederherstellungsvorgang genauso übersprungen wie bei der Angabe von no-restore true oder no-restore.

Kebab Case

In einigen Fällen verwendet die .NET CLI nicht den Kebab Case für Befehls-, Options- oder Argumentnamen. Beispielsweise gibt es eine .NET CLI-Option, die --additionalprobingpath statt --additional-probing-path heißt.

Freigeben über