Visão geral da sintaxe: comandos, opções e argumentos

2025-06-19

Importante

System.CommandLine está atualmente em pré-visualização e esta documentação destina-se à versão 2.0 beta 5. Algumas informações estão relacionadas ao produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações fornecidas aqui.

Este artigo explica a sintaxe de linha de comando que System.CommandLine reconhece. As informações são úteis para usuários e desenvolvedores de aplicativos de linha de comando .NET, incluindo a CLI do .NET.

Símbolos

System.CommandLine analisa a entrada da linha de comando em tokens, que são cadeias de caracteres delimitadas por espaços. Por exemplo, considere a seguinte linha de comando:

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

Esta entrada é analisada pela aplicação dotnet em tokens tool, install, dotnet-suggest, --global, --verbosity e quiet.

Os tokens são interpretados como comandos, opções ou argumentos. O aplicativo de linha de comando que está sendo invocado determina como os tokens após o primeiro são interpretados. A tabela a seguir mostra como System.CommandLine interpreta o exemplo anterior:

Símbolo	Analisado como
`tool`	Subcomando
`install`	Subcomando
`dotnet-suggest`	Argumento para o comando install
`--global`	Opção para o comando de instalação
`--verbosity`	Opção para o comando de instalação
`quiet`	Argumento a favor da `--verbosity` opção

