Omówienie składni wiersza polecenia dla polecenia System.CommandLine

Artykuł
06/08/2023

Ważne

System.CommandLine jest obecnie dostępna w wersji zapoznawczej, a ta dokumentacja dotyczy wersji 2.0 beta 4. Niektóre informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany przed jego wydaniem. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

W tym artykule wyjaśniono składnię wiersza polecenia, która System.CommandLine rozpoznaje. Informacje będą przydatne dla użytkowników, a także deweloperów aplikacji wiersza polecenia platformy .NET, w tym interfejsu wiersza polecenia platformy .NET.

Tokeny

System.CommandLine Analizuje dane wejściowe wiersza polecenia w tokenach, które są ciągami rozdzielanymi spacjami. Rozważmy na przykład następujący wiersz polecenia:

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

Te dane wejściowe są analizowane przez aplikację dotnet do tokenów tool, , install, --globaldotnet-suggest, , --verbosityi quiet.

Tokeny są interpretowane jako polecenia, opcje lub argumenty. Wywoływana aplikacja wiersza polecenia określa sposób interpretowania tokenów po pierwszym z nich. W poniższej tabeli przedstawiono sposób System.CommandLine interpretowania poprzedniego przykładu:

Token	Przeanalizowane jako
`tool`	Podpolecenie
`install`	Podpolecenie
`dotnet-suggest`	Argument polecenia install
`--global`	Opcja polecenia instalacji
`--verbosity`	Opcja polecenia instalacji
`quiet`	Argument dla `--verbosity` opcji

