Vue d’ensemble de la syntaxe de la ligne de commande pour System.CommandLine

Article
06/23/2023

Important

System.CommandLine est actuellement une PRÉVERSION et cette documentation concerne la version 2.0 beta 4. Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

Cet article explique la syntaxe de ligne de commande que System.CommandLine reconnaît. Les informations seront utiles aux utilisateurs ainsi qu’aux développeurs d’applications de ligne de commande .NET, y compris l’interface CLI .NET.

Jetons

System.CommandLine analyse l’entrée de la ligne de commande en jetons, qui sont des chaînes délimitées par des espaces. Examinons, par exemple, la ligne de commande suivante :

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

Cette entrée est analysée par l’application dotnet en jetons tool, install, dotnet-suggest, --global, --verbosity et quiet.

Les jetons sont interprétés comme des commandes, des options ou des arguments. L’application de ligne de commande appelée détermine la façon dont les jetons qui suivent le premier sont interprétés. La table suivante montre comment System.CommandLine interprète l’exemple précédent :

Jeton	analysé comme
`tool`	Sous-commande
`install`	Sous-commande
`dotnet-suggest`	Argument pour la commande d’installation
`--global`	Option pour la commande d’installation
`--verbosity`	Option pour la commande d’installation
`quiet`	Argument pour l’option `--verbosity`

