Udostępnij za pośrednictwem

Wskazówki projektowe

W poniższych sekcjach przedstawiono wskazówki, które zalecamy stosować podczas projektowania interfejsu wiersza polecenia. Pomyśl o tym, czego twoja aplikacja oczekuje w wierszu polecenia, jako o czymś podobnym do tego, czego serwer API REST oczekuje w adresie URL. Spójne reguły dla interfejsów API REST są tym, co sprawia, że są łatwo dostępne dla deweloperów aplikacji klienckich. W ten sam sposób użytkownicy aplikacji wiersza polecenia będą mieli lepsze wrażenia, jeśli projekt interfejsu wiersza polecenia będzie zgodny z typowymi wzorcami.

Po utworzeniu interfejsu wiersza polecenia trudno go zmienić, zwłaszcza jeśli użytkownicy używali go w skryptach, które oczekują, że będą nadal działać. Wytyczne te zostały opracowane po interfejsie wiersza polecenia platformy .NET i nie zawsze są zgodne z tymi wytycznymi. Aktualizujemy interfejs CLI .NET, gdzie możemy to zrobić bez wprowadzania zmian powodujących niekompatybilność. Przykładem tej pracy jest nowy projekt dla dotnet new platformy .NET 7.

Symbole

Polecenia i polecenia podrzędne

Jeśli polecenie ma polecenia podrzędne, polecenie powinno działać jako obszar lub identyfikator grupowania dla podpolecenia, zamiast określać akcję. Podczas wywoływania aplikacji należy określić polecenie grupowania i jedno z jego podpolecenia. Na przykład spróbuj uruchomić dotnet toolpolecenie i zostanie wyświetlony komunikat o błędzie, ponieważ tool polecenie identyfikuje tylko grupę poleceń podrzędnych związanych z narzędziem, takich jak install i list. Można uruchomić dotnet tool install, ale samo dotnet tool byłoby niekompletne.

Jednym ze sposobów, w jaki definiowanie obszarów pomaga użytkownikom, jest organizowanie wyników pomocy.

W interfejsie wiersza polecenia często występuje niejawny obszar. Na przykład w interfejsie wiersza polecenia platformy .NET niejawny obszar to projekt, a w interfejsie wiersza polecenia platformy Docker jest to obraz. W związku z tym można używać dotnet build bez uwzględniania obszaru. Zastanów się, czy CLI ma niejawny obszar. Jeśli tak, rozważ, czy zezwolić użytkownikowi na opcjonalne dołączanie lub pomijanie go, jak w docker build i docker image build. Jeśli opcjonalnie pozwolisz użytkownikowi wpisywać polecenia w domyślny obszar, automatycznie zyskasz również pomoc i możliwość uzupełniania poleceń za pomocą klawisza Tab w tym grupowaniu. Podaj opcjonalne użycie niejawnej grupy, definiując dwa polecenia, które wykonują tę samą operację.

Opcje jako parametry

Opcje powinny dostarczać parametry poleceń, a nie samemu określać akcje. Jest to zalecana zasada projektowania, chociaż nie zawsze następuje System.CommandLine po niej (--help wyświetla informacje pomocy).

Nazewnictwo

Krótkie aliasy

Ogólnie rzecz biorąc, zalecamy zminimalizowanie liczby zdefiniowanych aliasów dla krótkich opcji.

W szczególności należy unikać używania dowolnego z następujących aliasów inaczej niż ich typowe użycie w interfejsie wiersza polecenia platformy .NET i innych aplikacjach wiersza polecenia platformy .NET:

  • -i dla --interactive.

    Ta opcja sygnalizuje użytkownikowi, że może zostać wyświetlony monit o podanie danych wejściowych do pytań, na które musi odpowiedzieć polecenie. Na przykład monitowanie o nazwę użytkownika. Interfejs wiersza polecenia może być używany w skryptach, dlatego należy zachować ostrożność przy powiadamianiu użytkowników, którzy nie określili tego przełącznika.

  • -o dla --output.

    Niektóre polecenia generują pliki w wyniku ich wykonania. Ta opcja powinna służyć do określania lokalizacji tych plików. W przypadku utworzenia pojedynczego pliku ta opcja powinna być ścieżką pliku. W przypadkach, w których jest tworzonych wiele plików, ta opcja powinna być ścieżką katalogu.

  • -v dla --verbosity.

    Polecenia często udostępniają użytkownikowi dane wyjściowe na konsoli; opcja ta służy do określania ilości danych wyjściowych, które użytkownik żąda. Aby uzyskać więcej informacji, zobacz --verbosity opcję w dalszej części tego artykułu.

