Partager via

Guide de conception

Les sections suivantes présentent des conseils pour la conception d’une interface CLI. Pensez à ce que votre application attend sur la ligne de commande comme ce qu’attend un serveur d’API REST dans l’URL. Les règles cohérentes pour les API REST sont ce qui les rend facilement utilisables pour les développeurs d’applications clientes. De la même façon, les utilisateurs de vos applications en ligne de commande auront une meilleure expérience si la conception CLI suit des modèles courants.

Une fois que vous avez créé une interface CLI, il est difficile de le modifier, en particulier si vos utilisateurs ont utilisé votre interface CLI dans les scripts qu’ils s’attendent à continuer d’exécuter.

Symboles

Commandes et sous-commandes

Si une commande a des sous-commandes, la commande doit fonctionner en tant que zone ou identificateur de regroupement pour les sous-commandes, au lieu de spécifier une action. Lorsque vous appelez l’application, vous spécifiez la commande de regroupement et l’une de ses sous-commandes. Par exemple, essayez d’exécuter dotnet tool, et vous obtenez un message d’erreur, car la tool commande identifie uniquement un groupe de sous-commandes liées à l’outil, comme install et list. Vous pouvez exécuter dotnet tool install, mais dotnet tool en soi serait incomplet.

L’une des façons dont la définition des zones aide vos utilisateurs est qu’elle organise la sortie d’aide.

Dans une interface CLI, il existe souvent une zone implicite. Par exemple, dans l’interface CLI .NET, la zone implicite est le projet et, dans l’interface CLI Docker, il s’agit de l’image. Par conséquent, vous pouvez utiliser dotnet build sans inclure de zone. Déterminez si votre interface CLI a une zone implicite. Si c’est le cas, déterminez s’il faut autoriser l’utilisateur à l’inclure ou à l’omettre, comme dans docker build et docker image build. Si vous choisissez de permettre à l’utilisateur de saisir des données dans la zone implicite, vous bénéficiez également automatiquement de l’aide et de la saisie semi-automatique par tabulation pour ce regroupement de commandes. Fournissez l’utilisation facultative du groupe implicite en définissant deux commandes qui effectuent la même opération.

Options en tant que paramètres

Les options doivent fournir des paramètres aux commandes, plutôt que de spécifier eux-mêmes des actions. Il s’agit d’un principe de conception recommandé, bien qu’il ne soit pas toujours suivi par System.CommandLine (--help affiche les informations d’aide).

Dénomination

Alias de forme courte

En général, nous vous recommandons de réduire le nombre d’alias d’option de courte forme que vous définissez.

En particulier, évitez d’utiliser les alias suivants différemment de leur utilisation courante dans l’interface CLI .NET et d’autres applications en ligne de commande .NET :

  • -i pour --interactive.

    Cette option signale à l’utilisateur qu’il pourrait être invité à saisir des réponses aux questions dont la commande a besoin pour être traitées. Par exemple, vous êtes invité à entrer un nom d’utilisateur. Votre CLI peut être utilisée dans des scripts, alors faites preuve de prudence avant d'inviter les utilisateurs qui n’ont pas spécifié cette option.

  • -o pour --output.

    Certaines commandes produisent des fichiers à la suite de leur exécution. Cette option doit être utilisée pour déterminer l’emplacement de ces fichiers. Dans les cas où un seul fichier est créé, cette option doit être un chemin d’accès au fichier. Dans les cas où de nombreux fichiers sont créés, cette option doit être un chemin d’accès au répertoire.

  • -v pour --verbosity.

    Les commandes fournissent souvent une sortie à l’utilisateur sur la console ; cette option est utilisée pour spécifier la quantité de sortie que l’utilisateur demande. Pour plus d’informations, consultez l’option --verbosity plus loin dans cet article.

Il existe également des alias avec une utilisation courante limitée à l’interface CLI .NET. Vous pouvez utiliser ces alias pour d’autres options dans vos applications, mais tenez compte de la possibilité de confusion.

  • -c pour --configuration

    Cette option fait souvent référence à une configuration de build nommée, comme Debug ou Release. Vous pouvez utiliser n’importe quel nom souhaité pour une configuration, mais la plupart des outils s’attendent à l’un d’entre eux. Ce paramètre est souvent utilisé pour configurer d’autres propriétés d’une manière qui est logique pour cette configuration, par exemple, en effectuant moins d’optimisation du code lors de la génération de la Debug configuration. Envisagez cette option si votre commande a différents modes d’opération.

  • -f pour --framework

    Cette option est utilisée pour sélectionner un seul moniker de framework cible (TFM) à exécuter. Par conséquent, si votre application d’interface de ligne de commande a un comportement différent en fonction du TFM choisi, vous devez prendre en charge cet indicateur.

  • -p pour --property

    Si votre application appelle éventuellement MSBuild, l’utilisateur doit souvent personnaliser cet appel d’une certaine manière. Cette option permet aux propriétés MSBuild d’être fournies sur la ligne de commande et transmises à l’appel MSBuild sous-jacent. Si votre application n’utilise pas MSBuild mais a besoin d’un ensemble de paires clé-valeur, envisagez d’utiliser ce même nom d’option pour tirer parti des attentes des utilisateurs.

  • -r pour --runtime

    Si votre application peut s’exécuter sur différents runtimes ou a une logique spécifique au runtime, envisagez de prendre en charge cette option comme moyen de spécifier un identificateur d’exécution. Si votre application prend en charge --runtime, envisagez de prendre en charge --os et --arch également. Ces options vous permettent de spécifier uniquement le système d’exploitation ou les parties d’architecture du RID, en laissant la partie non spécifiée pour être déterminée à partir de la plateforme actuelle. Pour plus d’informations, consultez dotnet publish.

