Omówienie składni: polecenia, opcje i argumenty

2025-06-19

Ważne

System.CommandLine jest obecnie dostępna w wersji zapoznawczej, a ta dokumentacja dotyczy wersji 2.0 beta 5. 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, wyraźnych ani domniemanych, w odniesieniu do podanych tutaj informacji.

W tym artykule wyjaśniono składnię wiersza polecenia, która System.CommandLine rozpoznaje. Te informacje są przydatne zarówno dla użytkowników, jak i deweloperów aplikacji wiersza polecenia platformy .NET, w tym interfejsu wiersza polecenia platformy .NET.

Tokeny

System.CommandLine przekształca dane wejściowe wiersza polecenia na tokeny, które są ciągami oddzielonymi 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, dotnet-suggest--global, , --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:

Żeton	Przeparsowane jako
`tool`	Podpolecenia
`install`	Podpolecenia
`dotnet-suggest`	Argument dla polecenia install
`--global`	Opcja polecenia instalacji
`--verbosity`	Opcja polecenia instalacji
`quiet`	Argument dla `--verbosity` opcji

Token może zawierać spacje, jeśli jest ujęty 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 run, 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.

Polecenie główne

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

System.CommandLine.Command jest klasą ogólnego przeznaczenia dla dowolnego polecenia lub podpolecenia, natomiast System.CommandLine.RootCommand jest wyspecjalizowaną wersją przeznaczoną dla głównego punktu wejścia aplikacji. Dziedzicząc wszystkie funkcje System.CommandLine.Command, dodaje zachowanie i wartości domyślne specyficzne dla punktu wejścia, takie jak Opcja Pomoc, Opcja Wersji i Dyrektywa Sugestii.

Podpolecenia

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 installinstall jest podpoleceniem tool.

Możesz dodać podpolecenia, jak pokazano w poniższym przykładzie:

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

Najbardziej wewnętrzne podpolecenia w tym przykładzie można wywołać w następujący sposób:

myapp sub1 sub1a

Opcje

Opcja jest nazwanym parametrem, który można przekazać do polecenia. POSIX Interfejsy CLI zwykle poprzedzają nazwę opcji 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 i domyślnie przyjmują wartość true, jeśli opcja jest ustawiona 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:

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

Aby dodać opcję do polecenia i rekursywnie do wszystkich jego podpoleceń, użyj właściwość System.CommandLine.Symbol.Recursive.

Wymagane opcje

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. Aby ustawić wymaganą opcję, ustaw jej System.CommandLine.Symbol.Required właściwość na true, jak pokazano w poniższym przykładzie:

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

Jeśli wymagana opcja ma wartość domyślną (określoną za pośrednictwem DefaultValueFactory właściwości), opcja nie musi być określona w wierszu polecenia. W takim przypadku wartość domyślna udostępnia wymaganą wartość opcji.

Argumenty (w programowaniu)

Argument jest nienazwanym parametrem, który można przekazać do polecenia. Poniższy przykład pokazuje argument dla polecenia build.

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

Podczas konfigurowania argumentu należy określić nazwę argumentu (nie jest używana do analizowania, ale może służyć do pobierania przeanalizowanych wartości według nazwy lub wyświetlania pomocy) i wpisz:

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

Wartości domyślne

Zarówno argumenty, jak i opcje mogą mieć wartości domyślne, które mają zastosowanie, jeśli nie podano jawnie argumentu. Na przykład wiele opcji stanowi niejawne parametry logiczne z wartością domyślną true, jeśli nazwa opcji jest 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
                                  ^-----------^

Argument zdefiniowany bez wartości domyślnej jest traktowany jako argument wymagany.

Analizowanie błędów

Opcje i argumenty mają oczekiwane typy, a błąd jest generowany, gdy nie można przeanalizować wartości. Na przykład, następujące polecenie zawiera błąd, ponieważ "ciche" nie jest jedną z prawidłowych wartości dla --verbosity:

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'

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

Kolejność opcji i argumentów

Można podać opcje przed argumentami lub argumenty 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 są równoważne; różnią się one kolejnością wartości, co może prowadzić do różnych wyników:

myapp argument1 argument2
myapp argument2 argument1

Pseudonimy

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. Każdy alias musi być określony jawnie. Oba polecenia i opcje udostępniają właściwość Aliases. Option ma konstruktor, który akceptuje aliasy jako parametry, więc można zdefiniować opcję z wieloma aliasami w jednym wierszu:

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

Zalecamy zminimalizowanie liczby zdefiniowanych aliasów opcji i unikanie definiowania określonych aliasów. Aby uzyskać więcej informacji, zobacz Krótkie aliasy.

