Visão geral da sintaxe de linha de comando para System.CommandLine

Artigo
06/08/2023

Importante

Atualmente, System.CommandLine está em VERSÃO PRÉVIA, e essa documentação é para a versão 2.0 beta 4. Algumas informações estão relacionadas a produtos de pré-lançamento que poderão ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

Este artigo explica a sintaxe de linha de comando que o System.CommandLine reconhece. As informações serã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 abaixo mostra como System.CommandLine interpreta o exemplo anterior:

Token	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 para a opção `--verbosity`

Um token poderá conter espaços se estiver entre aspas ("). Veja 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. Há outros comandos relacionados a ferramentas, como tool uninstall, tool list e tool update.

Comandos raiz

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

Subcomandos

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

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

Opções

Uma opção é um parâmetro nomeado que pode ser transmitido a um comando. As interfaces de linha de comando POSIX geralmente prefixam o nome da opção com dois hifens (--). O exemplo abaixo mostra duas opções:

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

Como ilustrado por este exemplo, 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.

Argumentos

Um argumento é um valor transmitido a uma opção ou a um comando. Os exemplos a seguir mostram um argumento para a opção verbosity e um argumento para o comando build.

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

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

Os argumentos podem ter valores padrão que se aplicarão 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 abaixo são equivalentes:

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

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

Algumas opções exigem 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á.

Os argumentos podem ter tipos esperados, e System.CommandLine exibe uma mensagem de erro quando um argumento não pode ser analisado no tipo esperado. Por exemplo, os seguintes erros de comando por "silencioso" não ser um dos valores válidos para --verbosity:

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

Os argumentos também têm expectativas sobre quantos valores podem ser fornecidos. Exemplos são fornecidos na seção sobre arity 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 seguintes comandos não são necessariamente equivalentes:

myapp argument1 argument2
myapp argument2 argument1

Esses comandos transmitem uma lista com os mesmos valores ao código do manipulador de comandos, mas eles diferem na ordem dos valores, o que pode levar a resultados diferentes.

Aliases

No POSIX e no Windows, é comum que alguns comandos e opções tenham aliases. Geralmente, são formas curtas, mais fáceis de digitar. Os aliases também podem ser usados para outras finalidades, como simular a falta de diferenciação de maiúsculas e minúsculas e dar suporte a ortografias alternativas de uma palavra.

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.

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 é toda em 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 que se parecem com opções, pois impede que eles sejam interpretados como opções.

Digamos que myapp use um argumento message e você queira 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 opção --interactive, o token --interactive será interpretado como um argumento. Mas se o aplicativo tiver uma opção --interactive, essa entrada será interpretada como referenciando 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 comandos abaixo 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 comandos abaixo são equivalentes:

myapp -vquiet
myapp -v quiet

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

Arity de argumento

O arity de uma opção ou argumento de comando é o número de valores que podem ser transmitidos se essa opção ou comando é especificada.

O arity é expresso com um valor mínimo e um valor máximo, como ilustra a tabela abaixo:

Mín	Max	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:	--flag
		Válido:	--flag true
		Válido:	--flag false
		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 o arity, com os seguintes valores:

Zero – Nenhum valor permitido.
ZeroOrOne – Pode ter um valor, pode não ter valores.
ExactlyOne – Precisa ter um valor.
ZeroOrMore – Pode ter um valor, vários valores ou nenhum valor.
OneOrMore – Pode ter vários valores, precisa ter pelo menos um valor.

Geralmente, o arity pode ser inferido do tipo. Por exemplo, uma opção int tem aridade de ExactlyOne, e uma opção List<int> tem arity OneOrMore.

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 transmitido ao comando myapp.

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

Vários argumentos

Se o máximo de arity for maior que um, System.CommandLine poderá ser configurado a fim de aceitar vários argumentos para uma opção sem repetir o nome da opção.

No exemplo abaixo, a lista transmitida ao comando myapp conteria "a", "b", "c" e "d":

myapp --list a b c --list d

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 transmitido a uma opção que tenha um argumento bool, ele será analisado conforme o esperado. Mas uma opção cujo tipo de argumento seja bool normalmente não exige que um argumento seja especificado. As opções boolianas, às vezes chamadas de "sinalizadores", normalmente têm uma arity 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 comando myapp imprimir o valor de uma opção booliana chamada --interactive, a entrada abaixo criará a seguinte saída:

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

False
True
False
True

A opção --help

Normalmente, os aplicativos de linha de comando fornecem uma opção para exibir uma breve descrição dos comandos, das opções e dos argumentos disponíveis. System.CommandLine gera automaticamente a saída da ajuda. Por exemplo:

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.

Os usuários do aplicativo podem estar acostumados a maneiras diferentes de solicitar ajuda em diferentes plataformas, ou seja, os aplicativos criados com System.CommandLine respondem a muitas maneiras de solicitar ajuda. Os seguintes comandos são todos equivalentes:

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

A saída da ajuda não mostra necessariamente todos os comandos, argumentos e opções disponíveis. Alguns deles podem estar ocultos, o que significa que eles não aparecem na saída da ajuda, mas podem ser especificados na linha de comando.

A opção --version

Os aplicativos criados com 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 redigitar a linha inteira.

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

As linhas de comando a seguir 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 apresenta um elemento sintático chamado diretiva. A diretiva [parse] é um exemplo. Quando você inclui [parse] 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 [parse] build --no-restore --output ./build-output/
       ^-----^

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

A finalidade das diretivas é fornecer funcionalidades de corte cruzado que podem ser aplicadas entre aplicativos de linha de comando. Como as diretivas são sintaticamente distintas da própria sintaxe do aplicativo, elas podem fornecer funcionalidade que se aplica entre aplicativos.

Uma diretiva precisa 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 qualquer subcomando 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 internas:

[parse]
[suggest]

A diretiva `[parse]`

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

myapp [parse] --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 filho e os argumentos para essas opções são agrupados com colchetes.
Para o resultado da opção [ --delay !<not-an-int> ], o ! indica um erro de análise. O valor not-an-int de uma opção int não pode ser analisado para o tipo esperado. O erro também é sinalizado pelo ! na frente do comando que contém a opção com erro: ![ myapp....
Para o resultado da opção *[ --fgcolor <White> ], a opção não foi especificada na linha de comando, ou seja, 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 a entrada que não foi correspondida com nenhum dos comandos ou opções do aplicativo.

A diretiva `[suggest]`

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

dotnet [suggest] buil

build
build-server
msbuild

Diretrizes de design

As seções a seguir apresentam diretrizes que recomendamos que você siga na criação de uma CLI. Pense no que seu aplicativo espera na linha de comando de forma semelhante ao que um servidor de API REST espera na URL. Regras consistentes para APIs REST são o que as tornam prontamente utilizáveis por desenvolvedores de aplicativos cliente. Da mesma forma, os usuários de seus aplicativos de linha de comando terão uma experiência melhor se o design da CLI seguir padrões comuns.

Depois de criada uma CLI, é difícil alterá-la, especialmente se os usuários usaram sua CLI em scripts que esperam manter em execução. As diretrizes aqui foram desenvolvidas de acordo com a CLI do .NET e nem sempre seguem essas diretrizes. Estamos atualizando a CLI do .NET para podermos fazer isso sem introduzir alterações significativas. Um exemplo desse trabalho é o novo design para dotnet new no .NET 7.

Comandos e subcomandos

Se um comando tiver subcomandos, ele deverá funcionar como uma área ou um identificador de agrupamento para os subcomandos, em vez de especificar uma ação. Ao invocar o aplicativo, especifique o comando de agrupamento e um de seus subcomandos. Por exemplo, tente executar dotnet tool; você receberá uma mensagem de erro porque o comando tool identifica apenas um grupo de subcomandos relacionados a ferramentas, como install e list. Você pode executar dotnet tool install, mas dotnet tool por si só estaria incompleto.

Uma das maneiras pelas quais a definição de áreas ajuda seus usuários é que ela organiza a saída da ajuda.

Dentro de uma CLI, muitas vezes há uma área implícita. Por exemplo, na CLI do .NET, a área implícita é o projeto e, na CLI do Docker, é a imagem. Como resultado, você pode usar dotnet build sem incluir uma área. Considere se sua CLI tem uma área implícita. Se isso acontecer, considere se deseja permitir que o usuário a inclua ou omita como em docker build e docker image build. Se, opcionalmente, permitir que a área implícita seja digitada pelo usuário, você também terá ajuda e preenchimento de guia automaticamente para esse agrupamento de comandos. Forneça o uso opcional do grupo implícito definindo dois comandos que executam a mesma operação.

Opções como parâmetros

As opções devem fornecer parâmetros para comandos, em vez de especificar ações em si. Esse é um princípio de design recomendado, embora nem sempre seja seguido pela System.CommandLine (--help exibe informações de ajuda).

Aliases de forma curta

Em geral, recomendamos minimizar o número de aliases de opção de forma curta definidos.

Em particular, evite usar qualquer um dos seguintes aliases sem ser como o uso comum na CLI do .NET e em outros aplicativos de linha de comando do .NET:

-i para --interactive.

Essa opção sinaliza ao usuário que ele pode ter que inserir entradas para perguntas que o comando precisa responder. Por exemplo, a solicitação de um nome de usuário. Sua CLI pode ser usada em scripts, ou seja, tenha cuidado ao solicitar a usuários que não especificaram essa opção.
-o para --output.

Alguns comandos produzem arquivos como resultado de sua execução. Essa opção deve ser usada para ajudar a determinar onde os arquivos devem estar localizados. Nos casos em que um único arquivo é criado, essa opção deve ser um caminho de arquivo. Nos casos em que muitos arquivos são criados, essa opção deve ser um caminho de diretório.
-v para --verbosity.

Os comandos geralmente fornecem saída para o usuário no console; essa opção é usada para especificar a quantidade de saída que o usuário solicita. Para saber mais, confira A opção --verbosity mais adiante neste artigo.

Há também alguns aliases com uso comum limitado à CLI do .NET. Você pode usar esses aliases para outras opções em seus aplicativos, mas esteja ciente da possibilidade de confusão.

-c para --configuration

Essa opção geralmente se refere a uma Configuração de Build nomeada, por exemplo, Debug ou Release. Você pode usar qualquer nome desejado para uma configuração, mas a maioria das ferramentas está esperando um desses. Essa configuração normalmente é usada para configurar outras propriedades de forma que faça sentido para essa configuração, por exemplo, fazer menos otimização de código na hora de compilar a configuração de Debug. Considere essa opção se o comando tiver modos de operação diferentes.
-f para --framework

Essa opção é usada para selecionar um único TFM (Moniker da Estrutura de Destino) para o qual executar, ou seja, se o aplicativo da CLI tiver um comportamento diferente com base em qual TFM é escolhido, você deverá dar suporte a esse sinalizador.
-p para --property

Se o aplicativo eventualmente invocar o MSBuild, o usuário precisará personalizar essa chamada de alguma forma. Essa opção permite que as propriedades do MSBuild sejam fornecidas na linha de comando e transmitidas à chamada subjacente do MSBuild. Se o aplicativo não usar o MSBuild, mas precisar de um conjunto de pares chave-valor, considere usar esse mesmo nome de opção para tirar proveito das expectativas dos usuários.
-r para --runtime

Se o aplicativo puder ser executado em runtimes diferentes ou tiver uma lógica específica do runtime, considere dar suporte a essa opção como uma forma de especificar um Identificador de Runtime. Se o aplicativo for compatível com --runtime, considere dar suporte também a --os e --arch. Essas opções permitem que você especifique apenas o sistema operacional ou as partes de arquitetura do RID, deixando a parte não especificada para ser determinada na plataforma atual. Para obter mais informações, confira dotnet publish.

Nomes curtos

Crie nomes curtos e fáceis de soletrar para comandos, opções e argumentos. Por exemplo, se class estiver claro o suficiente, não crie o comando classification.

Nomes em minúsculas

Defina nomes somente em letras minúsculas; você pode fazer aliases em maiúsculas para fazer com que os comandos ou as opções não diferenciem maiúsculas e minúsculas.

Nomes Kebab

Use kebab para distinguir palavras. Por exemplo, --additional-probing-path.

Pluralização

Dentro de um aplicativo, seja consistente na pluralização. Por exemplo, não misture nomes plural e singular em opções que possam ter vários valores (aridade máxima maior que um):

Nomes de opção	Consistência
`--additional-probing-paths` e `--sources`	✔️
`--additional-probing-path` e `--source`	✔️
`--additional-probing-paths` e `--source`	❌
`--additional-probing-path` e `--sources`	❌

Verbos X substantivos

Use verbos em vez de substantivos para comandos que se referem a ações (aquelas sem subcomandos sob eles), por exemplo: dotnet workload remove, não dotnet workload removal. E use substantivos em vez de verbos para opções, por exemplo: --configuration, não --configure.

A opção `--verbosity`

Os aplicativos System.CommandLine normalmente oferecem uma opção --verbosity que especifica a quantidade de saída enviada ao console. Aqui estão as cinco configurações padrão:

Q[uiet]
M[inimal]
N[ormal]
D[etailed]
Diag[nostic]

Esses são os nomes padrão, mas os aplicativos existentes às vezes usam Silent no lugar de Quiet, e Trace, Debugou Verbose no lugar de Diagnostic.

Cada aplicativo define seus próprios critérios que determinam o que é exibido em cada nível. Normalmente, um aplicativo só precisa de três níveis:

Quiet
Normal
Diagnostic

Se um aplicativo não precisar de cinco níveis diferentes, a opção ainda deverá definir as mesmas cinco configurações. Nesse caso, Minimal e Normal produzirão a mesma saída, e DetailedDiagnostic também será o mesmo. Isso permite que os usuários digitem apenas aquilo com que estão familiarizados, e o melhor será usado.

A expectativa de Quiet é que nenhuma saída seja exibida no console. No entanto, se um aplicativo oferecer um modo interativo, o aplicativo deverá fazer uma das seguintes alternativas:

Exibir solicitações de entrada quando --interactive for especificado, mesmo que --verbosity seja Quiet.
Não permitir o uso de --verbosity Quiet e --interactive juntos.

Caso contrário, o aplicativo aguardará a entrada sem dizer ao usuário o que ele está esperando. Vai parecer que seu aplicativo congelou e o usuário não terá ideia de que o aplicativo está aguardando entrada.

Se você definir aliases, use -v para --verbosity e torne -v sem um argumento um alias para --verbosity Diagnostic. Usar -q para --verbosity Quiet.

As convenções de POSIX e CLI do .NET

A CLI do .NET não segue consistentemente todas as convenções POSIX.

Traço duplo

Vários comandos na CLI do .NET têm uma implementação especial do token de traço duplo. No caso de dotnet run, dotnet watch e dotnet tool run, os tokens que seguem -- são transmitidos ao aplicativo que está sendo executado pelo comando. Por exemplo:

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

Neste exemplo, a opção --project é transmitida ao comando dotnet run, e a opção --message com seu argumento é transmitida como uma opção de linha de comando a myapp quando ela é executada.

Nem sempre o token -- é necessário para transmitir opções a um aplicativo que você executa usando dotnet run. Sem o traço duplo, o comando dotnet run transmite automaticamente ao aplicativo que está sendo executado todas as opções que não são reconhecidas como aplicáveis ao próprio dotnet run ou ao MSBuild. Portanto, as seguintes linhas de comando são equivalentes porque dotnet run não reconhece os argumentos e as opções:

dotnet run -- quotes read --delay 0 --fg-color red
dotnet run quotes read --delay 0 --fg-color red

Omissão do delimitador de opção para argumento

A CLI do .NET não dá suporte à convenção POSIX que permite omitir o delimitador quando você está especificando um alias de opção de caractere único.

Vários argumentos sem repetir o nome da opção

A CLI do .NET não aceita vários argumentos para uma opção sem repetir o nome da opção.

Opções boolianas

Na CLI do .NET, algumas opções boolianas resultam no mesmo comportamento quando você transmite false e quando transmite true. Esse comportamento resulta quando o código da CLI do .NET que implementa a opção verifica apenas a presença ou ausência da opção, ignorando o valor. Um exemplo é --no-restore para o comando dotnet build. Transmita no-restore false e a operação de restauração será ignorada da mesma forma que quando você especificar no-restore true ou no-restore.

Kebab

Em alguns casos, a CLI do .NET não usa kebab para nomes de comando, opção ou argumento. Por exemplo, há uma opção de CLI do .NET chamada --additionalprobingpath em vez de --additional-probing-path.

Compartilhar via