Un jeton peut contenir des espaces s’il est entouré de guillemets ("). Voici un exemple :

dotnet tool search "ef migrations add"

Commandes

Une commandedans une entrée de ligne de commande est un jeton qui spécifie une action ou définit un groupe d’actions associées. Par exemple :

Dans dotnet run, run est une commande qui spécifie une action.
Dans dotnet tool install, install est une commande qui spécifie une action, et tool est une commande qui spécifie un groupe de commandes liées. Il existe d’autres commandes liées aux outils, telles que tool uninstall, tool list et tool update.

Commandes racines

La commande racine est celle qui spécifie le nom de l’exécutable de l’application. Par exemple, la commande dotnet spécifie l’exécutable dotnet.exe.

Sous-commandes

La plupart des applications de ligne de commande prennent en charge les sous-commandes, également appelées verbes. Par exemple, la commande dotnet a une sous-commande run que vous appelez en saisissant dotnet run.

Les sous-commandes peuvent avoir leurs propres sous-commandes. Dans dotnet tool install, install est une sous-commande de tool.

Options

Une option est un paramètre nommé qui peut être transmis à une commande. Les interfaces CLI POSIX préfixent généralement le nom de l’option avec deux traits d’union (--). L’exemple suivant montre deux options :

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

Comme l’illustre cet exemple, la valeur de l’option peut être explicite (quiet pour --verbosity) ou implicite (rien ne suit --global). Les options qui n’ont pas de valeur spécifiée sont généralement des paramètres booléens dont la valeur par défaut est true si l’option est spécifiée sur la ligne de commande.

Pour certaines applications de ligne de commande Windows, vous identifiez une option en utilisant une barre oblique (/) avec le nom de l’option. Par exemple :

msbuild /version
        ^------^

System.CommandLine prend en charge les conventions de préfixe POSIX et Windows. Lorsque vous configurez une option, vous spécifiez le nom de l’option, y compris le préfixe.

Arguments

Un argument est une valeur transmise à une option ou commande. Les exemples suivants montrent un argument pour l’option verbosity et un argument pour la commande build.

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

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

Les arguments peuvent avoir des valeurs par défaut qui s’appliquent si aucun argument n’est explicitement fourni. Par exemple, de nombreuses options sont implicitement des paramètres booléens avec une valeur par défaut de true lorsque le nom de l’option se trouve dans la ligne de commande. Les exemples de ligne de commande suivants sont équivalents :

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

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

Certaines options ont des arguments requis. Par exemple, dans l’interface de ligne de commande CLI .NET, --output requiert un argument de nom de dossier. Si l’argument n’est pas fourni, la commande échoue.

Les arguments peuvent avoir des types attendus et System.CommandLine affiche un message d’erreur si un argument ne peut pas être analysé dans le type attendu. Par exemple, les erreurs de commande suivantes, car « silent » n’est pas l’une des valeurs valides pour --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

Les arguments ont également des attentes sur le nombre de valeurs pouvant être fournies. Des exemples sont fournis dans la section sur l’arité des arguments.

Ordre des options et des arguments

Vous pouvez fournir des options avant les arguments ou des arguments avant les options sur la ligne de commande. Les commandes suivantes sont équivalentes :

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

Les options peuvent être spécifiées dans n’importe quel ordre. Les commandes suivantes sont équivalentes :

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

Lorsqu’il y a plusieurs arguments, l’ordre importe. Les commandes suivantes ne sont pas nécessairement équivalentes :

myapp argument1 argument2
myapp argument2 argument1

Ces commandes transmettent une liste avec les mêmes valeurs au code du gestionnaire de commandes, mais elles diffèrent dans l’ordre des valeurs, ce qui peut conduire à des résultats différents.

Alias

Dans POSIX et Windows, il est courant que certaines commandes et options aient des alias. Ce sont généralement des formulaires courts qui sont plus faciles à compléter. Les alias peuvent également être utilisés à d’autres fins, telles que simuler le non-respect de la casse et prendre en charge les variantes orthographiques d’un mot.

Les formes courtes POSIX ont généralement un seul trait d’union suivi d’un seul caractère. Les commandes suivantes sont équivalentes :

dotnet build --verbosity quiet
dotnet build -v quiet

La norme GNU recommande des alias automatiques. Autrement dit, vous pouvez saisir n’importe quelle partie d’un nom d’option ou de commande au format long et elle sera acceptée. Ce comportement rendrait les lignes de commande suivantes équivalentes :

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 ne prend pas en charge les alias automatiques.

Respect de la casse

Les noms et alias de commande et d’option respectent la casse par défaut selon la convention POSIX, et System.CommandLine suit cette convention. Si vous souhaitez que votre CLI ne respecte pas la casse, définissez des alias pour les différentes alternatives de casse. Par exemple, --additional-probing-path pourrait avoir des alias --Additional-Probing-Path et --ADDITIONAL-PROBING-PATH.

Dans certains outils de ligne de commande, une différence de casse spécifie une différence de fonction. Par exemple, git clean -X se comporte différemment de git clean -x. La CLI .NET est entièrement en minuscules.

Le respect de la casse ne s’applique pas aux valeurs d’argument des options basées sur des énumérations. Les noms d’énumération sont mis en correspondance, quelle que soit la casse.

Le jeton `--`

La convention POSIX interprète le jeton à double tiret (--) comme un mécanisme d’échappement. Tout ce qui suit le jeton à double tiret est interprété comme des arguments pour la commande. Cette fonctionnalité peut être utilisée pour soumettre des arguments qui ressemblent à des options, car elle les empêche d’être interprétés comme des options.

Supposons que myapp prenne un argument message et que vous souhaitiez que la valeur de message soit --interactive. La ligne de commande suivante peut donner des résultats inattendus.

myapp --interactive

Si myapp n’a pas d’option --interactive, le jeton --interactive est interprété comme un argument. Mais si l’application a une option --interactive, cette entrée sera interprétée comme faisant référence à cette option.

La ligne de commande suivante utilise le jeton à double tiret pour définir la valeur de l’argument message sur « --interactive » :

myapp -- --interactive
      ^^

System.CommandLine prend en charge cette fonctionnalité à double tiret.

Séparateur d’argument d’option

System.CommandLine vous permet d’utiliser un espace, « = » ou « : » comme séparateur entre un nom d’option et son argument. Par exemple, les commandes suivantes sont équivalentes :

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

Une convention POSIX vous permet d’omettre le séparateur lorsque vous spécifiez un alias d’option à un seul caractère. Par exemple, les commandes suivantes sont équivalentes :

myapp -vquiet
myapp -v quiet

System.CommandLine prend en charge cette syntaxe par défaut.

Arité de l’argument

L’arité de l’argument d’une option ou d’une commande correspond au nombre de valeurs pouvant être transmises si cette option ou cette commande est spécifiée.

L’arité est exprimée avec une valeur minimale et une valeur maximale, comme l’illustre le tableau suivant :

Min	Max	Exemple de validité	Exemple
0	0	Valide :	--file
		Invalide :	--file a.json
		Invalide :	--file a.json --file b.json
0	1	Valide :	--flag
		Valide :	--flag true
		Valide :	--flag false
		Invalide :	--flag false --flag false
1	1	Valide :	--file a.json
		Invalide :	--file
		Invalide :	--file a.json --file b.json
0	n	Valide :	--file
		Valide :	--file a.json
		Valide :	--file a.json --file b.json
1	n	Valide :	--file a.json
		Valide :	--file a.json b.json
		Invalide :	--file

System.CommandLine a une structure ArgumentArity pour définir l’arité, avec les valeurs suivantes :

Zero – Aucune valeur autorisée.
ZeroOrOne – Peut avoir une valeur, peut n’avoir aucune valeur.
ExactlyOne – Doit avoir une valeur.
ZeroOrMore – Peut avoir une valeur, plusieurs valeurs ou aucune valeur.
OneOrMore – Peut avoir plusieurs valeurs, doit avoir au moins une valeur.

L’arité peut souvent être déduite du type. Par exemple, une option int a une arité de ExactlyOne et une option List<int> a une arité de OneOrMore.

Remplacements d’options

Si le maximum d’arité est 1, System.CommandLine peut toujours être configuré pour accepter plusieurs instances d’une option. Dans ce cas, la dernière instance d’une option répétée remplace toutes les instances précédentes. Dans l’exemple suivant, la valeur 2 serait transmise à la commande myapp.

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

Arguments multiples

Si le maximum d’arité est supérieur à 1, System.CommandLine peut être configuré pour accepter plusieurs arguments pour une option sans répéter le nom de l’option.

Dans l’exemple suivant, la liste transmise à la commande myapp contiendrait « a », « b », « c » et « d » :

myapp --list a b c --list d

Regroupement d’options

POSIX vous recommande de prendre en charge le regroupement d’options à caractère unique, également appelé empilement. Les options regroupées sont des alias d’options à caractère unique spécifiés ensemble après un seul préfixe de trait d’union. Seule la dernière option peut spécifier un argument. Par exemple, les lignes de commande suivantes sont équivalentes :

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

Si un argument est fourni après un regroupement d’options, il s’applique à la dernière option du regroupement. Les lignes de commande suivantes sont équivalentes :

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

Dans les deux variantes de cet exemple, l’argument arg ne s’appliquerait qu’à l’option -c.

Options booléennes (indicateurs)

Si true ou false est transmis pour une option comprenant un argument bool, l’analyse s’effectue comme prévu. Mais une option dont le type d’argument est bool ne nécessite généralement pas la spécification d’un argument. Les options booléennes, parfois appelées « indicateurs », ont généralement une arité de ZeroOrOne. La présence du nom de l’option sur la ligne de commande, sans argument le suivant, se traduit par une valeur par défaut de true. L’absence du nom de l’option dans l’entrée de la ligne de commande entraîne une valeur de false. Si la commande myapp imprime la valeur d’une option booléenne nommée --interactive, l’entrée suivante crée la sortie suivante :

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

False
True
False
True

L’option --help

Les applications de ligne de commande fournissent généralement une option pour afficher une brève description des commandes, options et arguments disponibles. System.CommandLine génère automatiquement une sortie d’aide. Par exemple :

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.

Les utilisateurs d’applications peuvent être habitués à différentes manières de demander de l’aide sur différentes plateformes, de sorte que les applications construites sur System.CommandLine répondent à de nombreuses façons de demander de l’aide. Les commandes suivantes sont toutes équivalentes :

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

Le résultat de l’aide n’affiche pas nécessairement toutes les commandes, arguments et options disponibles. Certains d’entre eux peuvent être masqués, ce qui signifie qu’ils n’apparaissent pas dans le résultat de l’aide, mais qu’ils peuvent être spécifiés sur la ligne de commande.

L’option --version

Les applications construites sur System.CommandLine fournissent automatiquement le numéro de version en réponse à l’option --version utilisée avec la commande racine. Par exemple :

dotnet --version

6.0.100

Fichiers réponse

Un fichier de réponses est un fichier qui contient un ensemble de jetons pour une application de ligne de commande. Les fichiers de réponse sont une fonctionnalité de System.CommandLine qui est utile dans deux scénarios :

Pour appeler une application de ligne de commande en spécifiant une entrée plus longue que la limite de caractères du terminal.
Pour appeler la même commande à plusieurs reprises sans saisir à nouveau toute la ligne.

Pour utiliser un fichier réponse, saisissez le nom du fichier précédé du signe @ à l’endroit de la ligne où vous souhaitez insérer des commandes, des options et des arguments. L’extension de fichier .rsp est une convention courante, mais vous pouvez utiliser n’importe quelle extension de fichier.

Les lignes suivantes sont équivalentes :

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

Contenus de sample1.rsp :

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

Contenus de sample2.rsp :

--no-restore

Voici les règles de syntaxe qui déterminent comment le texte d’un fichier de réponses est interprété :

Les jetons sont délimités par des espaces. Une ligne qui contient Au revoir ! est traitée comme deux jetons, Au et revoir !.
Plusieurs jetons entre guillemets sont interprétés comme un seul jeton. Une ligne qui contient « Au revoir ! » est traitée comme un jeton, Au revoir !.
Tout texte entre le symbole # et la fin de la ligne est traité comme un commentaire et ignoré.
Les jetons préfixés de @ peuvent référencer des fichiers réponses supplémentaires.
Le fichier réponse peut contenir plusieurs lignes de texte. Les lignes sont concaténées et interprétées comme une séquence de jetons.

Directives

System.CommandLine introduit un élément syntaxique appelé directive. La directive [parse] en est un exemple. Lorsque vous incluez [parse] après le nom de l’application, System.CommandLine affiche un diagramme du résultat de l’analyse au lieu d’appeler l’application de ligne de commande :

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

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

Le but des directives est de fournir des fonctionnalités transversales qui peuvent s’appliquer à toutes les applications de ligne de commande. Étant donné que les directives sont syntaxiquement distinctes de la propre syntaxe de l’application, elles peuvent fournir des fonctionnalités qui s’appliquent à toutes les applications.

Une directive doit respecter les règles de syntaxe suivantes :

Elle contient un jeton sur la ligne de commande qui vient après le nom de l’application, mais avant toute sous-commande ou option.
Elle est placée entre crochets.
Elle ne contient pas d’espaces.

Une directive non reconnue est ignorée sans provoquer d’erreur d’analyse.

Une directive peut inclure un argument, séparé du nom de la directive par deux points.

Les directives suivantes sont intégrées :

[parse]
[suggest]

Directive `[parse]`

Les utilisateurs et les développeurs peuvent trouver utile de voir comment une application interprétera une entrée donnée. L’une des fonctionnalités par défaut d’une application System.CommandLine est la directive [parse], qui vous permet de prévisualiser le résultat de l’entrée de la commande d’analyse. Par exemple :

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

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

Dans l’exemple précédent :

La commande (myapp), ses options enfant et les arguments de ces options sont regroupés à l’aide de crochets.
Pour le résultat de l’option [ --delay !<not-an-int> ], le ! indique une erreur d’analyse. La valeur not-an-int pour une option int ne peut pas être analysée au type attendu. L’erreur est également indiquée par ! devant la commande qui contient l’option erronée : ![ myapp...
Pour le résultat de l’option *[ --fgcolor <White> ], l’option n’a pas été spécifiée sur la ligne de commande, donc la valeur par défaut configurée a été utilisée. White est la valeur effective de cette option. L’astérisque indique que la valeur est la valeur par défaut.
???--> pointe vers une entrée qui ne correspondait à aucune des commandes ou options de l’application.

Directive `[suggest]`

La directive [suggest] vous permet de rechercher des commandes lorsque vous ne connaissez pas la commande exacte.

dotnet [suggest] buil

build
build-server
msbuild

Guide de conception

Les sections suivantes présentent des conseils pour vous aider que nous vous recommandons de suivre lors de la conception d’une CLI. Pensez à ce que votre application attend sur la ligne de commande comme similaire à ce qu’un serveur d’API REST attend dans l’URL. Des 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 manière, les utilisateurs de vos applications en ligne de commande bénéficieront d’une meilleure expérience si la conception de la CLI suit des modèles courants.

Une fois que vous avez créé une CLI, il est difficile de la modifier, surtout si vos utilisateurs ont utilisé votre CLI dans des scripts qu’ils s’attendent à continuer à exécuter. Les présentes instructions ont été développées après la CLI .NET, et elles ne suivent pas toujours ces principes. Nous mettons à jour la CLI .NET où nous pouvons le faire sans introduire de changement cassant. Un exemple de ce travail est la nouvelle conception de dotnet new dans .NET 7.

Commandes et sous-commandes

Si une commande a des sous-commandes, la commande doit fonctionner comme une zone, ou un identifiant de regroupement pour les sous-commandes, plutôt que de devoir 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 ; vous obtenez un message d’erreur, car la commande tool identifie uniquement un groupe de sous-commandes liées à l’outil, telles que install et list. Vous pouvez exécuter dotnet tool install, mais dotnet tool seul serait incomplet.

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

Dans une CLI, il y a souvent une zone implicite. Par exemple, dans la CLI .NET, la zone implicite est le projet et dans la CLI Docker, c’est l’image. Par conséquent, vous pouvez utiliser dotnet build sans inclure de zone. Déterminez si votre CLI a une zone implicite. Si tel est le cas, envisagez de permettre à l’utilisateur de l’inclure ou de l’omettre éventuellement comme dans docker build et docker image build. Si vous autorisez éventuellement la saisie de la zone implicite par votre utilisateur, vous disposez également automatiquement de l’aide et du remplissage de l’onglet pour ce groupe de commandes. Fournissez l’utilisation facultative du groupe implicite en définissant deux commandes qui effectuent la même opération.

Les options utilisées en tant que paramètres

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

Alias abrégés

En général, nous vous recommandons de minimiser le nombre d’alias d’options abrégés que vous définissez.

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

-i plutôt que --interactive

Cette option signale à l’utilisateur qu’il peut être invité à saisir des questions auxquelles la commande doit répondre. Par exemple, demander un nom d’utilisateur. Votre CLI peut être utilisée dans des scripts, soyez donc prudent lorsque vous invitez les utilisateurs qui n’ont pas spécifié ce commutateur.
-o plutôt que --output

Certaines commandes produisent des fichiers à la suite de leur exécution. Cette option doit être utilisée pour aider à 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 à un fichier. Dans les cas où de nombreux fichiers sont créés, cette option doit être un chemin d’accès à un répertoire.
-v plutôt que --verbosity

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

Il existe également des alias dont l’utilisation courante est limitée à l’interface de la CLI .NET. Vous pouvez utiliser ces alias pour d’autres options dans vos applications, mais soyez conscient du risque 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 pour une configuration, mais la plupart des outils en attendent un. Ce paramètre est souvent utilisé pour configurer d’autres propriétés d’une manière qui a du sens pour cette configuration, par exemple, en faisant moins d’optimisation de code lors de la construction de la configuration Debug. Envisagez cette option si votre commande opère de différentes façons.
-f pour --framework

Cette option est utilisée pour sélectionner un Moniker de framework cible (TFM) à exécuter. Par conséquent, si votre application CLI a un comportement différent en fonction du TFM choisi, vous devez prendre en charge cet indicateur.
-p pour --property

Si votre application appelle finalement MSBuild, l’utilisateur devra souvent personnaliser cet appel d’une manière ou d’une autre. 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 possède une logique spécifique à un runtime, envisagez de prendre en charge cette option comme moyen de spécifier un identifiant de runtime. Si votre application prend en charge --runtime, envisagez également de prendre en charge --os et --arch Ces options vous permettent de spécifier uniquement le système d’exploitation ou les parties d’architecture du RID, laissant la partie non spécifiée à déterminer à partir de la plateforme actuelle. Pour plus d’informations, consultez dotnet publish.

Noms courts

Créez des noms pour les commandes, les options et les arguments aussi courts et faciles à épeler que possible. Par exemple, si class est suffisamment clair, n’effectuez pas la commande classification.

Noms en minuscules

Définissez les noms en minuscules uniquement, excepté pour les alias que vous pouvez créer en majuscules afin que les commandes ou les options respectent la casse.

Noms en casse kebab

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

Forme plurielle

Au sein d’une application, soyez cohérent dans la pluralisation. Par exemple, ne mélangez pas de noms au pluriel et au singulier pour les options qui peuvent avoir plusieurs valeurs (l’arité maximale est supérieure à 1) :

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 (celles sans sous-commandes), par exemple :dotnet workload remove, pas dotnet workload removal. Et utilisez des noms plutôt que des verbes pour les options, par exemple : --configuration, pas--configure.

L’option `--verbosity`

Les applications System.CommandLine offrent généralement une option --verbosity 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]

Ce sont les noms standard, mais les applications existantes utilisent parfois Silent à la place de Quiet, et Trace, Debug ou Verbose à la place de Diagnostic.

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

Quiet
Normal
Diagnostic

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

L’attente pour Quiet est qu’aucune sortie ne s’affiche sur la console. Cependant, si une application propose un mode interactif, l’application doit effectuer l’une des alternatives suivantes :

L’écran invite à compléter l’entrée lorsque --interactive est spécifié, même si --verbosity est Quiet.
Interdire l’utilisation de --verbosity Quiet et --interactive ensemble.

Sinon, l’application attendra une entrée sans dire à l’utilisateur ce qu’elle attend. Il apparaîtra que votre application est bloquée et l’utilisateur n’aura aucune idée que l’application attend une entrée.

Si vous définissez des alias, utilisez -v pour --verbosity et définissez -v sans argument d’alias pour --verbosity Diagnostic. Utilisez -q pour --verbosity Quiet.

Les conventions CLI .NET et POSIX

La CLI .NET ne suit pas systématiquement toutes les conventions POSIX.

Double tiret

Plusieurs commandes de la 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 exécutée par la commande. Par exemple :

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

Dans cet exemple, l’option --project est transmise à la commande dotnet run et l’option --message avec son argument est transmise en tant qu’option de ligne de commande à myapp lors de son exécution.

Le jeton -- n’est pas toujours requis pour transmettre des options à une application que vous exécutez à l’aide de dotnet run. Sans le 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. Ainsi, les lignes de commande suivantes sont équivalentes, car dotnet run ne reconnaît 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 séparateur d’option d’argument

La CLI .NET ne prend pas en charge la convention POSIX qui vous permet d’omettre le séparateur lorsque vous spécifiez un alias d’option à un seul caractère.

Arguments multiples sans répéter le nom de l’option

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

Options booléennes

Dans la CLI .NET, certaines options booléennes entraînent le même comportement lorsque vous transmettez false ou lorsque vous transmettez 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, en ignorant la valeur. Un exemple est --no-restore pour la commande dotnet build. Transmettez no-restore false et l’opération de restauration sera ignorée comme lorsque vous spécifiez no-restore true ou no-restore.

Casse kebab

Dans certains cas, la CLI .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.

Partager via