Introducción a la sintaxis de línea de comandos de System.CommandLine

Importante

System.CommandLine se encuentra actualmente en versión preliminar y esta documentación es para la versión 2.0 beta 4. Parte de la información hace referencia a la versión preliminar del producto, que puede haberse modificado sustancialmente antes de lanzar la versión definitiva. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.

En este artículo se explica la sintaxis de línea de comandos que System.CommandLine reconoce. La información es útil para los usuarios y para los desarrolladores de aplicaciones de línea de comandos de .NET, incluida la CLI de .NET.

Tokens

System.CommandLine analiza la entrada de la línea de comandos en tokens, que son cadenas delimitadas por espacios. Por ejemplo, considere la siguiente línea de comandos:

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

La aplicación dotnet analiza esta entrada en tokens tool, install, dotnet-suggest, --global, --verbosity y quiet.

Los tokens se interpretan como comandos, opciones o argumentos. La aplicación de línea de comandos que se invoca determina cómo se interpretan los tokens después del primero. En la tabla siguiente se muestra cómo System.CommandLine interpreta el ejemplo anterior:

Token	Analizado como
tool	Subcomando
install	Subcomando
dotnet-suggest	Argumento del comando install
--global	Opción del comando install
--verbosity	Opción del comando install
quiet	Argumento de la opción --verbosity

