Partager via

Vue d’ensemble de la syntaxe : Commandes, options et arguments

Cet article explique la syntaxe de ligne de commande qui System.CommandLine reconnaît. Les informations sont utiles pour les utilisateurs et les développeurs d’applications en ligne de commande .NET, notamment l’interface CLI .NET.

Jetons

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

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

Cette entrée est analysée par l'application dotnet en éléments 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 qui est invoquée détermine la manière dont les jetons après le premier sont interprétés. Le tableau suivant montre comment System.CommandLine interpréter l’exemple précédent :

Jeton Analysé en tant que
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 de l’option --verbosity

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

dotnet tool search "ef migrations add"

La hiérarchie de symboles (commandes, options, arguments) est considérée comme une entrée fiable ; les valeurs des tokens ne le sont pas.

Commandes

Une commande en 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 associées. Il existe d’autres commandes liées aux outils, telles que tool uninstall, tool listet tool update.

Commande racine

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écutabledotnet.exe.

Command est la classe à usage général pour n’importe quelle commande ou sous-commande, tandis qu’elle RootCommand est une version spécialisée destinée au point d’entrée racine de l’application. RootCommand hérite de toutes les fonctionnalités, Command mais ajoute un comportement spécifique à la racine et des valeurs par défaut, telles que l’option d’aide, l’option Version et la directive Suggest.

Sous-commandes

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

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

Vous pouvez ajouter des sous-commandes comme illustré dans l’exemple suivant :

RootCommand rootCommand = new();

Command sub1Command = new("sub1", "First-level subcommand");
rootCommand.Subcommands.Add(sub1Command);

Command sub1aCommand = new("sub1a", "Second level subcommand");
sub1Command.Subcommands.Add(sub1aCommand);

La sous-commande la plus interne de cet exemple peut être appelée comme suit :

myapp sub1 sub1a

Paramètres

Une option est un paramètre nommé qui peut être passé à une commande. POSIX Les CLIs 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 aucune valeur spécifiée sont généralement des paramètres booléens par défaut 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 à l’aide d’une barre oblique de début (/) 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 :

