Compartir vía

Guía de diseño

En las secciones siguientes se presentan instrucciones para diseñar una CLI. Piense en lo que la aplicación espera en la línea de comandos como similar a lo que espera un servidor de API REST en la dirección URL. Las reglas coherentes para las API REST son lo que las hacen fácilmente utilizables para los desarrolladores de aplicaciones cliente. De la misma manera, los usuarios de las aplicaciones de línea de comandos tendrán 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 han usado la CLI en scripts que esperan seguir ejecutándose.

Símbolos

Comandos y subcomandos

Si un comando tiene subcomandos, el comando debe funcionar como un área o un identificador de agrupación para los subcomandos, en lugar de especificar una acción. Al invocar la aplicación, se especifica el comando de agrupación y uno de sus subcomandos. Por ejemplo, intente ejecutar dotnet tooly reciba un mensaje de error porque el tool comando 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, a menudo hay un área implícita. Por ejemplo, en la CLI de .NET, el área implícita es el proyecto y, en la CLI de Docker, es la imagen. Como resultado, puede usar dotnet build sin incluir un área. Considere si la CLI tiene un área implícita. Si lo hace, considere si desea permitir que el usuario incluya o 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. Proporcione el uso opcional del grupo implícito definiendo dos comandos que realizan 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 no siempre va seguido de System.CommandLine (--help muestra información de ayuda).

Nomenclatura

Alias en formato breve

En general, se recomienda minimizar el número de alias de opción de formato corto que defina.

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 a preguntas que el comando necesita responder. Por ejemplo, solicitar un nombre de usuario. Es posible que la CLI se use en scripts, por lo que debe tener precaución al preguntar a los usuarios que no hayan 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 único archivo, esta opción debe ser una ruta de archivo. En los casos en los que se crean muchos archivos, esta opción debe ser una ruta del directorio.

  • -v para --verbosity.

    Los comandos suelen proporcionar la 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 --verbosity opción 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 tenga en cuenta la posibilidad de confusión.

  • -c para --configuration

    Esta opción a menudo hace referencia a una configuración de compilación con nombre, como Debug o Release. Puede usar cualquier nombre que desee para una configuración, pero la mayoría de las herramientas esperan uno de ellos. Esta configuración se usa a menudo para configurar otras propiedades de una manera que tenga sentido para esa configuración, por ejemplo, realizando menos optimización de código al compilar la Debug configuración. Tenga en cuenta esta opción si el comando tiene diferentes modos de operación.

  • -f para --framework

    Esta opción se usa para seleccionar un único Moniker de la plataforma de destino (TFM) para el que se va a ejecutar, por lo 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 MSBuild, el usuario a menudo tendrá que 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 puede ejecutarse en entornos de ejecución diferentes o tiene lógica específica del entorno de ejecución, considere la posibilidad de admitir esta opción como una manera de especificar un identificador en tiempo de ejecución. Si la aplicación admite --runtime, considere la posibilidad de admitir --os y --arch también. Estas opciones permiten especificar solo el sistema operativo o las partes 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 para comandos, opciones y argumentos lo más cortos y fáciles de escribir posible. Por ejemplo, si class está lo suficientemente claro, no ejecute el comando classification.

Nombres en minúscula

Defina los nombres solo en minúsculas, excepto que puede crear alias en mayúsculas para que los comandos u opciones no distingan entre mayúsculas y minúsculas.

Nombres de grafía kebab

Utiliza kebab case para distinguir entre palabras. Por ejemplo: --additional-probing-path.

Pluralización

Dentro de una aplicación, sea coherente en la pluralización. 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 opciones Consistencia
--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 nombres para comandos que hacen referencia a acciones (aquellas sin subcomandos en ellos), por ejemplo: dotnet workload remove, no dotnet workload removal. Y use nombres en lugar de verbos para opciones, por ejemplo: --configuration, no --configure.

La --verbosity opción

System.CommandLine Las aplicaciones suelen ofrecer una --verbosity opción que especifica la cantidad de salida que se envía a la consola. Estos son los cinco valores 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, Debugo 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:

  • Tranquilo
  • Normal
  • Diagnóstico

Si una aplicación no necesita cinco niveles diferentes, la opción debe definir la misma configuración. En ese caso, Minimal y Normal producirán la misma salida, y Detailed y Diagnostic también serán iguales. Esto permite que los usuarios simplemente escriban lo que les resulta familiar, y se usará la mejor opción.

Se espera que Quiet no muestre salida alguna en la consola. Sin embargo, si una aplicación ofrece un modo interactivo, la aplicación debe realizar una de las siguientes acciones:

  • Muestra las solicitudes de entrada cuando --interactive se especifica, incluso si --verbosity es Quiet.
  • No permitir el uso de --verbosity Quiet y --interactive juntos.

De lo contrario, la aplicación esperará la entrada sin indicar al usuario lo que está esperando. Aparecerá que la aplicación se congeló y el usuario no tendrá idea de que la aplicación esté esperando la entrada.

Si define alias, use -v para --verbosity y haga que -v, sin un argumento, sea un alias para --verbosity Diagnostic. Use -q para --verbosity Quiet.

CLI de .NET y convenciones POSIX

La CLI de .NET no sigue constantemente todas las convenciones POSIX.

Guión doble

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

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

En este ejemplo, la --project opción se pasa al dotnet run comando y la --message opción 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 las opciones a la aplicación que ejecutas 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 y las opciones:

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

Omisión del delimitador que separa la opción del argumento

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

Varios argumentos sin repetir el nombre de la opción

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

Opciones booleanas

En la CLI de .NET, algunas opciones booleanas producen el mismo comportamiento cuando se pasa false que cuando se pasa true. Este comportamiento se produce cuando el código de la CLI de .NET que implementa la opción solo comprueba la presencia o ausencia de la opción, ignorando el valor. Un ejemplo es --no-restore para el dotnet build comando . Pasar --no-restore false y la operación de restauración se omitirá igual que cuando especifique --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 denominada --additionalprobingpath en lugar de --additional-probing-path.

Consulte también

  • Last updated on