Freigeben über

Entwurfsleitfäden

Die folgenden Abschnitte enthalten Empfehlungen, die wir Ihnen beim Entwerfen einer CLI ans Herz legen. Stellen Sie sich das, was Ihre App in der Befehlszeile erwartet, ähnlich vor wie das, was ein REST-API-Server in der URL erwartet. Einheitliche Regeln für REST-APIs machen sie für Client-App-Entwickler leicht nutzbar. Auf die gleiche Weise haben Benutzer Ihrer Befehlszeilen-Apps eine bessere Erfahrung, wenn das CLI-Design gängigen Mustern folgt.

Nachdem Sie eine CLI erstellt haben, ist es schwierig zu ändern, insbesondere, wenn Ihre Benutzer Ihre CLI in Skripts verwendet haben, die 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, wo wir dies tun können, ohne unterbrechungsbehaftete Änderungen einzuführen. Ein Beispiel für diese Arbeit ist der neue Entwurf für dotnet new in .NET 7.

Symbole

Befehle und Unterbefehle

Wenn ein Befehl Unterbefehle enthält, sollte der Befehl als Bereich oder Gruppierungsbezeichner für die Unterbefehle funktionieren, anstatt eine Aktion anzugeben. Wenn Sie die App aufrufen, geben Sie den Gruppierungsbefehl und einen seiner Unterbefehle an. Versuchen Sie beispielsweise, dotnet tool auszuführen, und Sie erhalten eine Fehlermeldung, da der tool Befehl nur eine Gruppe toolbezogener Unterbefehle identifiziert, wie z. B. install und list. Sie können ausführen dotnet tool install, aber dotnet tool selbst 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. Beispielsweise ist in der .NET CLI der implizite Bereich das Projekt, und in der Docker CLI ist es das Image. Daher können Sie ohne Einschließen eines Bereichs verwenden dotnet build . Überlegen Sie, ob Ihre CLI über einen impliziten Bereich verfügt. Wenn dies der Fall ist, überlegen Sie, ob der Benutzer es optional einschließen oder weglassen soll, wie in docker build und docker image build. Wenn Sie optional zulassen, dass der implizite Bereich von Ihrem Benutzer eingegeben wird, verfügen Sie auch automatisch über Hilfe und Registerkartenabschluss für diese Gruppierung von Befehlen. Geben Sie die optionale Verwendung der impliziten Gruppe an, indem Sie zwei Befehle definieren, die denselben Vorgang ausführen.

Optionen als Parameter

Optionen sollten Parameter für Befehle bereitstellen, anstatt Aktionen selbst anzugeben. Dies ist ein empfohlenes Designprinzip, obwohl es nicht immer folgt System.CommandLine (--help zeigt Hilfeinformationen an).

Benennung

Kurzformaliase

Im Allgemeinen wird empfohlen, die Anzahl der von Ihnen definierten Aliase für Kurzformoptionen zu minimieren.

Vermeiden Sie insbesondere die Verwendung eines der folgenden Aliase anders als in der üblichen Verwendung in der .NET CLI und anderen .NET-Befehlszeilenanwendungen.

  • -i für --interactive.

    Diese Option signalisiert dem Benutzer, dass er möglicherweise zur Eingabe von Antworten auf Fragen aufgefordert wird, die der Befehl benötigt. Sie werden z. B. zur Eingabe eines Benutzernamens aufgefordert. Ihre CLI kann in Skripts verwendet werden. Verwenden Sie daher Vorsicht bei der Aufforderung von Benutzern, die diese Option nicht angegeben haben.

  • -o für --output.

    Einige Befehle erzeugen Dateien als Ergebnis ihrer Ausführung. Diese Option sollte verwendet werden, um zu ermitteln, wo sich diese Dateien befinden 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 häufig Ausgabe für den Benutzer auf der Konsole bereit; Diese Option wird verwendet, um die Ausgabemenge anzugeben, die der Benutzer anfordert. Weitere Informationen finden Sie weiter unten in diesem Artikel unter der --verbosity Option .