Istnieją również aliasy z typowym użyciem ograniczonym do .NET CLI. Te aliasy można używać do innych opcji w aplikacjach, ale należy pamiętać o możliwości pomyłek.

  • -c dla --configuration

    Ta opcja często odwołuje się do nazwanej konfiguracji kompilacji, takiej jak Debug lub Release. Możesz użyć dowolnej nazwy konfiguracji, ale większość narzędzi oczekuje jednego z tych elementów. To ustawienie jest często używane do konfigurowania innych właściwości w sposób, który ma sens dla tej konfiguracji — na przykład wykonanie mniejszej optymalizacji kodu podczas kompilowania Debug konfiguracji. Rozważ tę opcję, jeśli polecenie ma różne tryby działania.

  • -f dla --framework

    Ta opcja służy do wyboru pojedynczego Target Framework Moniker (TFM) do uruchomienia, więc jeśli aplikacja interfejsu wiersza polecenia ma różne zachowanie w zależności od wybranego TFM, należy obsługiwać tę flagę.

  • -p dla --property

    Jeśli aplikacja w końcu wywołuje program MSBuild, użytkownik będzie często musiał dostosować to wywołanie w jakiś sposób. Ta opcja umożliwia podanie właściwości programu MSBuild w wierszu polecenia i przekazanie ich do bazowego wywołania MSBuild. Jeśli aplikacja nie używa programu MSBuild, ale wymaga zestawu par klucz-wartość, rozważ użycie tej samej nazwy opcji, aby skorzystać z oczekiwań użytkowników.

  • -r dla --runtime

    Jeśli aplikacja może działać w różnych środowiskach uruchomieniowych lub ma logikę specyficzną dla środowiska uruchomieniowego, rozważ obsługę tej opcji jako sposób określania identyfikatora środowiska uruchomieniowego. Jeśli twoja aplikacja obsługuje --runtime, rozważ wsparcie także dla --os i --arch. Te opcje umożliwiają określenie tylko części systemu operacyjnego lub architektury identyfikatora RID, pozostawiając część nieokreśloną do określenia na bieżącej platformie. Aby uzyskać więcej informacji, zobacz dotnet publish.

Krótkie nazwy

Uczyń nazwy poleceń, opcji i argumentów możliwie krótkimi i łatwymi do zapisania. Jeśli na przykład class jest wystarczająco jasne, nie należy wykonywać polecenia classification.

Nazwy pisane małymi literami

Zdefiniuj nazwy tylko małymi literami, lecz możesz tworzyć aliasy zapisane wielkimi literami, aby polecenia lub opcje były nieczułe na wielkość liter.

Nazwy przypadków Kebab

Użyj wielkości liter kebabu , aby odróżnić słowa. Na przykład --additional-probing-path.

Pluralizacja

W aplikacji należy zachować spójność w stosowaniu liczby mnogiej. Na przykład nie mieszaj nazw w liczbie mnogiej i pojedynczej dla opcji, które mogą mieć wiele wartości (maksymalna arytmia większa niż jedna):

Nazwy opcji Konsystencja
--additional-probing-paths i --sources ✔️
--additional-probing-path i --source ✔️
--additional-probing-paths i --source ❌
--additional-probing-path i --sources ❌

Czasowniki a rzeczowniki

Użyj czasowników, a nie rzeczowników dla poleceń odwołujących się do akcji (tych bez podpolecenia pod nimi), na przykład: dotnet workload remove, a nie dotnet workload removal. I używaj rzeczowników, a nie czasowników dla opcji, na przykład: --configuration, a nie --configure.

Opcja --verbosity

System.CommandLine aplikacje zazwyczaj oferują opcję, która określa, --verbosity ile danych wyjściowych jest wysyłanych do konsoli. Poniżej przedstawiono pięć standardowych ustawień:

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

