Compartilhar via

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

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 do .NET, incluindo a CLI do .NET.

Tokens

System.CommandLine analisa a entrada de 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

Essa entrada é analisada pelo aplicativo dotnet nos 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 de instalação
--global Opção para o comando de instalação
--verbosity Opção para o comando de instalação
quiet Argumento a favor de --verbosity opção

Um token poderá conter espaços se ele estiver entre aspas ("). Veja um exemplo:

dotnet tool search "ef migrations add"

A hierarquia de símbolos (comandos, opções, argumentos) é considerada uma entrada confiável; os valores de token não são.

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:

  • In dotnet run, run é um comando que especifica uma ação.
  • In dotnet tool install, install é um comando que especifica uma ação e tool é um comando que especifica um grupo de comandos relacionados. Há outros comandos relacionados a ferramentas, 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 .

Command é a classe de uso geral para qualquer comando ou subcomando, enquanto RootCommand é uma versão especializada destinada ao ponto de entrada raiz do aplicativo. RootCommand herda todos os recursos, Command mas adiciona padrões e comportamentos específicos à raiz, como a opção Ajuda, a opção Versão e a diretiva Sugerir.

Subcomandos

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

Subcomandos podem ter seus próprios subcomandos. In 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 da seguinte maneira:

myapp sub1 sub1a

Opções

Uma opção é um parâmetro nomeado que pode ser passado para um comando. POSIX Normalmente, os CLIs prefixam o nome da opção com dois hifens (--). 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 segue --global). As opções que não têm nenhum valor especificado normalmente são parâmetros boolianos que assumem o padrão de true se a opção é especificada na linha de comando.

Para alguns aplicativos de linha de comando do Windows, você identifica uma opção usando uma barra à esquerda (/) com o nome da opção. Por exemplo:

msbuild /version
        ^------^

System.CommandLine dá suporte a convenções de prefixo POSIX e Windows.

Ao configurar uma opção, especifique 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 têm argumentos necessários. 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 fazer uma opção necessária, defina sua 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 por meio da DefaultValueFactory propriedade), a opção não precisará ser especificada na linha de comando. Nesse caso, o valor padrão fornece o valor da opção necessária.

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, especifique 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 digitar:

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 padrão

Argumentos e opções podem ter valores padrão que se aplicam se nenhum argumento for fornecido explicitamente. Por exemplo, muitas opções são parâmetros implicitamente boolianos com um padrão de true quando o nome da opção está na linha de comando. Os exemplos de linha de comando a seguir são equivalentes:

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

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

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

Erros de análise sintática

Opções e argumentos têm tipos esperados e um erro é produzido quando o valor não pode ser analisado. Por exemplo, os seguintes erros de comando por "silencioso" não ser 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 de argumento.

Ordem de opções e argumentos

Você pode fornecer opções antes de argumentos ou argumentos antes das 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; elas diferem na ordem dos valores, o que pode levar a resultados diferentes:

myapp argument1 argument2
myapp argument2 argument1

Apelidos

No POSIX e no Windows, é comum que alguns comandos e opções tenham aliases. Geralmente, são formulários curtos que são mais fáceis de digitar. Os aliases também podem ser usados para outras finalidades, como simular a insensibilidade a maiúsculas e minúsculas e suportar diferentes grafias de palavras.

Normalmente, as formas curtas POSIX 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 ou nome de opção de forma longa e ela será aceita. 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 dá suporte a aliases automáticos. Cada alias deve ser especificado explicitamente. Tanto comandos quanto opções expõem uma propriedade Aliases. 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 apelidos de forma curta.

Diferenciar maiúsculas de minúsculas

Nomes e aliases de comando e opções diferenciam maiúsculas de minúsculas por padrão de acordo com a convenção POSIX, e System.CommandLine segue essa convenção. Se você quiser que sua CLI não diferencie maiúsculas de minúsculas, defina aliases para as várias alternativas de maiúsculas e minúsculas. Por exemplo, --additional-probing-path poderia ter aliases --Additional-Probing-Path e --ADDITIONAL-PROBING-PATH.

Em algumas ferramentas de linha de comando, uma diferença no uso de maiúsculas e minúsculas especifica uma diferença na função. Por exemplo, git clean -X se comporta de forma diferente de git clean -x. A CLI do .NET é escrita em letras minúsculas.

A diferenciação de maiúsculas e minúsculas não se aplica a valores de argumento em opções baseadas em enumerações. Os nomes de enumeração têm correspondência independentemente do uso de maiúsculas e minúsculas.

O token --

A convenção POSIX interpreta o token de traço duplo (--) como um mecanismo de escape. Tudo o que segue o token de traço duplo é interpretado como argumentos para o comando. Essa funcionalidade pode ser usada para enviar argumentos semelhantes a opções, pois impede que eles sejam interpretados como opções.