Noms courts

Nommer les commandes, les options et les arguments aussi courts et faciles à orthographier que possible. Par exemple, si class est suffisamment clair, ne faites pas la commande classification.

Noms en lettres minuscules

Définissez les noms en minuscules uniquement, mais vous pouvez créer des alias en majuscules pour que les commandes ou options ne tiennent pas compte de la casse.

Noms de casse Kebab

Utilisez la casse kebab pour distinguer les mots. Par exemple : --additional-probing-path.

Pluralisation

Dans une application, soyez cohérent dans la pluralisation. Par exemple, ne mélangez pas de noms pluriels et singuliers pour les options qui peuvent avoir plusieurs valeurs (arité maximale supérieure à un) :

Noms des options Cohérence
--additional-probing-paths et --sources ✔️
--additional-probing-path et --source ✔️
--additional-probing-paths et --source ❌
--additional-probing-path et --sources ❌

Verbes et noms

Utilisez des verbes plutôt que des noms pour les commandes qui font référence à des actions (sans sous-commandes), par exemple : dotnet workload remove, plutôt que dotnet workload removal. Et utilisez des noms plutôt que des verbes pour les options, par exemple : --configuration, et non --configure.

L'option --verbosity

System.CommandLine les applications offrent généralement une --verbosity option qui spécifie la quantité de sortie envoyée à la console. Voici les cinq paramètres standard :

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

Il s’agit des noms standard, mais les applications existantes utilisent Silent parfois à la place Quiet, et Trace, Debugou Verbose à la place de Diagnostic.

Chaque application définit ses propres critères qui déterminent ce qui est affiché à chaque niveau. En règle générale, une application n’a besoin que de trois niveaux :

  • Silencieux
  • Normale
  • Diagnostique

Si une application n’a pas besoin de cinq niveaux différents, l’option doit toujours définir les mêmes cinq paramètres. Dans ce cas, Minimal et Normal produira la même sortie, et DetailedDiagnostic sera de même la même. Cela permet à vos utilisateurs de taper simplement ce qu’ils connaissent, et le meilleur ajustement sera utilisé.

L'expectation pour Quiet est qu'aucune sortie ne soit affichée sur la console. Toutefois, si une application offre un mode interactif, l’application doit effectuer l’une des opérations suivantes :

  • Affiche les invites d’entrée lorsque --interactive est spécifié, même si --verbosity est Quiet.
  • Interdire l'utilisation conjointe de --verbosity Quiet et --interactive.

Sinon, l’application attend l’entrée sans indiquer à l’utilisateur ce qu’il attend. Il semble que votre application s'est figée et que l'utilisateur n'a aucune idée que l'application attend des données.

Si vous définissez des alias, utilisez -v pour --verbosity et faites de -v sans argument un alias pour --verbosity Diagnostic. Utiliser -q pour --verbosity Quiet.

Conventions CLI et POSIX .NET

L’interface CLI .NET ne suit pas constamment toutes les conventions POSIX.

Double tiret

Plusieurs commandes de l’interface CLI .NET ont une implémentation spéciale du jeton double tiret. Dans le cas de dotnet run, dotnet watch et dotnet tool run, les jetons qui suivent -- sont transmis à l’application en cours d’exécution par la commande. Par exemple:

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

Dans cet exemple, l’option --project est passée à la dotnet run commande et l’option --message avec son argument est passée en tant qu’option de ligne de commande à myapp lorsqu’elle s’exécute.

Le -- jeton n’est pas toujours requis pour passer des options à une application que vous exécutez à l’aide de dotnet run. En l'absence du double tiret, la commande dotnet run transmet automatiquement à l’application en cours d’exécution toutes les options qui ne sont pas reconnues comme s’appliquant à dotnet run ou à MSBuild. Par conséquent, les lignes de commande suivantes sont équivalentes, car dotnet run ne reconnaissent pas les arguments et les options :

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

Omission du délimiteur entre l'option et l'argument

L’interface CLI .NET ne prend pas en charge la convention POSIX qui vous permet d’omettre le délimiteur lorsque vous spécifiez un alias d’option à caractère unique.

Plusieurs arguments sans répéter le nom de l’option

L’interface CLI .NET n’accepte pas plusieurs arguments pour une option sans répéter le nom de l’option.

Options booléennes

Dans l'interface CLI .NET, certaines options booléennes entraînent le même comportement que vous passiez false ou true. Ce comportement se produit lorsque le code CLI .NET qui implémente l’option vérifie uniquement la présence ou l’absence de l’option, ignorant la valeur. Exemple : --no-restore pour la commande dotnet build. Ignorer --no-restore false et l’opération de restauration sera sautée de la même manière que lorsque vous spécifiez --no-restore true ou --no-restore.

Cas kebab

Dans certains cas, l’interface de ligne de commande .NET n’utilise pas la casse kebab pour les noms de commande, d’option ou d’argument. Par exemple, il existe une option CLI .NET nommée --additionalprobingpath au lieu de --additional-probing-path.

Voir aussi

  • Last updated on