Общие сведения о синтаксисе: команды, параметры и аргументы

Это важно

System.CommandLine в настоящее время находится в предварительной версии, и эта документация предназначена для версии 2.0 бета-версии 5. Некоторые сведения относятся к предварительному выпуску продукта, который может быть существенно изменен до его выпуска. Корпорация Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых в отношении информации, предоставленной здесь.

В этой статье объясняется синтаксис командной строки, который System.CommandLine распознает. Эта информация полезна для пользователей и разработчиков приложений командной строки .NET, включая интерфейс командной строки .NET.

Токены

System.CommandLine анализирует входные данные командной строки в маркеры, которые являются строками, разделенными пробелами. Например, рассмотрим следующую командную строку:

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

Эти входные данные анализируются приложением dotnet в маркеры tool, install, dotnet-suggest, --global, --verbosity и quiet.

Маркеры интерпретируются как команды, параметры или аргументы. Вызываемое приложение командной строки определяет, как маркеры после первого интерпретируются. В следующей таблице показано, как System.CommandLine интерпретирует предыдущий пример:

Токен	Синтаксический анализ
tool	Подкоманда
install	Подкоманда
dotnet-suggest	Аргумент для команды установки
--global	Параметр для команды установки
--verbosity	Параметр для команды установки
quiet	Аргумент для --verbosity параметра