Es gibt auch einige Aliase mit allgemeiner Verwendung, die auf die .NET CLI beschränkt ist. Sie können diese Aliase für andere Optionen in Ihren Apps verwenden, beachten Sie jedoch die Möglichkeit von Verwirrung.

  • -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 eines dieser Namen. Diese Einstellung wird häufig verwendet, um andere Eigenschaften auf eine Weise zu konfigurieren, die für diese Konfiguration sinnvoll ist, 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 häufig auf irgendeine Weise anpassen. Mit dieser Option können MSBuild-Eigenschaften in der Befehlszeile bereitgestellt und an den zugrunde liegenden MSBuild-Aufruf übergeben werden. Wenn Ihre App MSBuild nicht verwendet, aber eine Reihe von Schlüssel-Wert-Paaren benötigt, sollten Sie diesen Optionsnamen verwenden, um die Erwartungen der Benutzer zu nutzen.

  • -r für --runtime

    Wenn Ihre Anwendung auf verschiedenen Laufzeiten ausgeführt werden kann oder über laufzeitspezifische Logik verfügt, sollten Sie diese Option als Möglichkeit zum Angeben eines Laufzeitbezeichners unterstützen. Wenn Ihre App unterstützt --runtimewird, sollten Sie die Unterstützung und --arch auch die Unterstützung --os in Betracht ziehen. Mit diesen Optionen können Sie nur das Betriebssystem oder die Architekturteile des RID angeben, sodass der Teil nicht angegeben wird, der von der aktuellen Plattform bestimmt werden soll. Weitere Informationen finden Sie unter dotnet publish.

Kurze Namen

Erstellen Sie Namen für Befehle, Optionen und Argumente so kurz und einfach wie möglich. Wenn beispielsweise class klar genug ist, machen Sie den Befehl classificationnicht.

Namen in Kleinbuchstaben

Definieren Sie Namen nur in Kleinbuchstaben, es sei denn, Sie können Großbuchstaben aliase erstellen, um Befehle oder Optionen ohne Groß-/Kleinschreibung zu berücksichtigen.

Kebab Case-Namen

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

Pluralisierung

In einer App sollte die Pluralisierung konsistent sein. 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 Nomen

Verwenden Sie Verben anstelle von Substantiven für Befehle, die auf Aktionen verweisen (die ohne Unterbefehle darunter), z. B.: dotnet workload remove, nicht dotnet workload removal. Und verwenden Sie Nomen anstelle von Verben für Optionen, z. B.: --configuration, nicht --configure.

Die --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 vorhandene Apps verwenden Silent manchmal anstelle von Quiet, und Trace, Debugoder Verbose anstelle von Diagnostic.

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

  • Ruhig
  • Normal
  • Diagnostik

Wenn eine App keine fünf verschiedenen Ebenen benötigt, sollte die Option weiterhin die gleichen fünf Einstellungen definieren. In diesem Fall werden Minimal und Normal dieselbe Ausgabe erzeugen, und Detailed und Diagnostic werden ebenfalls gleich sein. 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 Aktionen ausführen:

  • Die Anzeige fordert zur Eingabe auf, wenn --interactive angegeben wird, auch wenn --verbosity entsprechend Quiet ist.
  • Die Verwendung von --verbosity Quiet und --interactive zusammen verbieten.

Andernfalls wartet die App auf die Eingabe, ohne dem Benutzer mitzuteilen, worauf er wartet. Es wird angezeigt, dass Ihre Anwendung eingefroren ist, und der Benutzer hat keine Vorstellung davon, dass die Anwendung auf die Eingabe wartet.

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

Die Konventionen .NET CLI und POSIX

Die .NET CLI folgt nicht konsistent allen 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 Token, die auf -- folgen, an die App übergeben, die vom Befehl ausgeführt wird. Beispiel:

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

In diesem Beispiel wird die --project Option an den dotnet run Befehl übergeben, und die --message Option mit seinem Argument wird bei der Ausführung als Befehlszeilenoption an myapp übergeben.

Das -- Token ist nicht immer erforderlich, um Optionen an eine App zu übergeben, die Sie mit 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. Daher sind die folgenden Befehlszeilen gleichwertig, weil 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 den Optionsnamen zu wiederholen

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 zum gleichen Verhalten, unabhängig davon, ob Sie false oder true übergeben. Dieses Verhalten ergibt sich, wenn .NET CLI-Code, der die Option implementiert, nur auf das Vorhandensein oder Fehlen der Option überprüft, wobei der Wert ignoriert wird. Ein Beispiel ist --no-restore für den dotnet build-Befehl. Geben Sie --no-restore false ein, und der Wiederherstellungsvorgang wird übersprungen, genauso wie wenn Sie --no-restore true oder --no-restore angeben.

Kebab Case

In einigen Fällen verwendet die .NET CLI nicht den Kebab Case für Befehls-, Options- oder Argumentnamen. Beispielsweise gibt es eine Option in der .NET CLI, die --additionalprobingpath anstelle von --additional-probing-path genannt wird.

Siehe auch