Uwzględnij wielkość liter

Nazwy poleceń, opcji oraz aliasów domyślnie rozróżniają wielkość liter zgodnie z konwencją POSIX, a System.CommandLine także tej konwencji przestrzega. 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 oznacza różnicę w funkcji. Na przykład git clean -X zachowuje się inaczej niż git clean -x. ".NET CLI jest pisane małymi literami."

Rozróżnianie wielkości liter nie ma zastosowania do wartości argumentów opcji opartych na wyliczeniach (enums). 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 podwójnym znaku 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 separatora podczas określania aliasu dla opcji z pojedynczym znakiem. 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.

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

Minuta	Maks	Przykładowa ważność	Przykład
0	0	Ważny:	--plik
		Nieprawidłowy:	--file a.json
		Nieprawidłowy:	--file a.json --file b.json
0	1	Ważny:	--flaga
		Ważny:	--flaga prawda
		Ważny:	--flaga false
		Nieprawidłowy:	--flaga false --flaga false
1	1	Ważny:	--file a.json
		Nieprawidłowy:	--plik
		Nieprawidłowy:	--file a.json --file b.json
0	n	Ważny:	--plik
		Ważny:	--file a.json
		Ważny:	--file a.json --file b.json
1	n	Ważny:	--file a.json
		Ważny:	--file a.json b.json
		Nieprawidłowy:	--plik

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

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

Można jawnie ustawić arity przy użyciu Arity właściwości, ale w większości przypadków nie jest to konieczne. System.CommandLine automatycznie określa arity argumentu na podstawie typu argumentu:

Typ argumentu	Domyślna liczba argumentów
`Boolean`	`ArgumentArity.ZeroOrOne`
Typy kolekcji	`ArgumentArity.ZeroOrMore`
Reszta wszystkiego	`ArgumentArity.ExactlyOne`

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 polecenia myapp.

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

Wiele argumentów

Domyślnie podczas wywoływania polecenia można powtórzyć nazwę opcji, aby określić wiele argumentów dla opcji, która ma maksymalną wartość arity większą niż jedną.

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

Aby zezwolić na wiele argumentów bez powtarzania nazwy opcji, ustaw wartość System.CommandLine.Option.AllowMultipleArgumentsPerTokentrue. To ustawienie umożliwia wprowadzenie następującego wiersza polecenia.

myapp --items one two three

To samo ustawienie ma inny wpływ, jeśli maksymalna wartość arity argumentu wynosi 1. Umożliwia powtórzenie opcji, ale przyjmuje tylko ostatnią wartość w wierszu. W poniższym przykładzie wartość three zostanie przekazana do aplikacji.

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

Tworzenie pakietów opcji

System POSIX zaleca obsługę pakietowania opcji jednoznakowych, nazywanych również łączeniem. 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 dla opcji z argumentem true przekazywane są false lub bool, jest ona analizowana zgodnie z oczekiwaniami. Jednak opcja, której typ argumentu jest bool zwykle nie wymaga określenia argumentu. Opcje boolowskie, czasami nazywane "flagami", zwykle mają licznośćSystem.CommandLine.ArgumentArity.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. Jeśli polecenie myapp wyświetli wartość opcji logicznej nazwanej --interactive, dane wejściowe powodują poniższy wynik:

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

False
True
False
True

Opcja wersji

Aplikacje zbudowane na System.CommandLine automatycznie podają numer wersji w odpowiedzi na opcję --version 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ą System.CommandLine, która jest przydatna 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 symboli.

Dyrektyw

System.CommandLine wprowadza element składniowy nazywany dyrektywą reprezentowaną przez System.CommandLine.Directive typ. Dyrektywa [diagram] jest przykładem. Gdy załączysz [diagram] po nazwie aplikacji, System.CommandLine wyświetli diagram wyniku analizy zamiast uruchamiać aplikację wiersza polecenia.

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

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

Celem dyrektyw jest zapewnienie funkcjonalności przekrojowej, która może być stosowana 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:

[diagram]
[suggest]

Dyrektywa `[diagram]`

Dla użytkowników i deweloperów może być przydatne zobaczenie, jak aplikacja zinterpretuje dane wejściowe. Jedną z domyślnych System.CommandLine funkcji aplikacji jest [diagram] dyrektywa, która umożliwia wyświetlenie podglądu wyniku analizy danych wejściowych polecenia. Na przykład:

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

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

W poprzednim 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-int dla opcji int do oczekiwanego typu. Błąd jest również sygnalizowany przez ! przed poleceniem, które zawiera 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.

Sugerowanie dyrektywy

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

dotnet [suggest] buil

build
build-server
msbuild

Udostępnij za pośrednictwem