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

2025-06-22

Important

System.CommandLine est actuellement disponible en préversion et cette documentation concerne la version 2.0 bêta 5. Certaines informations se rapportent à un produit en version préliminaire qui peut être sensiblement modifié avant sa sortie. Microsoft n’offre aucune garantie, expresse ou implicite, en ce qui concerne les informations fournies ici.

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 en jetons tool, , install, dotnet-suggest--global, , --verbosity, et quiet.dotnet

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 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"

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 dotnet commande spécifie l’exécutabledotnet.exe .

System.CommandLine.Command est la classe à usage général pour n’importe quelle commande ou sous-commande, tandis qu’elle System.CommandLine.RootCommand est une version spécialisée destinée au point d’entrée racine de l’application, hérite de toutes les fonctionnalités de l’ajout d’un System.CommandLine.Command 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 requise, définissez sa System.CommandLine.Symbol.Required propriété truesur , 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 DefaultValueFactory la 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 des paramètres booléens implicitement avec une valeur par défaut lorsque le nom de true 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 arguments avant les options de 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 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 qui sont plus faciles à taper. Les alias peuvent également être utilisés à d’autres fins, par exemple pour simuler l’insensitivité de la casse et prendre en charge d’autres orthographes 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 de formulaire long 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 de formulaire court.

Respect de la casse

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

Dans certains outils en ligne de commande, une différence dans la 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é de 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 de double tiret (--) comme 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 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 aucune option n’est --interactive disponible, le --interactive jeton 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	Valable:	--lime
		Non valide:	--file a.json
		Non valide:	--file a.json --file b.json
0	1	Valable:	--drapeau
		Valable:	--flag true
		Valable:	--flag false
		Non valide:	--flag false --flag false
1	1	Valable:	--file a.json
		Non valide:	--lime
		Non valide:	--file a.json --file b.json
0	n	Valable:	--lime
		Valable:	--file a.json
		Valable:	--file a.json --file b.json
1	n	Valable:	--file a.json
		Valable:	--file a.json b.json
		Non valide:	--lime

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

System.CommandLine.ArgumentArity.Zero - Aucune valeur autorisée.
System.CommandLine.ArgumentArity.ZeroOrOne - Peut avoir une valeur, peut ne pas avoir de valeurs.
System.CommandLine.ArgumentArity.ExactlyOne - Doit avoir une valeur.
System.CommandLine.ArgumentArity.ZeroOrMore - Peut avoir une valeur, plusieurs valeurs ou aucune valeur.
System.CommandLine.ArgumentArity.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 collections	`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 sur System.CommandLine.Option.AllowMultipleArgumentsPerTokentrue. 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’option à caractère unique spécifiés ensemble après un préfixe de trait d’union unique. 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)

false S’il true est passé pour une option ayant un bool argument, 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 System.CommandLine.ArgumentArity.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 réponse, entrez le nom de fichier précédé d’un @ signe où que vous soyez dans la ligne que vous souhaitez 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 jetons 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 System.CommandLine.Directive type. La [diagram] directive est un exemple. 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.
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 un signe deux-points.

Les directives suivantes sont intégrées :

[diagram]
[suggest]

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. L’erreur est également signalée devant ! la commande qui contient l’option d’erreur : ![ 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