Option<int> delayOption = new("--delay", "-d")
{
    Description = "An option whose argument is parsed as an int.",
    DefaultValueFactory = parseResult => 42,
};
Option<string> messageOption = new("--message", "-m")
{
    Description = "An option whose argument is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Options.Add(delayOption);
rootCommand.Options.Add(messageOption);

Pour ajouter une option à une commande et de manière récursive à toutes ses sous-commandes, utilisez la System.CommandLine.Symbol.Recursive propriété.

Options requises

Certaines options ont des arguments obligatoires. Par exemple, dans l’interface CLI .NET, --output nécessite un argument de nom de dossier. Si l’argument n’est pas fourni, la commande échoue. Pour rendre une option obligatoire, définissez sa propriété Required sur true, comme illustré dans l'exemple suivant :

Option<FileInfo> fileOption = new("--output")
{
    Required = true
};

Si une option requise a une valeur par défaut (spécifiée via la DefaultValueFactory propriété), l’option n’a pas besoin d’être spécifiée sur la ligne de commande. Dans ce cas, la valeur par défaut fournit la valeur d’option requise.

Les arguments

Un argument est un paramètre sans nom qui peut être passé à une commande. L’exemple suivant montre un argument pour la build commande.

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

Lorsque vous configurez un argument, vous spécifiez le nom de l’argument (il n’est pas utilisé pour l’analyse, mais il peut être utilisé pour obtenir des valeurs analysées par nom ou affichage de l’aide) et tapez :

Argument<int> delayArgument = new("delay")
{
    Description = "An argument that is parsed as an int.",
    DefaultValueFactory = parseResult => 42
};
Argument<string> messageArgument = new("message")
{
    Description = "An argument that is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Arguments.Add(delayArgument);
rootCommand.Arguments.Add(messageArgument);

Valeurs par défaut

Les arguments et les options 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
                                  ^-----------^

Un argument défini sans valeur par défaut est traité comme un argument obligatoire.

Erreurs d’analyse

Les options et les arguments ont des types attendus et une erreur est générée lorsque la valeur ne peut pas être analysée. Par exemple, les erreurs de commande suivantes, car « silencieux » n’est pas l’une des valeurs valides pour --verbosity:

dotnet build --verbosity silent

Option<string> verbosityOption = new("--verbosity", "-v")
{
    Description = "Set the verbosity level.",
};
verbosityOption.AcceptOnlyFromAmong("quiet", "minimal", "normal", "detailed", "diagnostic");
RootCommand rootCommand = new() { verbosityOption };

ParseResult parseResult = rootCommand.Parse(args);
foreach (ParseError parseError in parseResult.Errors)
{
    Console.WriteLine(parseError.Message);
}

Argument 'silent' not recognized. Must be one of:
        'quiet'
        'minimal'
        'normal'
        'detailed'
        'diagnostic'

Les arguments ont également des attentes quant au nombre de valeurs qui peuvent être fournies. Des exemples sont fournis dans la section relative à l’arité des arguments.

Ordre des options et des arguments

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

dotnet add package System.CommandLine --no-restore
dotnet add package --no-restore System.CommandLine

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

dotnet add package System.CommandLine --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

Lorsqu’il existe plusieurs arguments, l’ordre est important. Les commandes suivantes ne sont pas équivalentes ; ils diffèrent dans l’ordre des valeurs, ce qui peut entraîner des résultats différents :

myapp argument1 argument2
myapp argument2 argument1

Pseudonymes

Dans POSIX et Windows, il est courant que certaines commandes et options aient des alias. Il s’agit généralement de formes courtes plus faciles à saisir. Les alias peuvent également être utilisés à d’autres fins, par exemple pour simuler l’insensibilité à la casse et pour prendre en charge les variantes orthographiques d’un mot.

Les formes courtes POSIX ont généralement un trait d’union simple 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 entrer n’importe quelle partie d’une commande ou d’un nom d’option longue, et il sera accepté. Ce comportement rend 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. Chaque alias doit être spécifié explicitement. Les commandes et les options exposent une Aliases propriété. Option a un constructeur qui accepte les alias en tant que paramètres. Vous pouvez donc définir une option avec plusieurs alias dans une seule ligne :

Option<bool> helpOption = new("--help", ["-h", "/h", "-?", "/?"]);
Command command = new("serialize") { helpOption };
command.Aliases.Add("serialise");

Nous vous recommandons de réduire le nombre d’alias d’option que vous définissez et d’éviter de définir certains alias en particulier. Pour plus d’informations, consultez alias abrégés.

Respect de la casse

Les noms de commande, d’option et les alias sont sensibles à la casse par défaut selon la convention POSIX, et System.CommandLine respecte cette convention. Si vous souhaitez que votre interface de ligne de commande ne soit pas sensible à la casse, définissez des alias pour les différentes alternatives de casse. Par exemple, --additional-probing-path peut 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. L’interface CLI .NET est en minuscules.

La sensibilité à la casse ne s’applique pas aux valeurs d’argument pour les options basées sur des énumérations. Les noms d’énumération sont mis en correspondance indépendamment de la casse.

Jeton --

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

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

myapp --interactive

Si myapp n’a pas d'option --interactive disponible, le jeton --interactive est interprété comme un argument. Toutefois, si l’application a une --interactive option, 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.

Délimiteurs d’arguments d’option

System.CommandLine vous permet d’utiliser un espace, « = » ou « : » comme délimiteur 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 délimiteur lorsque vous spécifiez un alias d’option à caractère unique. 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 est le nombre de valeurs qui peuvent être passées si cette option ou cette commande est spécifiée.

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

Min Max Exemple de validité Exemple :
0 0 Valide : --file
Non valide: --file a.json
Non valide: --file a.json --file b.json
0 1 Valide : --drapeau
Valide : --flag vrai
Valide : --flag false
Non valide: --flag false --flag false
1 1 Valide : --file a.json
Non valide: --file
Non valide: --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
Non valide: --file

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

  • Zero - Aucune valeur autorisée.
  • ZeroOrOne - Peut avoir une valeur ou aucune valeur.
  • ExactlyOne - Nécessite une valeur.
  • ZeroOrMore - Peut avoir une valeur, plusieurs valeurs ou aucune valeur.
  • OneOrMore - Peut avoir plusieurs valeurs ; doit avoir au moins une valeur.

Vous pouvez définir explicitement la arité à l’aide de la propriété, mais dans la Arity plupart des cas, cela n’est pas nécessaire. System.CommandLine détermine automatiquement l’arité de l’argument en fonction du type d’argument :

Type d’argument Arité par défaut
Boolean ArgumentArity.ZeroOrOne
Types de collection ArgumentArity.ZeroOrMore
Tout le reste ArgumentArity.ExactlyOne

Remplacements d’option

Si la valeur maximale de la arité est 1, System.CommandLine peut toujours être configurée 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 antérieures. Dans l’exemple suivant, la valeur 2 est passée à la myapp commande.

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

Plusieurs arguments

Par défaut, lorsque vous appelez une commande, vous pouvez répéter un nom d’option pour spécifier plusieurs arguments pour une option qui a une arité maximale supérieure à une.

myapp --items one --items two --items three

Pour autoriser plusieurs arguments sans répéter le nom de l’option, définissez de AllowMultipleArgumentsPerToken à true. Ce paramètre vous permet d’entrer la ligne de commande suivante.

myapp --items one two three

Le même paramètre a un effet différent si la arité d’argument maximale est 1. Elle vous permet de répéter une option, mais ne prend que la dernière valeur sur la ligne. Dans l’exemple suivant, la valeur three est passée à l’application.

myapp --item one --item two --item three

Regroupement d’options

POSIX vous recommande de prendre en charge le regroupement d’options à caractère unique, également appelé empilement. Les options groupées sont des alias d'options à caractère unique spécifiés ensemble après un trait d'union unique comme préfixe. 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 bundle d’options, il s’applique à la dernière option du bundle. 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 s’applique uniquement à l’option -c.

Options booléennes (indicateurs)

S’il true ou false est passé pour une option ayant un argument bool, elle est analysée comme prévu. Mais une option dont le type d’argument est bool généralement ne nécessite pas de spécification d’argument. Les options booléennes, parfois appelées « indicateurs », ont généralement une arité de ZeroOrOne. La présence du nom d’option sur la ligne de commande, sans argument qui suit, entraîne une valeur par défaut .true L’absence du nom d’option dans l’entrée de ligne de commande entraîne une valeur de false. Si la myapp commande 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

Option de version

Les applications basées 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 de réponse

Un fichier réponse est un fichier qui contient un ensemble de jetons pour une application en ligne de commande. Les fichiers de réponse sont une fonctionnalité utile System.CommandLine 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 retaper la ligne entière.

Pour utiliser un fichier de réponse, entrez le nom du fichier précédé d'un signe @ à l'endroit souhaité dans la ligne pour insérer des commandes, des options et des arguments. L’extension de fichier .rsp est une convention commune, 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/

Contenu de sample1.rsp :

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

Contenu de sample2.rsp :

--no-restore

Voici des règles de syntaxe qui déterminent la façon dont le texte d’un fichier réponse est interprété :

  • Les tokens sont délimités par des espaces. Une ligne qui contient Good morning ! est traitée comme deux jetons, Bonjour et matin !.
  • Plusieurs jetons placés entre guillemets sont interprétés comme un seul jeton. Une ligne qui contient « Bonjour ! » est traitée comme un jeton, Bonjour !.
  • Tout texte entre un # symbole et la fin de la ligne est traité comme un commentaire et ignoré.
  • Les jetons préfixés @ peuvent référencer des fichiers de réponse supplémentaires.
  • Le fichier réponse peut avoir 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 syntactique appelé directive représentée par le Directive type. Par exemple, la [diagram] directive est une directive intégrée. Lorsque vous incluez [diagram] après le nom de l’application, System.CommandLine affiche un diagramme du résultat d’analyse au lieu d’appeler l’application de ligne de commande :

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

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

L’objectif des directives est de fournir des fonctionnalités croisées qui peuvent s’appliquer sur les applications en ligne de commande. Étant donné que les directives sont syntactiquesment distinctes de la syntaxe propre à l’application, elles peuvent fournir des fonctionnalités qui s’appliquent à l’ensemble des applications.

Une directive doit être conforme aux règles de syntaxe suivantes :

  • Il s’agit d’un jeton sur la ligne de commande qui vient après le nom de l’application, mais avant les sous-commandes ou options.
  • Il est placé entre crochets.
  • Il ne contient pas d’espace.

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 un signe deux-points.

Les directives suivantes sont intégrées :

Directive [diagram]

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 System.CommandLine application est la [diagram] directive, qui vous permet d’afficher un aperçu du résultat de l’analyse de l’entrée de commande. Par exemple:

myapp [diagram] --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 enfants et les arguments de ces options sont regroupés à l’aide de crochets.
  • Pour le résultat [ --delay !<not-an-int> ]de l’option, le ! paramètre indique une erreur d’analyse. La valeur not-an-int d’une int option ne peut pas être analysée au type attendu. La présence de l’erreur est également signalée par ! devant la commande qui contient l’option erronée : ![ myapp....
  • Pour le résultat *[ --fgcolor <White> ]de l’option, l’option n’a pas été spécifiée sur la ligne de commande. Par conséquent, 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 l’entrée qui n’a pas été mise en correspondance avec les commandes ou options de l’application.

Suggérer une directive

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

dotnet [suggest] buil

build
build-server
msbuild

Voir aussi

  • Last updated on