Un token puede contener espacios si está entre comillas ("). Este es un ejemplo:

dotnet tool search "ef migrations add"

Comandos

Un comando de la entrada de la línea de comandos es un token que especifica una acción o define un grupo de acciones relacionadas. Por ejemplo:

• En dotnet run, run es un comando que especifica una acción.
• En dotnet tool install, install es un comando que especifica una acción y tool es un comando que especifica un grupo de comandos relacionados. Hay otros comandos relacionados con herramientas, como tool uninstall, tool list y tool update.

Comandos raíz

El comando raíz es el que especifica el nombre del ejecutable de la aplicación. Por ejemplo, el comando dotnet especifica el ejecutable dotnet.exe.

Subcomandos

La mayoría de las aplicaciones de línea de comandos admiten subcomandos, también conocidos como verbos. Por ejemplo, el comando dotnet tiene un subcomando run que se invoca escribiendo dotnet run.

Los subcomandos pueden tener sus propios subcomandos. En dotnet tool install, install es un subcomando de tool.

Opciones

Una opción es un parámetro con nombre que se puede pasar a un comando. Las CLI de POSIX suelen llevar delante del nombre de opción dos guiones (--). En el ejemplo siguiente se muestran dos opciones:

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

Como se muestra en este ejemplo, el valor de la opción puede ser explícito (quiet para --verbosity) o implícito (nada sigue a --global). Las opciones que no tienen ningún valor especificado suelen ser parámetros booleanos cuyo valor predeterminado es true si se especifica la opción en la línea de comandos.

En algunas aplicaciones de línea de comandos de Windows, una opción se identifica mediante una barra diagonal inicial (/) con el nombre de la opción. Por ejemplo:

msbuild /version
        ^------^

System.CommandLine admite convenciones de prefijo POSIX y Windows. Al configurar una opción, especifique el nombre de la opción, incluido el prefijo.

Argumentos

Un argumento es un valor pasado a una opción o a un comando. En los ejemplos siguientes se muestra un argumento para la opción verbosity y un argumento para el comando build.

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

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

Los argumentos pueden tener valores predeterminados que se aplican si no se proporciona ningún argumento explícitamente. Por ejemplo, muchas opciones son parámetros booleanos implícitamente con un valor predeterminado de true cuando el nombre de la opción está en la línea de comandos. Los siguientes ejemplos de línea de comandos son equivalentes:

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

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

Algunas opciones tienen argumentos requeridos. Por ejemplo, en la CLI de .NET, --output requiere un argumento de nombre de carpeta. Si no se proporciona el argumento, se produce un error en el comando.

Los argumentos pueden tener tipos esperados, y System.CommandLine muestra un mensaje de error si no se puede analizar un argumento en el tipo esperado. Por ejemplo, se produce un error en el siguiente comando porque "silent" no es uno de los valores válidos de --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

Los argumentos también tienen expectativas sobre cuántos valores se pueden proporcionar. En la sección sobre la aridad de los argumentos se proporcionan ejemplos.

Orden de las opciones y los argumentos

Puede proporcionar opciones antes que argumentos o argumentos antes que opciones en la línea de comandos. Los siguientes comandos son equivalentes:

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

Las opciones se pueden especificar en cualquier orden. Los siguientes comandos son 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

Cuando hay varios argumentos el orden importa. Los siguientes comandos no son necesariamente equivalentes:

myapp argument1 argument2
myapp argument2 argument1

Estos comandos pasan una lista con los mismos valores al código del controlador de comandos, pero difieren en el orden de los valores, lo que podría dar lugar a resultados diferentes.

Alias

En POSIX y Windows, es habitual que algunos comandos y opciones tengan alias. Normalmente son formas cortas que resultan más fáciles de escribir. Los alias también se pueden usar para otros fines, como simular la no distinción entre mayúsculas y minúsculas y admitir ortografías alternativas de una palabra.

Las formas cortas de POSIX suelen tener un único guión inicial seguido de un solo carácter. Los siguientes comandos son equivalentes:

dotnet build --verbosity quiet
dotnet build -v quiet

El estándar GNU recomienda alias automáticos. Es decir, puede escribir cualquier parte de un nombre de opción o comando de formato largo, que se aceptará. Este comportamiento convertiría en equivalentes las siguientes líneas de comandos:

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 no admite alias automáticos.

Distinción entre mayúsculas y minúsculas

Los nombres de comandos y opciones y los alias distinguen mayúsculas de minúsculas de manera predeterminada según la convención POSIX, y System.CommandLine sigue esta convención. Si quiere que la CLI no distinga mayúsculas de minúsculas, defina alias para las distintas alternativas de uso de mayúsculas y minúsculas. Por ejemplo, --additional-probing-path podría tener los alias --Additional-Probing-Path y --ADDITIONAL-PROBING-PATH.

En algunas herramientas de línea de comandos, una diferencia en el uso de mayúsculas y minúsculas especifica una diferencia de función. Por ejemplo, git clean -X se comporta de forma diferente a git clean -x. La CLI de .NET está en minúsculas en su totalidad.

La distinción entre mayúsculas y minúsculas no se aplica a los valores de argumento de las opciones basadas en enumeraciones. Los nombres de enumeraciones se emparejan independientemente del uso de mayúsculas y minúsculas.

El token --

La convención POSIX interpreta el token de guión doble (--) como un mecanismo de escape. Todo lo que sigue al token de guión doble se interpreta como argumentos del comando. Esta funcionalidad se puede usar para enviar argumentos que parezcan opciones, ya que evita que se interpreten como opciones.

Imagine que myapp toma un argumento message y quiere que el valor de message sea --interactive. La siguiente línea de comandos podría dar resultados inesperados.

myapp --interactive

Si myapp no tiene una opción --interactive, el token --interactive se interpreta como un argumento. Pero si la aplicación tiene una opción --interactive, esta entrada se interpreta como referencia a esa opción.

La siguiente línea de comandos usa el token de guión doble para establecer el valor del argumento message en "--interactive":

myapp -- --interactive
      ^^

System.CommandLine admite esta funcionalidad de guión doble.

Delimitadores de argumento y opción

System.CommandLine permite usar un espacio, "=" o ":" como delimitador entre un nombre de opción y su argumento. Por ejemplo, los comandos siguientes son equivalentes:

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

Una convención POSIX permite omitir el delimitador cuando se especifica un alias de opción de un solo carácter. Por ejemplo, los comandos siguientes son equivalentes:

myapp -vquiet
myapp -v quiet

System.CommandLine admite esta sintaxis de manera predeterminada.

Aridad de los argumentos

La aridad de un argumento de opción o comando es el número de valores que se pueden pasar si se especifica esa opción o comando.

La aridad se expresa con un valor mínimo y un valor máximo, como se muestra en la tabla siguiente:

Min	Max	Validez del ejemplo	Ejemplo
0	0	Válido:	--file
		No válido:	--file a.json
		No válido:	--file a.json --file b.json
0	1	Válido:	--flag
		Válido:	--flag true
		Válido:	--flag false
		No válido:	--flag false --flag false
1	1	Válido:	--file a.json
		No válido:	--file
		No vá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
		No válido:	--file

System.CommandLine tiene una estructura ArgumentArity para definir la aridad con los siguientes valores:

• Zero: no se permiten valores.
• ZeroOrOne: puede tener un valor, puede no tener valores.
• ExactlyOne: debe tener un valor.
• ZeroOrMore: puede tener un valor, varios valores o ningún valor.
• OneOrMore: puede tener varios valores, debe tener al menos un valor.

A menudo, la aridad se puede deducir del tipo. Por ejemplo, una opción int tiene una aridad ExactlyOne y una opción List<int> tiene una aridad OneOrMore.

Invalidaciones de opciones

Si la aridad máxima es 1, System.CommandLine todavía se puede configurar para aceptar varias instancias de una opción. En ese caso, la última instancia de una opción repetida invalida a las instancias anteriores. En el ejemplo siguiente, el valor 2 se pasaría al comando myapp.

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

Varios argumentos

Si la aridad máxima es más de uno, System.CommandLine se puede configurar para aceptar varios argumentos para una opción sin repetir el nombre de la opción.

En el ejemplo siguiente, la lista que se pasa al comando myapp contendría "a", "b", "c" y "d":

myapp --list a b c --list d

Agrupación de opciones

POSIX recomienda que se admita la agrupación de opciones de un solo carácter, también conocida como apilamiento. Las opciones agrupadas son alias de opción de un solo carácter especificados juntos tras un prefijo de un solo guion. Solo la última opción puede especificar un argumento. Por ejemplo, las siguientes líneas de comandos son equivalentes:

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

Si se proporciona un argumento después de una agrupación de opciones, se aplica a la última opción de la agrupación. Las siguientes líneas de comandos son equivalentes:

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

En ambas variantes de este ejemplo, el argumento arg solo se aplicaría a la opción -c.

Opciones booleanas (marcas)

Si true o false se pasa a una opción que tiene un argumento bool, se analiza según lo previsto. Pero una opción cuyo tipo de argumento es bool normalmente no requiere que se especifique un argumento. Las opciones booleanas, a veces conocidas como "marcas", suelen tener una aridad de ZeroOrOne. La presencia del nombre de opción en la línea de comandos, sin ir seguido de ningún argumento, da como resultado un valor predeterminado de true. La ausencia del nombre de opción en la entrada de la línea de comandos da como resultado un valor de false. Si el comando myapp imprime el valor de una opción booleana de nombre --interactive, la siguiente entrada crea la siguiente salida:

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

False
True
False
True

La opción --help

Las aplicaciones de línea de comandos suelen proporcionar una opción para mostrar una breve descripción de los comandos, las opciones y los argumentos disponibles. System.CommandLine genera automáticamente la salida de ayuda. Por ejemplo:

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.

Es posible que los usuarios de aplicaciones estén acostumbrados a diferentes formas de solicitar ayuda en distintas plataformas, por lo que las aplicaciones basadas en System.CommandLine responden a muchas formas de solicitar ayuda. Los siguientes comandos son todos equivalentes:

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

La salida de ayuda no muestra necesariamente todos los comandos, los argumentos y las opciones disponibles. Algunos de ellos pueden estar ocultos, lo que significa que no aparecen en la salida de ayuda aunque se pueden especificar en la línea de comandos.

La opción --version

Las aplicaciones basadas en System.CommandLine proporcionan automáticamente el número de versión en respuesta a la opción --version usada con el comando raíz. Por ejemplo:

dotnet --version

6.0.100

Archivos de respuesta

Un archivo de respuesta es un archivo que contiene un conjunto de tokens para una aplicación de línea de comandos. Los archivos de respuesta son una característica de System.CommandLine que resulta útil en dos escenarios:

• Para invocar a una aplicación de línea de comandos mediante la especificación de una entrada que es mayor que el límite de caracteres del terminal.
• Para invocar al mismo comando repetidamente sin volver a escribir toda la línea.

Para usar un archivo de respuesta, escriba el nombre de archivo con el prefijo @ en el lugar de la línea donde quiera insertar comandos, opciones y argumentos. La extensión de archivo .rsp es una convención habitual, pero se puede usar cualquier extensión de archivo.

Las líneas siguientes son equivalentes:

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

Contenido de sample1.rsp:

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

Contenido de sample2.rsp:

--no-restore

Estas son las reglas de sintaxis que determinan cómo se interpreta el texto de un archivo de respuesta:

• Los tokens se delimitan mediante espacios. Una línea que contiene Buenos días se trata como dos tokens, Buenos y días.
• Varios tokens entre comillas se interpretan como un único token. Una línea que contiene Buenos días se trata como un token, Buenos días.
• Cualquier texto entre un símbolo # y el final de la línea se trata como un comentario y se omite.
• Los tokens con el prefijo @ pueden hacer referencia a archivos de respuesta adicionales.
• El archivo de respuesta puede tener varias líneas de texto. Las líneas se concatenan y se interpretan como una secuencia de tokens.

Directivas

System.CommandLine incorpora un elemento sintáctico que se conoce como directiva. La directiva [parse] es un ejemplo. Al incluir [parse] después del nombre de la aplicación, System.CommandLine muestra un diagrama del resultado del análisis en lugar de invocar a la aplicación de línea de comandos:

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

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

El propósito de las directivas es proporcionar funcionalidad transversal que se pueda aplicar en las aplicaciones de línea de comandos. Dado que las directivas son sintácticamente distintas de la propia sintaxis de la aplicación, pueden proporcionar funcionalidad que se aplique en todas las aplicaciones.

Una directiva debe cumplir las siguientes reglas de sintaxis:

• Es un token de la línea de comandos que viene después del nombre de la aplicación, pero antes de cualquier subcomando u opción.
• Está entre corchetes.
• No contiene espacios.

Una directiva no reconocida se omite sin provocar ningún error de análisis.

Una directiva puede incluir un argumento, separado del nombre de la directiva por dos puntos.

Las siguientes directivas están integradas:

• [parse]
• [suggest]

La directiva [parse]

Tanto a los usuarios como a los desarrolladores les puede resultar útil para ver cómo interpreta una aplicación una entrada determinada. Una de las características predeterminadas de una aplicación System.CommandLine es la directiva [parse], que permite obtener una vista previa del resultado de la entrada de comandos de análisis. Por ejemplo:

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

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

En el ejemplo anterior:

• El comando (myapp), sus opciones secundarias y los argumentos de esas opciones se agrupan mediante corchetes.
• En el resultado de la opción [ --delay !<not-an-int> ], ! indica un error de análisis. El valor not-an-int de una opción int no se puede analizar en el tipo esperado. El error también se marca mediante ! delante del comando que contiene la opción errónea: ![ myapp....
• En el resultado de la opción *[ --fgcolor <White> ], la opción no se ha especificado en la línea de comandos, por lo que se ha usado el valor predeterminado configurado. White es el valor efectivo de esta opción. El asterisco indica que el valor es el predeterminado.
• ???--> apunta a la entrada no emparejada con ninguno de los comandos u opciones de la aplicación.

La directiva [suggest]

La directiva [suggest] permite buscar comandos cuando no conoce el comando exacto.

dotnet [suggest] buil

build
build-server
msbuild

Guía de diseño

En las secciones siguientes se presentan instrucciones que se recomienda seguir al diseñar una CLI. Piense en lo que la aplicación espera en la línea de comandos, igual que lo que espera un servidor de API de REST en la dirección URL. Unas reglas coherentes para las API de REST es lo que las hace útiles a los desarrolladores de aplicaciones cliente. De la misma manera, los usuarios de las aplicaciones de línea de comandos van a tener una mejor experiencia si el diseño de la CLI sigue patrones comunes.

Una vez creada una CLI, es difícil cambiarla, especialmente si los usuarios la han usado en scripts que esperan seguir ejecutando. Estas instrucciones se desarrollaron después de la CLI de .NET, que no siempre las sigue. Se está actualizando la CLI de .NET para seguir las instrucciones sin incorporar cambios importantes. Un ejemplo de este trabajo es el nuevo diseño de dotnet new en .NET 7.

Comandos y subcomandos

Si un comando tiene subcomandos, el comando debe actuar como un área, o un identificador de agrupación, de los subcomandos, en lugar de especificar una acción. Al invocar a la aplicación, se especifican el comando de agrupación y uno de sus subcomandos. Por ejemplo, intente ejecutar dotnet tool: aparecerá un mensaje de error porque el comando tool solo identifica un grupo de subcomandos relacionados con herramientas, como install y list. Puede ejecutar dotnet tool install, pero dotnet tool por sí mismo estaría incompleto.

Una de las formas en que la definición de áreas ayuda a los usuarios es que organiza la salida de ayuda.

Dentro de una CLI suele haber un área implícita. Por ejemplo, en la CLI de .NET, el área implícita es el proyecto y, en la CLI de Docker, la imagen. Como resultado, puede usar dotnet build sin incluir un área. Piense si la CLI tiene un área implícita. Si la tiene, piense si va a permitir que el usuario la incluya o la omita opcionalmente, como en docker build y docker image build. Si opcionalmente permite que el usuario escriba el área implícita, también tiene automáticamente ayuda y finalización con tabulación para esta agrupación de comandos. Para proporcionar el uso opcional del grupo implícito, defina dos comandos que realicen la misma operación.

Opciones como parámetros

Las opciones deben proporcionar parámetros a los comandos, en lugar de especificar las propias acciones. Se trata de un principio de diseño recomendado, aunque System.CommandLine no siempre lo siga (--help muestra información de ayuda).

Alias abreviados

En general, se recomienda minimizar el número de alias de opción abreviados definidos.

En concreto, evite usar cualquiera de los siguientes alias de forma diferente a su uso común en la CLI de .NET y otras aplicaciones de línea de comandos de .NET:

• -i para --interactive

  Esta opción indica al usuario que puede que se le pidan entradas para preguntas cuya respuesta necesita el comando. Por ejemplo, solicitar un nombre de usuario. La CLI se puede usar en scripts, por lo que debe tener cuidado al preguntar a los usuarios que no han especificado este modificador.

• -o para --output

  Algunos comandos generan archivos como resultado de su ejecución. Esta opción debe usarse para ayudar a determinar dónde se deben ubicar esos archivos. En los casos en los que se crea un solo archivo, esta opción debe ser una ruta de acceso de archivo. En los casos en los que se crean muchos archivos, esta opción debe ser una ruta de acceso de directorio.

• -v para --verbosity

  Los comandos suelen proporcionar una salida al usuario en la consola; esta opción se usa para especificar la cantidad de salida que solicita el usuario. Para obtener más información, vea La opción --verbosity más adelante en este artículo.

También hay algunos alias con uso común limitado a la CLI de .NET. Puede usar estos alias para otras opciones de las aplicaciones, pero sea consciente de la posibilidad de confusión.

• -c para --configuration

  Esta opción suele referirse a una configuración de compilación con nombre, como Debug o Release. Puede usar cualquier nombre que quiera para una configuración, pero la mayoría de las herramientas esperan uno de esos. Este valor se suele usar para configurar otras propiedades de una manera que tenga sentido para esa configuración, por ejemplo, haciendo menos optimización de código al compilar la configuración Debug. Tenga en cuenta esta opción si el comando tiene diferentes modos de funcionamiento.

• -f para --framework

  Esta opción se usa para seleccionar un único moniker de la plataforma de destino (TFM) en el que ejecutar, así que si la aplicación de la CLI tiene un comportamiento diferente en función del TFM elegido, debe admitir esta marca.

• -p para --property

  Si la aplicación finalmente invoca a MSBuild, el usuario suele necesitar personalizar esa llamada de alguna manera. Esta opción permite proporcionar propiedades de MSBuild en la línea de comandos y pasarlas a la llamada subyacente de MSBuild. Si la aplicación no usa MSBuild pero necesita un conjunto de pares clave-valor, considere la posibilidad de usar este mismo nombre de opción para aprovechar las expectativas de los usuarios.

• -r para --runtime

  Si la aplicación se puede ejecutar en diferentes runtimes, o tiene lógica específica del runtime, considere la posibilidad de admitir esta opción como una manera de especificar un identificador de entorno de ejecución. Si la aplicación admite --runtime, considere la posibilidad de admitir --os y también --arch. Estas opciones permiten especificar solo el sistema operativo o los elementos de la arquitectura del RID, dejando que la parte no especificada se determine desde la plataforma actual. Para obtener más información, vea dotnet publish.

Nombres cortos

Cree nombres de comandos, opciones y argumentos lo más cortos y fáciles de escribir posible. Por ejemplo, si class está lo suficientemente claro, no cree el comando classification.

Nombres en minúscula

Defina nombres en minúscula únicamente, aunque puede crear alias en mayúscula para que los comandos o las opciones no distingan mayúsculas de minúsculas.

Nombres de grafía kebab

Use el caso kebab para distinguir palabras. Por ejemplo: --additional-probing-path.

Pluralización

En una aplicación, sea coherente con los plurales. Por ejemplo, no combine nombres en plural y singular en las opciones que puedan tener varios valores (aridad máxima mayor que uno):

Nombres de opción	Coherencia
--additional-probing-paths y --sources	✔️
--additional-probing-path y --source	✔️
--additional-probing-paths y --source	❌
--additional-probing-path y --sources	❌

Verbos frente a sustantivos

Use verbos en lugar de sustantivos en los comandos que hagan referencia a acciones (aquellos sin subcomandos subyacentes), por ejemplo: dotnet workload remove, no dotnet workload removal. Use sustantivos en lugar de verbos en las opciones, por ejemplo: --configuration, no --configure.

La opción --verbosity

Las aplicaciones System.CommandLine suelen ofrecer una opción --verbosity que especifica la cantidad de salida que se envía a la consola. Estas son las cinco configuraciones estándar:

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

Estos son los nombres estándar, pero las aplicaciones existentes a veces usan Silent en lugar de Quiet, y Trace, Debug o Verbose en lugar de Diagnostic.

Cada aplicación define sus propios criterios que determinan lo que se muestra en cada nivel. Normalmente, una aplicación solo necesita tres niveles:

• Quiet
• Normal
• Diagnostic

Aunque una aplicación no necesite cinco niveles diferentes, la opción debe seguir definiendo las cinco configuraciones. En ese caso, Minimal y Normal generan la misma salida y, así mismo, Detailed y Diagnostic son iguales. Esto permite a los usuarios simplemente escribir aquello con lo que están familiarizados para que se emplee la mejor opción.

La expectativa de Quiet es que no se muestre ninguna salida en la consola. Pero si una aplicación ofrece un modo interactivo, la aplicación debe realizar una de las siguientes alternativas:

• Mostrar mensajes de entrada cuando se especifique --interactive, aunque --verbosity sea Quiet.
• No permitir el uso de --verbosity Quiet y --interactive juntos.

De lo contrario, la aplicación espera la entrada sin indicar al usuario lo que está esperando. Parece que la aplicación se ha congelado y el usuario no tiene ni idea de que está esperando la entrada.

Si define alias, use -v para --verbosity y cree -v sin un argumento de alias para --verbosity Diagnostic. Use -q para --verbosity Quiet.

CLI de .NET y convenciones POSIX

La CLI de .NET no sigue de forma coherente todas las convenciones POSIX.

Guión doble

Varios comandos de la CLI de .NET tienen una implementación especial del token de guión doble. En el caso de dotnet run, dotnet watch y dotnet tool run, los tokens que siguen a -- se pasan a la aplicación que ejecuta el comando. Por ejemplo:

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

En este ejemplo, la opción --project se pasa al comando dotnet run, y la opción --message con su argumento se pasa como una opción de línea de comandos a myapp cuando se ejecuta.

El token -- no siempre es necesario para pasar opciones a una aplicación que se ejecuta mediante dotnet run. Sin el guión doble, el comando dotnet run pasa automáticamente a la aplicación que se ejecuta cualquier opción no reconocida como en aplicación a dotnet run o a MSBuild. Por lo tanto, las siguientes líneas de comandos son equivalentes porque dotnet run no reconoce los argumentos ni las opciones:

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

Omisión del delimitador de opción a argumento

La CLI de .NET no admite la convención POSIX que permite omitir el delimitador cuando se especifica un alias de opción de un solo carácter.

Varios argumentos sin repetir el nombre de opción

La CLI de .NET no acepta varios argumentos para una opción sin repetir el nombre de opción.

Opciones booleanas

En la CLI de .NET, algunas opciones booleanas dan lugar al mismo comportamiento cuando se pasa false que cuando se pasa true. Este comportamiento se manifiesta cuando el código de la CLI de .NET que implementa la opción solo comprueba la presencia o ausencia de la opción y omite el valor. Un ejemplo es --no-restore para el comando dotnet build. Pase no-restore false y la operación de restauración se omitirá lo mismo que cuando se especifica no-restore true o no-restore.

Caso kebab

En algunos casos, la CLI de .NET no usa el caso kebab para nombres de argumento, opción o comando. Por ejemplo, hay una opción de la CLI de .NET de nombre --additionalprobingpath en lugar de --additional-probing-path.

Consulte también

• Guía de diseño de la CLI de código abierto
• Estándares GNU
• Información general de System.CommandLine
• Tutorial: Introducción a System.CommandLine