Token może zawierać spacje, jeśli jest ujęta w cudzysłów ("). Oto przykład:

dotnet tool search "ef migrations add"

Polecenia

Polecenie w danych wejściowych wiersza polecenia to token określający akcję lub definiujący grupę powiązanych akcji. Na przykład:

W dotnet runpliku run to polecenie, które określa akcję.
W dotnet tool installsystemie install jest poleceniem, które określa akcję i tool jest poleceniem określającym grupę powiązanych poleceń. Istnieją inne polecenia związane z narzędziem, takie jak tool uninstall, tool listi tool update.

Polecenia główne

Polecenie główne jest tym , który określa nazwę pliku wykonywalnego aplikacji. Na przykład dotnet polecenie określa plik wykonywalny dotnet.exe .

Podpoleceń polecenia

Większość aplikacji wiersza polecenia obsługuje polecenia podrzędne, znane również jako czasowniki. Na przykład polecenie dotnet ma run podpolecenia, które wywołujesz, wprowadzając polecenie dotnet run.

Podpolecenia mogą mieć własne podpolecenia. W dotnet tool installsystemie install jest podpolecenia .tool

Opcje

Opcja jest nazwanym parametrem, który można przekazać do polecenia. Interfejsy wiersza polecenia POSIX zwykle prefiks nazwy opcji z dwoma łącznikami (--). W poniższym przykładzie przedstawiono dwie opcje:

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

Jak pokazano w tym przykładzie, wartość opcji może być jawna (quiet dla --verbosity) lub niejawna (nic nie wynika z --global). Opcje, które nie mają określonej wartości, są zazwyczaj parametrami logicznymi domyślnymi, true jeśli opcja jest określona w wierszu polecenia.

W przypadku niektórych aplikacji wiersza polecenia systemu Windows można zidentyfikować opcję przy użyciu wiodącego ukośnika (/) z nazwą opcji. Na przykład:

msbuild /version
        ^------^

System.CommandLine obsługuje konwencje prefiksów POSIX i Windows. Podczas konfigurowania opcji należy określić nazwę opcji, w tym prefiks.

Argumenty

Argument jest wartością przekazywaną do opcji lub polecenia. W poniższych przykładach przedstawiono argument opcji verbosity i argument polecenia build .

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

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

Argumenty mogą mieć wartości domyślne, które mają zastosowanie, jeśli nie podano jawnie argumentu. Na przykład wiele opcji jest niejawnie parametrami logicznymi z wartością domyślną true , gdy nazwa opcji znajduje się w wierszu polecenia. Następujące przykłady wiersza polecenia są równoważne:

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

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

Niektóre opcje mają wymagane argumenty. Na przykład w interfejsie wiersza polecenia --output platformy .NET wymagany jest argument nazwy folderu. Jeśli argument nie zostanie podany, polecenie zakończy się niepowodzeniem.

Argumenty mogą mieć oczekiwane typy i System.CommandLine wyświetla komunikat o błędzie, jeśli nie można przeanalizować argumentu w oczekiwanym typie. Na przykład następujące błędy polecenia, ponieważ "dyskretne" nie są jedną z prawidłowych wartości dla --verbosityelementu :

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

Argumenty mają również oczekiwania dotyczące liczby wartości, które można podać. Przykłady znajdują się w sekcji dotyczącej arity argumentów.

Kolejność opcji i argumentów

Opcje można podać przed argumentami lub argumentami przed opcjami w wierszu polecenia. Następujące polecenia są równoważne:

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

Opcje można określić w dowolnej kolejności. Następujące polecenia są równoważne:

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

Jeśli istnieje wiele argumentów, kolejność ma znaczenie. Następujące polecenia nie muszą być równoważne:

myapp argument1 argument2
myapp argument2 argument1

Te polecenia przekazują listę o tych samych wartościach do kodu programu obsługi poleceń, ale różnią się one kolejnością wartości, co może prowadzić do różnych wyników.

Aliasy

W systemach POSIX i Windows niektóre polecenia i opcje mają aliasy. Są to zazwyczaj krótkie formy, które są łatwiejsze do pisania. Aliasy mogą być również używane w innych celach, takich jak symulowanie niewrażliwości na wielkość liter i obsługę alternatywnych pisowni wyrazu.

Krótkie formy POSIX zwykle mają jeden łącznik wiodący, po którym następuje pojedynczy znak. Następujące polecenia są równoważne:

dotnet build --verbosity quiet
dotnet build -v quiet

Standard GNU zaleca automatyczne aliasy. Oznacza to, że można wprowadzić dowolną część długiego polecenia lub nazwy opcji i zostanie zaakceptowana. To zachowanie spowoduje, że następujące wiersze polecenia będą równoważne:

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 nie obsługuje aliasów automatycznych.

Uwzględnij wielkość liter

Nazwy poleceń i aliasów są domyślnie uwzględniane wielkości liter zgodnie z konwencją POSIX i System.CommandLine są zgodne z tą konwencją. Jeśli chcesz, aby interfejs wiersza polecenia był niewrażliwy na wielkość liter, zdefiniuj aliasy dla różnych alternatyw wielkości liter. Na przykład --additional-probing-path może mieć aliasy --Additional-Probing-Path i --ADDITIONAL-PROBING-PATH.

W niektórych narzędziach wiersza polecenia różnica w wielkości liter określa różnicę w funkcji. Na przykład git clean -X zachowuje się inaczej niż git clean -x. Interfejs wiersza polecenia platformy .NET ma małe litery.

Wielkość liter nie ma zastosowania do wartości argumentów dla opcji opartych na wyliczeniach. Nazwy wyliczenia są dopasowywane niezależnie od wielkości liter.

Token `--`

Konwencja POSIX interpretuje token podwójnej kreski (--) jako mechanizm ucieczki. Wszystko, co następuje po tokenie podwójnej kreski, jest interpretowane jako argumenty dla polecenia. Ta funkcja może służyć do przesyłania argumentów, które wyglądają jak opcje, ponieważ uniemożliwia ich interpretowanie jako opcji.

Załóżmy, że aplikacja myapp przyjmuje message argument i chcesz, aby wartość message to --interactive. Poniższy wiersz polecenia może dać nieoczekiwane wyniki.

myapp --interactive

Jeśli myapp nie ma --interactive opcji, --interactive token jest interpretowany jako argument. Jeśli jednak aplikacja ma --interactive opcję, te dane wejściowe będą interpretowane jako odwołujące się do tej opcji.

Poniższy wiersz polecenia używa tokenu podwójnej kreski, aby ustawić wartość argumentu message na wartość "--interactive":

myapp -- --interactive
      ^^

System.CommandLine obsługuje tę funkcję podwójnej kreski.

Ograniczniki argumentów opcji

System.CommandLine umożliwia użycie spacji, '=' lub ':' jako ogranicznika między nazwą opcji a jej argumentem. Na przykład następujące polecenia są równoważne:

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

Konwencja POSIX umożliwia pominięcie ogranicznika podczas określania aliasu opcji pojedynczego znaku. Na przykład następujące polecenia są równoważne:

myapp -vquiet
myapp -v quiet

System.CommandLine obsługuje tę składnię domyślnie.

Arity argumentów

Arity argumentu opcji lub polecenia to liczba wartości, które można przekazać, jeśli określono tę opcję lub polecenie.

Arity jest wyrażana przy użyciu wartości minimalnej i wartości maksymalnej, jak pokazano w poniższej tabeli:

Min	Max	Przykładowa ważność	Przykład
0	0	Prawidłowe:	--Plik
		Nieprawidłowy:	--file a.json
		Nieprawidłowy:	--file a.json --file b.json
0	1	Prawidłowe:	--Flaga
		Prawidłowe:	--flaga true
		Prawidłowe:	--flaga false
		Nieprawidłowy:	--flaga false --flaga false
1	1	Prawidłowe:	--file a.json
		Nieprawidłowy:	--Plik
		Nieprawidłowy:	--file a.json --file b.json
0	N	Prawidłowe:	--Plik
		Prawidłowe:	--file a.json
		Prawidłowe:	--file a.json --file b.json
1	N	Prawidłowe:	--file a.json
		Prawidłowe:	--file a.json b.json
		Nieprawidłowy:	--Plik

System.CommandLineArgumentArity ma strukturę do definiowania arity z następującymi wartościami:

Zero - Brak dozwolonych wartości.
ZeroOrOne — Może mieć jedną wartość, może nie mieć wartości.
ExactlyOne - Musi mieć jedną wartość.
ZeroOrMore — Może mieć jedną wartość, wiele wartości lub brak wartości.
OneOrMore — Może mieć wiele wartości, musi mieć co najmniej jedną wartość.

Arity często można wywnioskować z typu. Na przykład int opcja ma wartość , ExactlyOnea List<int> opcja ma wartość .OneOrMore

Przesłonięcia opcji

Jeśli wartość maksymalna arity wynosi 1, nadal można skonfigurować tak, System.CommandLine aby akceptowała wiele wystąpień opcji. W takim przypadku ostatnie wystąpienie powtarzanej opcji zastępuje wszystkie wcześniejsze wystąpienia. W poniższym przykładzie wartość 2 zostanie przekazana do myapp polecenia .

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

Wiele argumentów

Jeśli wartość maksymalna arity jest więcej niż jedna, można skonfigurować tak, System.CommandLine aby akceptowała wiele argumentów dla jednej opcji bez powtarzania nazwy opcji.

W poniższym przykładzie lista przekazana do myapp polecenia będzie zawierać "a", "b", "c" i "d":

myapp --list a b c --list d

Tworzenie pakietów opcji

System POSIX zaleca obsługę tworzenia pakietów opcji jednoznakowych, nazywanych również tworzeniem stosu. Opcje w pakiecie to aliasy opcji jednoznaczowych określone razem po jednym prefiksie łącznika. Tylko ostatnia opcja może określać argument. Na przykład następujące wiersze polecenia są równoważne:

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

Jeśli argument zostanie podany po pakiecie opcji, ma zastosowanie do ostatniej opcji w pakiecie. Następujące wiersze polecenia są równoważne:

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

W obu wariantach w tym przykładzie argument arg ma zastosowanie tylko do opcji -c.

Opcje logiczne (flagi)

Jeśli true opcja mająca bool argument lub false jest przekazywana, jest ona analizowana zgodnie z oczekiwaniami. Jednak opcja, której typ argumentu jest bool zwykle nie wymaga określenia argumentu. Opcje logiczne, czasami nazywane "flagami", zwykle mają arity ZeroOrOne. Obecność nazwy opcji w wierszu polecenia, bez argumentu następującego po nim, powoduje domyślną wartość true. Brak nazwy opcji w danych wejściowych wiersza polecenia powoduje wartość false. myapp Jeśli polecenie wyświetli wartość opcji logicznej o nazwie --interactive, następujące dane wejściowe tworzą następujące dane wyjściowe:

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

False
True
False
True

Opcja --help

Aplikacje wiersza polecenia zwykle udostępniają opcję wyświetlania krótkiego opisu dostępnych poleceń, opcji i argumentów. System.CommandLine automatycznie generuje dane wyjściowe pomocy. Na przykład:

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.

Użytkownicy aplikacji mogą być przyzwyczajeni do różnych sposobów żądania pomocy na różnych platformach, więc aplikacje oparte na odpowiedzi na System.CommandLine wiele sposobów żądania pomocy. Wszystkie następujące polecenia są równoważne:

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

Dane wyjściowe pomocy nie muszą pokazywać wszystkich dostępnych poleceń, argumentów i opcji. Niektóre z nich mogą być ukryte, co oznacza, że nie są wyświetlane w danych wyjściowych pomocy, ale można je określić w wierszu polecenia.

Opcja --version

Aplikacje utworzone automatycznie System.CommandLine udostępniają numer wersji w odpowiedzi na --version opcję używaną z poleceniem głównym. Na przykład:

dotnet --version

6.0.100

Pliki odpowiedzi

Plik odpowiedzi to plik zawierający zestaw tokenów dla aplikacji wiersza polecenia. Pliki odpowiedzi są funkcją, która jest przydatna System.CommandLine w dwóch scenariuszach:

Aby wywołać aplikację wiersza polecenia, określając dane wejściowe dłuższe niż limit znaków terminalu.
Aby wielokrotnie wywoływać to samo polecenie bez ponownego pisania całego wiersza.

Aby użyć pliku odpowiedzi, wprowadź nazwę pliku poprzedzoną znakiem @ wszędzie tam, gdzie w wierszu chcesz wstawić polecenia, opcje i argumenty. Rozszerzenie pliku rsp jest wspólną konwencją, ale można użyć dowolnego rozszerzenia pliku.

Następujące wiersze są równoważne:

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

Zawartość pliku sample1.rsp:

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

Zawartość pliku sample2.rsp:

--no-restore

Poniżej przedstawiono reguły składni określające sposób interpretowania tekstu w pliku odpowiedzi:

Tokeny są rozdzielane spacjami. Wiersz zawierający dzień dobry! jest traktowany jako dwa tokeny, Dobry i Rano!.
Wiele tokenów ujęta w cudzysłów jest interpretowanych jako pojedynczy token. Wiersz zawierający "Dzień dobry!" jest traktowany jako jeden token, Dzień dobry!.
Dowolny tekst między symbolem # a końcem wiersza jest traktowany jako komentarz i ignorowany.
Tokeny poprzedzone prefiksem @ mogą odwoływać się do dodatkowych plików odpowiedzi.
Plik odpowiedzi może zawierać wiele wierszy tekstu. Wiersze są łączone i interpretowane jako sekwencja tokenów.

Dyrektyw

System.CommandLinewprowadza element składniowy nazywany dyrektywą. Dyrektywa [parse] jest przykładem. Po dołączeniu [parse] nazwy System.CommandLine aplikacji zostanie wyświetlony diagram wyniku analizy zamiast wywoływania aplikacji wiersza polecenia:

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

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

Celem dyrektyw jest zapewnienie funkcji krzyżowych, które mogą być stosowane w aplikacjach wiersza polecenia. Ponieważ dyrektywy są składniowo odrębne od własnej składni aplikacji, mogą one zapewniać funkcjonalność, która ma zastosowanie w aplikacjach.

Dyrektywa musi być zgodna z następującymi regułami składni:

Jest to token w wierszu polecenia, który pojawia się po nazwie aplikacji, ale przed wszystkimi podpoleceniami lub opcjami.
Jest ujęta w nawiasy kwadratowe.
Nie zawiera spacji.

Nierozpoznana dyrektywa jest ignorowana bez powodowania błędu analizy.

Dyrektywa może zawierać argument oddzielony od nazwy dyrektywy dwukropkiem.

Wbudowane są następujące dyrektywy:

[parse]
[suggest]

Dyrektywa `[parse]`

Zarówno użytkownicy, jak i deweloperzy mogą okazać się przydatne, aby zobaczyć, jak aplikacja zinterpretuje dane wejściowe. Jedną z domyślnych System.CommandLine funkcji aplikacji jest [parse] dyrektywa, która umożliwia wyświetlenie podglądu wyniku analizy danych wejściowych polecenia. Na przykład:

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

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

W powyższym przykładzie:

Polecenie (myapp), jego opcje podrzędne i argumenty do tych opcji są pogrupowane przy użyciu nawiasów kwadratowych.
W przypadku wyniku [ --delay !<not-an-int> ]opcji parametr ! wskazuje błąd analizy. Nie można przeanalizować wartości not-an-intint dla opcji oczekiwanego typu. Błąd jest również oflagowany przed ! poleceniem zawierającym błędną opcję: ![ myapp....
W przypadku wyniku *[ --fgcolor <White> ]opcji opcja nie została określona w wierszu polecenia, więc użyto skonfigurowanej wartości domyślnej. White jest efektywną wartością dla tej opcji. Gwiazdka wskazuje, że wartość jest wartością domyślną.
???--> wskazuje dane wejściowe, które nie były zgodne z żadnymi poleceniami lub opcjami aplikacji.

Dyrektywa `[suggest]`

Dyrektywa [suggest] umożliwia wyszukiwanie poleceń, gdy nie znasz dokładnego polecenia.

dotnet [suggest] buil

build
build-server
msbuild

Wskazówki projektowe

W poniższych sekcjach przedstawiono wskazówki, które zalecamy stosować podczas projektowania interfejsu wiersza polecenia. Zastanów się, czego oczekuje twoja aplikacja w wierszu polecenia, podobnie jak oczekiwany przez serwer interfejsu API REST 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 środowisko, jeśli projekt interfejsu wiersza polecenia jest zgodny z typowymi wzorcami.

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

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ć polecenie , ale dotnet tool samo w dotnet tool installsobie byłoby niekompletne.

Jednym ze sposobów definiowania obszarów ułatwia użytkownikom organizowanie danych wyjściowych 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 interfejs wiersza polecenia ma niejawny obszar. Jeśli tak, należy rozważyć, czy zezwolić użytkownikowi na opcjonalne dołączanie lub pomijanie go tak jak w systemach docker build i docker image build. Jeśli opcjonalnie zezwolisz użytkownikowi na wpisywanie niejawnego obszaru, możesz również automatycznie uzyskać pomoc i uzupełnianie kart dla tego grupowania poleceń. 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).

Aliasy krótkich formularzy

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

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ść w monitowaniu 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 w konsoli programu ; Ta opcja służy do określania ilości danych wyjściowych żądań użytkownika. 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 interfejsu wiersza polecenia platformy .NET. 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 wybierania pojedynczej platformy docelowej Moniker (TFM) do wykonania, więc jeśli aplikacja interfejsu wiersza polecenia ma różne zachowanie w zależności od wybranego serwera 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 aplikacja obsługuje środowisko uruchomieniowe , rozważ obsługę --os , a --arch także. Te opcje umożliwiają określenie tylko części systemu operacyjnego lub architektury identyfikatora RID, pozostawiając część nieokreśloną do określenia z bieżącej platformy. Aby uzyskać więcej informacji, zobacz dotnet publish (Publikowanie dotnet).

Krótkie nazwy

Wprowadź nazwy poleceń, opcji i argumentów tak krótko, jak to możliwe. Jeśli na przykład jest wystarczająco jasne, class nie wykonaj polecenia classification.

Małe nazwy

Zdefiniuj nazwy tylko małymi literami, z wyjątkiem tworzenia wielkich aliasów, aby nie uwzględniać wielkości liter poleceń lub opcji.

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 liczbie 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	Spójność
`--additional-probing-paths` i `--sources`	✔️
`--additional-probing-path` i `--source`	✔️
`--additional-probing-paths` i `--source`	❌
`--additional-probing-path` i `--sources`	❌

Czasowniki a czasowniki

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ę określającą --verbosity ilość danych wyjściowych wysyłanych do konsoli programu . 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 są używane Silent zamiast Quiet, i TraceDebug, 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:

Quiet
Normalna
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 spowoduje wygenerowanie tych samych danych wyjściowych i DiagnosticDetailed będzie podobnie takie same. Dzięki temu użytkownicy mogą po prostu wpisać to, co znają, a najlepsze dopasowanie będzie używane.

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 alternatyw:

Wyświetla monity o podanie danych wejściowych, --interactive jeśli jest określony, 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, 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 polecenia -v--verbosity i nie utwórz -v bez argumentu aliasu dla elementu --verbosity Diagnostic. Użyj dla elementu -q--verbosity Quiet.

Konwencje interfejsu wiersza polecenia platformy .NET i POSIX

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

Podwójna kreska

Kilka poleceń w interfejsie wiersza polecenia platformy .NET ma specjalną implementację tokenu podwójnej kreski. W przypadku dotnet runnastępujących tokenów -- , dotnet watchi dotnet tool run, są przekazywane do aplikacji uruchamianej przez polecenie . Na przykład:

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

W tym przykładzie --project opcja jest przekazywana do dotnet run polecenia, a --message opcja z jej argumentem jest przekazywana jako opcja wiersza polecenia do aplikacji myapp po jej uruchomieniu.

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 aplikacji uruchamianej wszelkie opcje, które nie są rozpoznawane jako stosowane do dotnet run samego siebie lub do programu 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

Interfejs wiersza polecenia platformy .NET nie obsługuje konwencji POSIX, która umożliwia pominięcie ogranicznika podczas określania aliasu opcji 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 polecenia, jak w przypadku przekazania trueelementu . To zachowanie powoduje, że kod interfejsu wiersza polecenia platformy .NET implementujący opcję sprawdza tylko obecność lub brak opcji, ignorując wartość. Przykładem jest --no-restore polecenie dotnet build . Przekazywanie no-restore false i operacja przywracania zostanie pominięta tak samo jak w przypadku określenia no-restore true lub no-restore.

Przypadek Kebab

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