Um token pode conter espaços se estiver entre aspas ("). Aqui está um exemplo:

dotnet tool search "ef migrations add"

Comandos

Um comando na entrada de linha de comando é um token que especifica uma ação ou define um grupo de ações relacionadas. Por exemplo:

Em dotnet run, run é um comando que especifica uma ação.
Em dotnet tool install, install é um comando que especifica uma ação e tool é um comando que especifica um grupo de comandos relacionados. Existem outros comandos relacionados à ferramenta, como tool uninstall, tool liste tool update.

Comando raiz

O comando raiz é aquele que especifica o nome do executável do aplicativo. Por exemplo, o dotnet comando especifica o executáveldotnet.exe .

System.CommandLine.Command é a classe de uso geral para qualquer comando ou subcomando, enquanto System.CommandLine.RootCommand é uma versão especializada destinada ao ponto de entrada raiz do aplicativo, herdando todos os recursos, mas adicionando comportamento e padrões específicos da System.CommandLine.Command raiz, como a opção Ajuda, a opção Versão e a diretiva Sugira.

Subcomandos

A maioria dos aplicativos de linha de comando suporta subcomandos, também conhecidos como verbos. Por exemplo, o dotnet comando tem um run subcomando que você invoca digitando dotnet run.

Os subcomandos podem ter subcomandos próprios. Em dotnet tool install, install é um subcomando de tool.

Você pode adicionar subcomandos conforme mostrado no exemplo a seguir:

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

O subcomando mais interno neste exemplo pode ser invocado assim:

myapp sub1 sub1a

Opções

Uma opção é um parâmetro nomeado que pode ser passado para um comando. POSIX As CLIs normalmente prefixam o nome da opção com dois hífenes (--). O exemplo a seguir mostra duas opções:

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

Como este exemplo ilustra, o valor da opção pode ser explícito (quiet para --verbosity) ou implícito (nada se segue --global). As opções que não têm nenhum valor especificado são normalmente parâmetros booleanos que usam como padrão true se a opção for especificada na linha de comando.

Para algumas aplicações de linha de comando do Windows, uma opção é identificada usando uma barra inversa (/) com o nome da opção. Por exemplo:

msbuild /version
        ^------^

System.CommandLine suporta convenções de prefixo POSIX e Windows.

Ao configurar uma opção, você especifica o nome da opção, incluindo o prefixo:

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

Para adicionar uma opção a um comando e recursivamente a todos os seus subcomandos, use a System.CommandLine.Symbol.Recursive propriedade.

Opções Necessárias

Algumas opções exigiram argumentos. Por exemplo, na CLI do .NET, --output requer um argumento de nome de pasta. Se o argumento não for fornecido, o comando falhará. Para tornar uma opção necessária, defina sua System.CommandLine.Symbol.Required propriedade como true, conforme mostrado no exemplo a seguir:

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

Se uma opção necessária tiver um valor padrão (especificado via DefaultValueFactory propriedade), a opção não precisa ser especificada na linha de comando. Nesse caso, o valor padrão fornece o valor de opção necessário.

Argumentos

Um argumento é um parâmetro sem nome que pode ser passado para um comando. O exemplo a seguir mostra um argumento para o build comando.

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

Ao configurar um argumento, você especifica o nome do argumento (ele não é usado para análise, mas pode ser usado para obter valores analisados por nome ou exibir ajuda) e digita:

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

Valores Predefinidos

Ambos os argumentos e opções podem ter valores padrão que se aplicam se nenhum argumento for explicitamente fornecido. Por exemplo, muitas opções são parâmetros booleanos implícitos com um padrão de true quando o nome da opção está na linha de comando. Os seguintes exemplos de linha de comando são equivalentes:

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

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

Um argumento que é definido sem um valor padrão é tratado como um argumento necessário.

Erros de análise

Opções e argumentos têm tipos esperados, e um erro é produzido quando o valor não pode ser analisado. Por exemplo, o seguinte comando apresenta erro porque "silent" não é um dos valores válidos para --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'

Os argumentos também têm expectativas sobre quantos valores podem ser fornecidos. Exemplos são fornecidos na seção sobre aridade argumentativa.

Ordem das opções e dos argumentos

Você pode fornecer opções antes de argumentos ou argumentos antes de opções na linha de comando. Os seguintes comandos são equivalentes:

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

As opções podem ser especificadas em qualquer ordem. Os seguintes comandos são equivalentes:

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

Quando há vários argumentos, a ordem importa. Os comandos a seguir não são equivalentes; diferem na ordem dos valores, o que pode levar a resultados diferentes:

myapp argument1 argument2
myapp argument2 argument1

Apelidos

Tanto no POSIX quanto no Windows, é comum que alguns comandos e opções tenham aliases. Estas são geralmente formas curtas que são mais fáceis de digitar. Os aliases também podem ser usados para outros fins, como simular a insensibilidade a maiúsculas e minúsculas e dar suporte a grafias alternativas de uma palavra.

As formas curtas POSIX normalmente têm um único hífen à esquerda seguido por um único caractere. Os seguintes comandos são equivalentes:

dotnet build --verbosity quiet
dotnet build -v quiet

O padrão GNU recomenda aliases automáticos. Ou seja, você pode inserir qualquer parte de um comando de forma longa ou nome de opção e ele será aceito. Esse comportamento tornaria as seguintes linhas de comando equivalentes:

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 não suporta aliases automáticos. Cada alias deve ser especificado explicitamente. Ambos os comandos e opções expõem uma Aliases propriedade. Option tem um construtor que aceita aliases como parâmetros, para que você possa definir uma opção com vários aliases em uma única linha:

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

Recomendamos que você minimize o número de aliases de opção definidos e evite definir determinados aliases em particular. Para obter mais informações, consulte Aliases de formulário curto.

Sensível às maiúsculas e minúsculas

Os nomes e aliases de comandos e opções são sensíveis a maiúsculas e minúsculas por padrão, de acordo com a convenção POSIX, e System.CommandLine segue esta convenção. Se você quiser que sua CLI não diferencie maiúsculas de minúsculas, defina aliases para as várias alternativas de invólucro. Por exemplo, --additional-probing-path pode ter aliases --Additional-Probing-Path e --ADDITIONAL-PROBING-PATH.

Em algumas ferramentas de linha de comando, uma diferença na caixa especifica uma diferença na função. Por exemplo, git clean -X comporta-se de forma diferente do git clean -x. A CLI do .NET está em minúsculas.

A diferenciação de maiúsculas e minúsculas não se aplica a valores de argumento para opções baseados em enums. Os nomes de enum são combinados independentemente do invólucro.

O `--` token (símbolo)

A convenção POSIX interpreta o token de traço duplo (--) como um mecanismo de escape. Tudo o que vem depois do hífen duplo é interpretado como argumentos para o comando. Essa funcionalidade pode ser usada para enviar argumentos que se parecem com opções, uma vez que impede que eles sejam interpretados como opções.

Suponha que myapp usa um message argumento e você quer que o valor de message seja --interactive. A linha de comando a seguir pode fornecer resultados inesperados.

myapp --interactive

Se myapp não tiver uma --interactive opção, o --interactive token é interpretado como um argumento. Mas se o aplicativo tiver uma --interactive opção, essa entrada será interpretada como referindo-se a essa opção.

A linha de comando a seguir usa o token de traço duplo para definir o message valor do argumento como "--interactive":

myapp -- --interactive
      ^^

System.CommandLine suporta esta funcionalidade de traço duplo.

Delimitadores de argumento de opção

System.CommandLine permite que você use um espaço, '=', ou ':' como o delimitador entre um nome de opção e seu argumento. Por exemplo, os seguintes comandos são equivalentes:

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

Uma convenção POSIX permite omitir o delimitador quando você está especificando um alias de opção de caractere único. Por exemplo, os seguintes comandos são equivalentes:

myapp -vquiet
myapp -v quiet

System.CommandLine suporta essa sintaxe por padrão.

Aridade argumentativa

A aridade do argumento de uma opção ou comando é o número de valores que podem ser passados se essa opção ou comando for especificado.

A aridade é expressa com um valor mínimo e um valor máximo, como ilustra o quadro seguinte:

Minuto	Máx	Exemplo de validade	Exemplo
0	0	Validade:	--ficheiro
		Inválido:	--arquivo a.json
		Inválido:	--file a.json --file b.json
0	1	Validade:	--bandeira
		Validade:	--bandeira true
		Validade:	--bandeira falsa
		Inválido:	--bandeira falsa --bandeira falsa
1	1	Validade:	--arquivo a.json
		Inválido:	--ficheiro
		Inválido:	--file a.json --file b.json
0	n	Validade:	--ficheiro
		Validade:	--arquivo a.json
		Validade:	--file a.json --file b.json
1	n	Validade:	--arquivo a.json
		Validade:	--arquivo a.json b.json
		Inválido:	--ficheiro

System.CommandLine tem uma estrutura System.CommandLine.ArgumentArity para definir a aridade, com os seguintes valores:

System.CommandLine.ArgumentArity.Zero - Não são permitidos valores.
System.CommandLine.ArgumentArity.ZeroOrOne - Pode ter um valor, pode não ter valores.
System.CommandLine.ArgumentArity.ExactlyOne - Deve ter um valor.
System.CommandLine.ArgumentArity.ZeroOrMore - Pode ter um valor, vários valores ou nenhum valor.
System.CommandLine.ArgumentArity.OneOrMore - Pode ter vários valores, deve ter pelo menos um valor.

Você pode definir explicitamente a aridade usando a propriedade Arity, mas na maioria dos casos isso não é necessário. System.CommandLine determina automaticamente a aridade do argumento com base no tipo de argumento:

Tipo de argumento	Aridade padrão
`Boolean`	`ArgumentArity.ZeroOrOne`
Tipos de recolha	`ArgumentArity.ZeroOrMore`
Tudo o resto	`ArgumentArity.ExactlyOne`

Substituições de opção

Se a aridade máxima for 1, System.CommandLine ainda pode configurar-se para aceitar várias instâncias de uma única opção. Nesse caso, a última instância de uma opção repetida substitui quaisquer instâncias anteriores. No exemplo a seguir, o valor 2 seria passado para o myapp comando.

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

Vários argumentos

Por padrão, quando você chama um comando, pode repetir um nome de opção para especificar vários argumentos para uma opção que tenha aridade máxima maior que um.

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

Para permitir vários argumentos sem repetir o nome da opção, defina System.CommandLine.Option.AllowMultipleArgumentsPerToken como true. Essa configuração permite que você insira a seguinte linha de comando.

myapp --items one two three

A mesma configuração tem um efeito diferente se a aridade máxima do argumento for 1. Ele permite que você repita uma opção, mas leva apenas o último valor na linha. No exemplo a seguir, o valor three seria passado para o aplicativo.

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

Agregação de opções

O POSIX recomenda que você suporte a agregação de opções de um único caractere, também conhecido como empilhamento. As opções agrupadas são aliases de opção de caractere único especificados juntos após um único prefixo de hífen. Apenas a última opção pode especificar um argumento. Por exemplo, as seguintes linhas de comando são equivalentes:

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

Se um argumento for fornecido após um pacote de opções, ele se aplicará à última opção do pacote. As seguintes linhas de comando são equivalentes:

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

Em ambas as variantes neste exemplo, o argumento arg se aplicaria apenas à opção -c.

Opções booleanas (bandeiras)

Se true ou false for passado para uma opção com um bool argumento, ele será analisado conforme o esperado. Mas uma opção cujo tipo de argumento é bool normalmente não requer que um argumento seja especificado. As opções booleanas, às vezes chamadas de "bandeiras", normalmente têm uma aridade de System.CommandLine.ArgumentArity.ZeroOrOne. A presença do nome da opção na linha de comando, sem nenhum argumento seguindo-o, resulta em um valor padrão de true. A ausência do nome da opção na entrada da linha de comando resulta em um valor de false. Se o myapp comando imprimir o valor de uma opção booleana chamada --interactive, a entrada a seguir criará a seguinte saída:

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

False
True
False
True

Opção de versão

Os aplicativos criados em System.CommandLine fornecem automaticamente o número da versão em resposta à opção --version usada com o comando root. Por exemplo:

dotnet --version

6.0.100

Arquivos de resposta

Um arquivo de resposta é um arquivo que contém um conjunto de tokens para um aplicativo de linha de comando. Arquivos de resposta de System.CommandLine são um recurso útil em dois cenários:

Para invocar um aplicativo de linha de comando especificando a entrada que é maior do que o limite de caracteres do terminal.
Para invocar o mesmo comando repetidamente sem redigitar toda a linha.

Para usar um arquivo de resposta, digite o nome do arquivo prefixado por um @ sinal onde quer que na linha você queira inserir comandos, opções e argumentos. A extensão do arquivo .rsp é uma convenção comum, mas você pode usar qualquer extensão de arquivo.

As seguintes linhas são equivalentes:

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

Conteúdo da amostra1.rsp:

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

Conteúdo da amostra2.rsp:

--no-restore

Aqui estão as regras de sintaxe que determinam como o texto em um arquivo de resposta é interpretado:

Os tokens são delimitados por espaços. Uma linha que contém Bom dia! , é tratada como duas fichas, Bom e Bom dia!.
Vários tokens entre aspas são interpretados como um único token. Uma frase que contém "Bom dia!" é tratada como um símbolo, Bom dia!.
Qualquer texto entre um # símbolo e o fim da linha é tratado como um comentário e ignorado.
Tokens prefixados com @ podem fazer referência a arquivos de resposta adicionais.
O arquivo de resposta pode ter várias linhas de texto. As linhas são concatenadas e interpretadas como uma sequência de tokens.

Diretivas

System.CommandLine introduz um elemento sintático chamado diretiva representada por System.CommandLine.Directive tipo. A [diagram] diretiva é um exemplo. Quando você inclui [diagram] após o nome do aplicativo, System.CommandLine exibe um diagrama do resultado da análise em vez de invocar o aplicativo de linha de comando:

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

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

O objetivo das diretivas é fornecer funcionalidade transversal que possa ser aplicada em aplicativos de linha de comando. Como as diretivas são sintaticamente distintas da sintaxe do próprio aplicativo, elas podem fornecer funcionalidade que se aplica a todos os aplicativos.

Uma diretiva deve estar em conformidade com as seguintes regras de sintaxe:

É um token na linha de comando que vem após o nome do aplicativo, mas antes de quaisquer subcomandos ou opções.
Está entre parênteses retos.
Não contém espaços.

Uma diretiva não reconhecida é ignorada sem causar um erro de análise.

Uma diretiva pode incluir um argumento, separado do nome da diretiva por dois pontos.

As seguintes diretivas estão incorporadas:

[diagram]
[suggest]

A `[diagram]` diretiva

Tanto os usuários quanto os desenvolvedores podem achar útil ver como um aplicativo interpretará uma determinada entrada. Um dos recursos padrão de um System.CommandLine aplicativo é a [diagram] diretiva, que permite visualizar o resultado da análise da entrada de comando. Por exemplo:

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

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

No exemplo anterior:

O comando (myapp), suas opções filhas e os argumentos para essas opções são agrupados usando colchetes.
Para o resultado [ --delay !<not-an-int> ]da opção , o ! indica um erro de análise. O valor not-an-int de uma int opção não pode ser analisado para o tipo esperado. O erro também é assinalado por ! à frente do comando que contém a opção com erro: ![ myapp....
Para o resultado *[ --fgcolor <White> ]da opção, a opção não foi especificada na linha de comando, portanto, o padrão configurado foi usado. White é o valor efetivo para esta opção. O asterisco indica que o valor é o padrão.
???--> aponta para entradas que não corresponderam a nenhum dos comandos ou opções do aplicativo.

Sugerir diretiva

A [suggest] diretiva permite pesquisar comandos quando você não sabe o comando exato.

dotnet [suggest] buil

build
build-server
msbuild

Partilhar via