Są to nazwy standardowe, ale istniejące aplikacje czasami używają Silent zamiast Quiet, a także Trace, Debug lub Verbose zamiast Diagnostic.

Każda aplikacja definiuje własne kryteria, które określają, co jest wyświetlane na każdym poziomie. Zazwyczaj aplikacja wymaga tylko trzech poziomów:

  • Spokojny
  • Standardowy
  • Diagnostyka

Jeśli aplikacja nie potrzebuje pięciu różnych poziomów, opcja powinna nadal definiować te same pięć ustawień. W takim przypadku Minimal i Normal spowodują wygenerowanie takich samych danych wyjściowych, a Detailed i Diagnostic również będą takie same. Dzięki temu użytkownicy mogą po prostu wpisać to, co znają, a system automatycznie wybierze najlepsze dopasowanie.

Quiet Oczekuje się, że w konsoli nie są wyświetlane żadne dane wyjściowe. Jeśli jednak aplikacja oferuje tryb interaktywny, aplikacja powinna wykonać jedną z następujących czynności:

  • Wyświetl monity o podanie danych wejściowych, gdy określono --interactive, nawet jeśli --verbosity ma wartość Quiet.
  • Nie zezwalaj na używanie --verbosity Quiet i --interactive razem.

W przeciwnym razie aplikacja będzie czekać na dane wejściowe bez informowania użytkownika o tym, na co czeka. Pojawi się, że aplikacja zamarła, a użytkownik nie będzie miał pojęcia, że aplikacja czeka na dane wejściowe.

Jeśli zdefiniujesz aliasy, użyj -v dla --verbosity i ustaw -v bez argumentu jako alias dla --verbosity Diagnostic. Użyj -q dla --verbosity Quiet.

Konwencje CLI i POSIX dla platformy .NET

Interfejs wiersza polecenia platformy .NET nie przestrzega konsekwentnie wszystkich konwencji POSIX.

Podwójna kreska

Kilka poleceń w .NET CLI ma specjalną implementację znacznika podwójnej kreseczki. W przypadku dotnet run, dotnet watch i dotnet tool run, tokeny, które następują po --, są przekazywane do aplikacji uruchamianej przez polecenie. Przykład:

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

W tym przykładzie opcja --project jest przekazywana do polecenia dotnet run, a opcja --message wraz ze swoim argumentem jest przekazywana jako opcja wiersza polecenia do aplikacji myapp podczas jej uruchamiania.

Token -- nie zawsze jest wymagany do przekazywania opcji do aplikacji, która jest uruchamiana przy użyciu polecenia dotnet run. Bez podwójnej kreski dotnet run polecenie automatycznie przekazuje do uruchamianej aplikacji wszelkie opcje, które nie są rozpoznawane jako stosowane do dotnet run lub do MSBuild. Dlatego następujące wiersze polecenia są równoważne, ponieważ dotnet run nie rozpoznaje argumentów i opcji:

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

Pominięcie ogranicznika opcji do argumentu

Narzędzie wiersza polecenia .NET CLI nie obsługuje konwencji POSIX, która pozwala na pominięcie ogranicznika podczas określania aliasu opcji za pomocą pojedynczego znaku.

Wiele argumentów bez powtarzania nazwy opcji

Interfejs wiersza polecenia platformy .NET nie akceptuje wielu argumentów dla jednej opcji bez powtarzania nazwy opcji.

Opcje logiczne

W interfejsie wiersza polecenia platformy .NET niektóre opcje logiczne powodują takie samo zachowanie podczas przekazywania false, jak podczas przekazywania true. To zachowanie powoduje, że kod interfejsu wiersza polecenia platformy .NET implementujący opcję sprawdza tylko obecność lub brak opcji, ignorując wartość. Przykładem polecenia jest --no-restore dla dotnet build . Przekaż --no-restore false, a operacje przywracania zostaną pominięte tak samo, jak podczas określania --no-restore true lub --no-restore.

Przypadek Kebab

W niektórych przypadkach interfejs wiersza polecenia platformy .NET nie używa formatu kebab case dla nazw poleceń, opcji ani argumentów. Na przykład istnieje opcja interfejsu wiersza polecenia platformy .NET o nazwie --additionalprobingpath zamiast --additional-probing-path.

Zobacz także