Маркер может содержать пробелы, если он заключен в кавычки ("). Ниже приведен пример:

dotnet tool search "ef migrations add"

Команды

Команда во входных данных командной строки — это токен, указывающий действие или определяющий группу связанных действий. Рассмотрим пример.

• В dotnet run— run это команда, указывающая действие.
• В dotnet tool install— install это команда, указывающая действие, и tool является командой, указывающей группу связанных команд. Существуют другие команды, связанные с инструментами, например tool uninstall, tool listи tool update.

Корневая команда

Корневая команда — это команда, указывающая имя исполняемого файла приложения. Например, команда dotnet задает исполняемый файл dotnet.exe.

System.CommandLine.Command — это класс общего назначения для любой команды или субкоманда, в то время как System.CommandLine.RootCommand это специализированная версия, предназначенная для корневой точки входа приложения, наследуя все функции System.CommandLine.Command , но добавляя поведение и значения по умолчанию, такие как параметр справки, параметр версии и директива "Предложить".

Подкоманды

Большинство приложений командной строки поддерживают вложенные команды, также называемые командами. Например, у команды dotnet есть подкоманда run, которую можно вызвать путем ввода dotnet run.

Подкоманды могут иметь собственные подкоманды. В dotnet tool installinstall является подкомандой tool.

Вы можете добавить вложенные комманды, как показано в следующем примере:

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

Самую внутреннюю подкоманду в этом примере можно вызвать следующим образом:

myapp sub1 sub1a

Опции

Опция — это именованный параметр, который можно передать команде. POSIX CLI обычно представляют имя параметра с двумя тирами (--). В следующем примере показаны два варианта:

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

Как показано в этом примере, значение параметра может быть явным (quiet для --verbosity) или неявным (ничего не следует --global). Параметры, для которых не указано значение, обычно являются логическими параметрами, которые по умолчанию принимают значение true, если опция указана в командной строке.

Для некоторых приложений командной строки Windows можно определить параметр с помощью начальной косой черты (/) с именем параметра. Рассмотрим пример.

msbuild /version
        ^------^

System.CommandLine поддерживает соглашения о префиксе POSIX и Windows.

При настройке параметра укажите имя параметра, включая префикс:

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

Чтобы добавить параметр в команду и рекурсивно ко всем её вложенным командам, используйте это свойство System.CommandLine.Symbol.Recursive.

Обязательные параметры

Несколько параметров имеют обязательные аргументы. Например, в .NET CLI --output требуется аргумент имени папки. Если аргумент не указан, команда завершается ошибкой. Чтобы сделать параметр обязательным, установите его свойство System.CommandLine.Symbol.Required в true, как показано в следующем примере:

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

Если обязательный параметр имеет значение по умолчанию (указанное через DefaultValueFactory свойство), этот параметр не должен быть указан в командной строке. В этом случае значение по умолчанию предоставляет требуемое значение параметра.

Аргументы

Аргумент — это неименованный параметр, который можно передать команде. В следующем примере показан аргумент команды build .

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

При настройке аргумента укажите имя аргумента (он не используется для синтаксического анализа, но его можно использовать для получения проанализированных значений по имени или отображению справки) и типа:

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

Значения по умолчанию

Оба аргумента и параметры могут иметь значения по умолчанию, которые применяются, если аргумент не указан явным образом. Например, многие параметры являются неявно логическими параметрами с значением по умолчанию true , если имя параметра находится в командной строке. Ниже приведены эквивалентные примеры командной строки:

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

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

Аргумент, определенный без значения по умолчанию, рассматривается как обязательный аргумент.

Ошибки синтаксического анализа

Параметры и аргументы имеют ожидаемые типы, и возникает ошибка, если значение не удается разобрать. Например, следующая команда вызывает ошибку, потому что "silent" не является одним из допустимых значений для --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'

Ожидания аргументов также касаются количества значений, которые можно предоставить. Примеры приведены в разделе о количестве аргументов.

Порядок параметров и аргументов

Вы можете указать параметры перед аргументами или аргументы перед параметрами в командной строке. Следующие команды эквивалентны:

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

Параметры можно указать в любом порядке. Следующие команды эквивалентны:

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

Если имеется несколько аргументов, порядок имеет значение. Следующие команды не эквивалентны; они отличаются в порядке значений, которые могут привести к разным результатам:

myapp argument1 argument2
myapp argument2 argument1

Псевдонимы

В средах POSIX и Windows для некоторых команд и параметров обычно существуют псевдонимы. Обычно это короткие формы, которые проще вводить. Псевдонимы также можно использовать для других целей, таких как имитация нечувствительности к регистру и поддержка альтернативного написания слова.

Короткие формы POSIX обычно имеют один ведущий дефис, за которым следует один символ. Следующие команды эквивалентны:

dotnet build --verbosity quiet
dotnet build -v quiet

Стандарт GNU рекомендует автоматические псевдонимы. То есть можно ввести любую часть команды длинной формы или имени параметра, и она будет принята. Это поведение приведет к эквиваленту следующих команд:

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 не поддерживает автоматические псевдонимы. Каждый псевдоним должен быть указан явным образом. Как команды, так и параметры предоставляют свойство Aliases. Option имеет конструктор, который принимает псевдонимы в качестве параметров, поэтому можно определить параметр с несколькими псевдонимами в одной строке:

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

Рекомендуется свести к минимуму количество псевдонимов параметров, которые вы определяете, и избегать определения некоторых из них. Дополнительные сведения см. в разделе "Кратковременные псевдонимы".

Конфиденциальность регистра

Имена команд и псевдонимов по умолчанию чувствительны к регистру в соответствии с соглашением POSIX, и System.CommandLine соответствует этому соглашению. Если вы хотите, чтобы интерфейс командной строки не учитывал регистр, определите алиасы для различных вариантов регистра. Например, --additional-probing-path может иметь псевдонимы --Additional-Probing-Path и --ADDITIONAL-PROBING-PATH.

В некоторых инструментах командной строки разница в регистре определяет разницу в функциональности. Например, git clean -X ведет себя иначе, чем git clean -x. Интерфейс командной строки .NET пишется полностью строчными буквами.

Конфиденциальность регистра не применяется к значениям аргументов для параметров, основанных на перечислениях. Имена перечислений совпадают независимо от регистра.

Маркер --

Соглашение POSIX интерпретирует маркер двойного дефиса (--) в качестве механизма экранирования. Все, что следует маркеру двойного дефиса, интерпретируется как аргументы для команды. Эту функцию можно использовать для отправки аргументов, которые выглядят как параметры, так как они не интерпретируются как параметры.

Предположим, myapp принимает message аргумент, и вы хотите, чтобы значение message было --interactive. Следующая командная строка может дать непредвиденные результаты.

myapp --interactive

Если myapp нет --interactive опции, --interactive маркер интерпретируется как аргумент. Но если у приложения есть --interactive параметр, этот вход будет интерпретирован как ссылающийся на этот параметр.

В следующей командной строке используется токен двойного дефиса, чтобы установить значение аргумента message на "--interactive".

myapp -- --interactive
      ^^

System.CommandLine поддерживает эту функцию двойного дефиса.

Разделители опция-аргумент

System.CommandLine позволяет использовать пробел, "=" или ":" в качестве разделителя между именем параметра и его аргументом. Например, следующие команды эквивалентны:

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

Соглашение POSIX позволяет опустить разделитель при указании псевдонима однобуквенной опции. Например, следующие команды эквивалентны:

myapp -vquiet
myapp -v quiet

System.CommandLine поддерживает этот синтаксис по умолчанию.

Арность аргумента

Arity аргумента параметра или команды — это количество значений, которые можно передать, если указан этот параметр или команда.

Arity выражается минимальным и максимальным значениями, как показано в следующей таблице.

мин	Макс	Пример допустимости	Пример
0	0	Действительный:	--файл
		Недопустимый:	--file a.json
		Недопустимый:	--file a.json --file b.json
0	1	Действительный:	--флаг
		Действительный:	--flag истина
		Действительный:	--flag false
		Недопустимый:	--flag false --flag false --flag false
1	1	Действительный:	--file a.json
		Недопустимый:	--файл
		Недопустимый:	--file a.json --file b.json
0	n	Действительный:	--файл
		Действительный:	--file a.json
		Действительный:	--file a.json --file b.json
1	n	Действительный:	--file a.json
		Действительный:	--file a.json b.json
		Недопустимый:	--файл

System.CommandLine имеет структуру System.CommandLine.ArgumentArity для определения arity со следующими значениями:

• System.CommandLine.ArgumentArity.Zero — значения не разрешены.
• System.CommandLine.ArgumentArity.ZeroOrOne — Может иметь одно значение, может не иметь значений.
• System.CommandLine.ArgumentArity.ExactlyOne — должно иметь одно значение.
• System.CommandLine.ArgumentArity.ZeroOrMore — может иметь одно значение, несколько значений или нет значений.
• System.CommandLine.ArgumentArity.OneOrMore — Может иметь несколько значений, должно иметь по крайней мере одно значение.

Вы можете явно задать arity с помощью Arity свойства, но в большинстве случаев это необязательно. System.CommandLine автоматически определяет арность аргумента на основе типа аргумента.

Тип аргумента	Arity по умолчанию
Boolean	ArgumentArity.ZeroOrOne
Типы коллекций	ArgumentArity.ZeroOrMore
В любом другом месте	ArgumentArity.ExactlyOne

Переопределения опций

Если максимальное значение arity равно 1, System.CommandLine можно настроить для принятия нескольких экземпляров параметра. В этом случае последний вариант повторяющегося параметра перезаписывает все предыдущие варианты. В следующем примере значение 2 будет передано команде myapp .

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

Несколько аргументов

По умолчанию при вызове команды можно повторить имя параметра, чтобы указать несколько аргументов для параметра с максимальным числом arity больше одного.

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

Чтобы разрешить использование нескольких аргументов без повторения имени опции, установите System.CommandLine.Option.AllowMultipleArgumentsPerToken в значение true. Этот параметр позволяет ввести следующую командную строку.

myapp --items one two three

Тот же параметр имеет другой эффект, если максимальное число аргументов равно 1. Он позволяет повторять параметр, но принимает только последнее значение в строке. В следующем примере значение three будет передано приложению.

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

Пакетирование опций

POSIX рекомендует поддерживать объединение односимвольных опций, также известное как группировка. Объединённые параметры — это псевдонимы, состоящие из одного символа, указанные вместе после одного префикса дефиса. Только последний параметр может указать аргумент. Например, следующие командные строки эквивалентны:

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

Если аргумент предоставляется после пакета параметров, он применяется к последнему параметру в пакете. Следующие командные строки эквивалентны:

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

В обоих вариантах в этом примере аргумент arg будет применяться только к параметру -c.

Логические параметры (флаги)

Если true или false передан как параметр с аргументом bool, он должным образом анализируется. Но параметр, тип bool аргумента которого обычно не требует указания аргумента. Логические параметры, иногда называемые "флагами", обычно имеют арностьSystem.CommandLine.ArgumentArity.ZeroOrOne. Наличие имени параметра в командной строке без аргументов, приводит к значению trueпо умолчанию. Отсутствие имени параметра во входных данных командной строки приводит к значению false. myapp Если команда выводит значение логического параметра с именем--interactive, то следующие входные данные создают следующие выходные данные:

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

False
True
False
True

Настройка версии

Приложения, созданные на основе System.CommandLine, автоматически предоставляют номер версии в ответ на параметр --version, используемый с корневой командой. Рассмотрим пример.

dotnet --version

6.0.100

Файлы ответов

Файл ответа — это файл, содержащий набор маркеров для приложения командной строки. Файлы ответов — это функция System.CommandLine , которая полезна в двух сценариях:

• Чтобы вызвать приложение командной строки, указав входные данные, превышающие предел символа терминала.
• Для многократного вызова одной и той же команды без повторного ввода всей строки.

Чтобы использовать файл ответа, введите имя файла, префиксированного @ знаком, где бы ни находилась строка, в которую нужно вставить команды, параметры и аргументы. Расширение RSP-файла является общим соглашением, но вы можете использовать любое расширение файла.

Следующие строки эквивалентны:

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

Содержимое примера1.rsp:

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

Содержимое sample2.rsp:

--no-restore

Ниже приведены правила синтаксиса, определяющие интерпретацию текста в файле ответа:

• Токены разделяются пробелами. Строка, содержащая доброе утро! рассматривается как два маркера, Доброе и утро!.
• Несколько маркеров, заключенных в кавычки, интерпретируются как один маркер. Строка, содержащая "Доброе утро!" рассматривается как один маркер , Доброе утро!.
• Любой текст между символом # и концом строки рассматривается как комментарий и игнорируется.
• Токены с префиксом @ могут ссылаться на дополнительные файлы ответов.
• Файл ответа может содержать несколько строк текста. Строки объединяются и интерпретируются как последовательность маркеров.

Директивы

System.CommandLine представляет синтаксический элемент, называемый директивой , представленной типом System.CommandLine.Directive . Директива [diagram] является примером. При включении [diagram] после имени System.CommandLine приложения отображается схема результата синтаксического анализа вместо вызова приложения командной строки:

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

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

Цель директив — предоставить сквозную функциональность, которая может применяться в приложениях командной строки. Так как директивы синтаксически отличаются от собственного синтаксиса приложения, они могут предоставлять функциональные возможности, которые применяются в приложениях.

Директива должна соответствовать следующим правилам синтаксиса:

• Это токен в командной строке, который следует за именем приложения, но перед любыми подкомандами или параметрами.
• Он заключен в квадратные скобки.
• Он не содержит пробелов.

Нераспознанная директива игнорируется без возникновения ошибки синтаксического анализа.

Директива может включать аргумент, разделенный именем директивы двоеточием.

Встроены следующие директивы:

• [diagram]
• [suggest]

Директива [diagram]

Пользователям и разработчикам может быть полезно увидеть, как приложение будет интерпретировать заданные входные данные. Одной из функций System.CommandLine по умолчанию приложения является [diagram] директива, которая позволяет предварительно просмотреть результат анализа входных данных команды. Рассмотрим пример.

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

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

В предыдущем примере:

• Команда (myapp), ее дочерние параметры и аргументы для этих параметров группируются с помощью квадратных скобок.
• Для результата [ --delay !<not-an-int> ]! указывает ошибку синтаксического анализа. Значение not-an-int для параметра int невозможно распознать как ожидаемый тип. Ошибка также помечается ! перед командой, содержащей ошибочную опцию: ![ myapp....
• Для результата *[ --fgcolor <White> ] параметр не был указан в командной строке, поэтому использовалось заданное по умолчанию значение. White — это эффективное значение для этого параметра. Звездочка указывает, что значение по умолчанию.
• ???--> указывает на входные данные, которые не соответствовали ни одной из команд или параметров приложения.

Предложение директивы

Директива [suggest] позволяет искать команды, если вы не знаете точной команды.

dotnet [suggest] buil

build
build-server
msbuild

См. также

• Руководство по проектированию
• Руководство по проектированию интерфейса командной строки с открытым исходным кодом
• Стандарты GNU
• System.CommandLine Обзор
• Руководство. Начало работы с System.CommandLine