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

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

Tokens

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

Essa entrada é analisada dotnet pelo aplicativo em tokens tool, install, dotnet-suggest, --global, --verbositye 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:

Token	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 ("). Eis 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.

Comandos raiz

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

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 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 passado para um comando. As CLIs POSIX 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 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 suporta convenções de prefixo POSIX e Windows. Ao configurar uma opção, você especifica o nome da opção, incluindo o prefixo.

Argumentos

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

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

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

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

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

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

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á.

Os argumentos podem ter tipos esperados e System.CommandLine exibem uma mensagem de erro se um argumento não puder ser analisado no tipo esperado. Por exemplo, os seguintes erros de comando porque "silent" não é 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 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 seguintes comandos não são necessariamente equivalentes:

myapp argument1 argument2
myapp argument2 argument1

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

Aliases

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.

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

Os nomes e aliases de comandos e opções diferenciam maiúsculas de minúsculas por padrão, de acordo com a convenção POSIX, e System.CommandLine seguem 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 é toda minúscula.

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

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, 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 seja .--interactivemessage 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:

Mín.	Max	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 um ArgumentArity struct para definir aridade, com os seguintes valores:

• Zero - Não são permitidos valores.
• ZeroOrOne - Pode ter um valor, pode não ter valores.
• 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.

A aridade pode muitas vezes ser inferida a partir do tipo. Por exemplo, uma int opção tem arity de ExactlyOne, e uma List<int> opção tem arity OneOrMore.

Substituições de opção

Se a aridade máxima for 1, System.CommandLine ainda pode ser configurado para aceitar várias instâncias de uma 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

Múltiplos argumentos

Se o máximo de aridade for mais de um, System.CommandLine pode ser configurado para aceitar vários argumentos para uma opção sem repetir o nome da opção.

No exemplo a seguir, a lista passada para o myapp comando conteria "a", "b", "c" e "d":

myapp --list a b c --list d

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

A opção --help

Os aplicativos de linha de comando geralmente fornecem uma opção para exibir uma breve descrição dos comandos, opções e argumentos disponíveis. System.CommandLine gera automaticamente saída de 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 utilizadores de aplicações podem estar habituados a diferentes formas de solicitar ajuda em diferentes plataformas, pelo que as aplicações baseadas respondem System.CommandLine a muitas formas 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 não aparecem na saída de ajuda, mas podem ser especificados na linha de comando.

A opção --version

Os aplicativos criados automaticamente System.CommandLine fornecem o número da versão em resposta à --version opção 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. Os arquivos de System.CommandLine resposta são um recurso que é ú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!" é tratado como um só 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 denominado diretiva. A [parse] diretiva é 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/> ] ] ]

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:

• [parse]
• [suggest]

A [parse] 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 [parse] diretiva, 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 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 é sinalizado por ! na frente do comando que contém a opção errored: ![ 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.

A [suggest] diretiva

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

dotnet [suggest] buil

build
build-server
msbuild

Orientação de design

As seções a seguir apresentam orientações que recomendamos que você siga ao criar uma CLI. Pense no que seu aplicativo espera na linha de comando como 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 para 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 criar uma CLI, é difícil alterá-la, especialmente se os usuários tiverem usado a CLI em scripts que esperam continuar executando. As diretrizes aqui foram desenvolvidas após a CLI do .NET e nem sempre seguem essas diretrizes. Estamos atualizando a CLI do .NET onde podemos fazê-lo sem introduzir alterações de quebra. Um exemplo desse trabalho é o novo design do dotnet new .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, você especifica o comando de agrupamento e um de seus subcomandos. Por exemplo, tente executar dotnet toolo , e você receberá uma mensagem de erro porque o tool comando identifica apenas um grupo de subcomandos relacionados à ferramenta, como install e list. Você pode executar dotnet tool install, mas dotnet tool por si só seria incompleto.

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

Dentro de uma CLI há muitas vezes 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 deve permitir que o usuário opcionalmente inclua ou omita como em docker build e docker image build. Se você opcionalmente permitir que a área implícita seja digitada pelo usuário, você também terá automaticamente ajuda e preenchimento de guias 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. Este é um princípio de design recomendado, embora nem sempre seja seguido por System.CommandLine (--help exibe informações de ajuda).

Aliases de forma curta

Em geral, recomendamos que você minimize o número de aliases de opção de forma curta que você definir.

Em particular, evite usar qualquer um dos seguintes aliases de forma diferente de seu 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 ser solicitado a inserir entradas para perguntas que o comando precisa ser respondido. Por exemplo, solicitando um nome de usuário. Sua CLI pode ser usada em scripts, portanto, tenha cuidado ao avisar os usuários que não especificaram essa opção.

• -o para --output.

  Alguns comandos produzem ficheiros como resultado da sua execução. Essa opção deve ser usada para ajudar a determinar onde esses arquivos devem ser 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; Esta opção é usada para especificar a quantidade de saída que o usuário solicita. Para obter mais informações, consulte A --verbosity opção 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 compilação nomeada, como Debug ou Release. Você pode usar qualquer nome que quiser para uma configuração, mas a maioria das ferramentas está esperando um desses. Essa configuração geralmente é usada para configurar outras propriedades de uma maneira que faça sentido para essa configuração — por exemplo, fazer menos otimização de código ao criar a Debug configuração. Considere esta opção se o seu comando tiver diferentes modos de operação.

• -f para --framework

  Essa opção é usada para selecionar um único Target Framework Moniker (TFM) para executar, portanto, se seu aplicativo CLI tiver um comportamento diferente com base no TFM escolhido, você deverá oferecer suporte a esse sinalizador.

• -p para --property

  Se seu aplicativo eventualmente invocar o MSBuild, o usuário geralmente precisará personalizar essa chamada de alguma forma. Essa opção permite que as propriedades do MSBuild sejam fornecidas na linha de comando e passadas para a chamada subjacente do MSBuild. Se seu aplicativo não usa o MSBuild, mas precisa de um conjunto de pares chave-valor, considere usar esse mesmo nome de opção para aproveitar as expectativas dos usuários.

• -r para --runtime

  Se seu aplicativo pode ser executado em tempos de execução diferentes ou tem lógica específica de tempo de execução, considere oferecer suporte a essa opção como uma maneira de especificar um identificador de tempo de execução. Se o seu aplicativo oferecer suporte a --runtime, considere o suporte --os e --arch também. Essas opções permitem especificar apenas as partes do sistema operacional ou da arquitetura do RID, deixando a parte não especificada para ser determinada a partir da plataforma atual. Para obter mais informações, consulte dotnet publish.

Nomes abreviados

Torne os nomes dos comandos, opções e argumentos tão curtos e fáceis de soletrar quanto possível. Por exemplo, se class for claro o suficiente, não faça o comando classification.

Nomes minúsculos

Defina nomes apenas em minúsculas, exceto que você pode criar aliases maiúsculos para tornar os comandos ou opções insensíveis a maiúsculas.

Nomes de casos de Kebab

Use o caso de 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 plurais e singulares para opções que podem ter vários valores (aridade máxima maior que um):

Nomes das opções	Consistência
--additional-probing-paths e --sources	✔️
--additional-probing-path e --source	✔️
--additional-probing-paths e --source	❌
--additional-probing-path e --sources	❌

Verbos vs. substantivos

Use verbos em vez de substantivos para comandos que se referem a ações (aqueles 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 --verbosity opção

System.CommandLine Os aplicativos geralmente oferecem uma --verbosity opção que especifica a quantidade de saída enviada para o 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
• Diagnóstico

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á a mesma produção, e DetailedDiagnostic será igualmente a mesma. Isso permite que seus usuários apenas digitem o que eles estão familiarizados, e o melhor ajuste será usado.

A expectativa é Quiet que nenhuma saída seja exibida no console. No entanto, se um aplicativo oferecer um modo interativo, o aplicativo deve 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 está esperando. Parecerá que seu aplicativo congelou e o usuário não terá ideia de que o aplicativo está esperando por entrada.

Se você definir aliases, use -v for --verbosity e faça -v sem um argumento um alias para --verbosity Diagnostic. Use -q para --verbosity Quiet.

As convenções .NET CLI e POSIX

A CLI .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 double-dash. No caso de dotnet run, , e dotnet tool run, os tokens a seguir -- são passados para o aplicativo que está sendo dotnet watchexecutado pelo comando. Por exemplo:

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

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

O -- token nem sempre é necessário para passar opções para um aplicativo que você executa usando o dotnet run. Sem o traço duplo, o dotnet run comando passa automaticamente para o aplicativo que está sendo executado quaisquer opções que não são reconhecidas como aplicáveis a dotnet run si mesmo ou ao MSBuild. Portanto, as seguintes linhas de comando são equivalentes porque dotnet run não reconhece os argumentos e opções:

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

Omissão do delimitador opção-a-argumento

A CLI .NET não suporta a 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 booleanas

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

Caso Kebab

Em alguns casos, a CLI do .NET não usa maiúsculas e minúsculas de kebab para nomes de comando, opção ou argumento. Por exemplo, há uma opção da CLI do .NET que é nomeada --additionalprobingpath em vez de --additional-probing-path.

Consulte também

• Diretrizes de design de CLI de código aberto
• Padrões GNU
• System.CommandLine Visão geral
• Tutorial: Introdução System.CommandLine