Suponha que o myapp use um message argumento e você queira que o valor 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 será interpretado como um argumento. No entanto, se o aplicativo tiver uma --interactive opção, essa entrada será interpretada como referência a essa opção.

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

myapp -- --interactive
      ^^

System.CommandLine dá suporte a essa funcionalidade de traço duplo.

Delimitadores de argumento de opção

System.CommandLine permite que você use um espaço, '=' ou ':' como 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ê estiver especificando um alias de opção de caractere único. Por exemplo, os seguintes comandos são equivalentes:

myapp -vquiet
myapp -v quiet

System.CommandLine dá suporte a essa sintaxe por padrão.

Arity de argumento

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

Arity é expresso com um valor mínimo e um valor máximo, como ilustra a tabela a seguir:

Mín Máximo Validade de exemplo Exemplo
0 0 Válido: --file
Inválido: --file a.json
Inválido: --file a.json --file b.json
0 1 Válido: --bandeira
Válido: --flag verdadeiro
Válido: --flag falso
Inválido: --flag false --flag false
1 1 Válido: --file a.json
Inválido: --file
Inválido: --file a.json --file b.json
0 n Válido: --file
Válido: --file a.json
Válido: --file a.json --file b.json
1 n Válido: --file a.json
Válido: --file a.json b.json
Inválido: --file

System.CommandLine tem um struct ArgumentArity para definir a aridade, com os seguintes valores:

  • Zero - Nenhum valor permitido.
  • ZeroOrOne - Pode ter um valor ou nenhum valor.
  • ExactlyOne - Deve ter um valor.
  • ZeroOrMore - Pode ter um valor, vários valores ou nenhum valor.
  • 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 Arity padrão
Boolean ArgumentArity.ZeroOrOne
Tipos de coleção ArgumentArity.ZeroOrMore
Todo o resto ArgumentArity.ExactlyOne

Substituições de opção

Se o máximo de arity for 1, System.CommandLine ainda poderá ser configurada para aceitar várias instâncias de uma opção. Nesse caso, a última instância de uma opção repetida substitui todas as 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, ao chamar um comando, você pode repetir um nome de opção para especificar vários argumentos para uma opção que tenha aridade máxima maior que uma.

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

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

myapp --items one two three

A mesma configuração terá um efeito diferente se a aridade máxima do argumento for 1. Ele permite que você repita uma opção, mas usa 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

Agrupamento de opções

O POSIX recomenda que você dê suporte ao agrupamento de opções de caractere único, 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. Somente 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 no 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 somente à opção -c.

Opções boolianas (sinalizadores)

Se true ou false for passado para uma opção que tenha um bool argumento, ele será analisado conforme o esperado. Mas uma opção cujo tipo bool de argumento normalmente não exige que um argumento seja especificado. As opções boolianas, às vezes chamadas de "sinalizadores", normalmente têm uma aridade de ZeroOrOne. A presença do nome da opção na linha de comando, sem nenhum argumento a seguir, resulta em um valor padrão de true. A ausência do nome da opção na entrada de linha de comando resulta em um valor de false. Se o myapp comando imprimir o valor de uma opção booliana chamada --interactive, a seguinte entrada 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 com base System.CommandLine fornecem automaticamente o número de versão em resposta à opção --version usada com o comando raiz. 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. Os arquivos de resposta são um recurso de System.CommandLine que é útil em dois cenários:

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

Para usar um arquivo de resposta, insira o nome do arquivo prefixado por um @ sinal onde você quiser inserir comandos, opções e argumentos na linha. A extensão de 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 de sample1.rsp:

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

Conteúdo de sample2.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 dois tokens, Bom e dia!.
  • Vários tokens entre aspas são interpretados como um único token. Uma linha que contém "Bom dia!" é tratada como um token, Bom dia!.
  • Qualquer texto entre um # símbolo e o final da linha é tratado como um comentário e ignorado.
  • Os 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 sintactico chamado diretiva representada pelo Directive tipo. Por exemplo, a [diagram] diretiva é uma diretiva interna. 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/> ] ] ]

A finalidade das diretivas é fornecer funcionalidade transversal que pode ser aplicada nos aplicativos de linha de comando. Como as diretivas são sintaticamente distintas da própria sintaxe do aplicativo, elas podem fornecer funcionalidades que se aplicam a vários 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.
  • Fica entre colchetes.
  • 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 são embutidas:

A diretiva [diagram]

Tanto usuários quanto 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 com o uso de colchetes.
  • Para o resultado da opção [ --delay !<not-an-int> ], ! 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 é sinalizado ! na 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 essa opção. O asterisco indica que o valor é o padrão.
  • ???--> aponta para uma entrada que não foi correspondida a nenhum dos comandos ou opções do aplicativo.

Sugerir diretiva

A [suggest] diretiva permite que você pesquise comandos quando não souber o comando exato.

dotnet [suggest] buil

build
build-server
msbuild

Consulte também

  • Last updated on