Condividi tramite

Panoramica della sintassi: Comandi, opzioni e argomenti

Importante

System.CommandLine è attualmente disponibile in ANTEPRIMA e questa documentazione è per la versione 2.0 beta 5. Alcune informazioni riguardano il prodotto in fase di pre-rilascio che potrebbe essere modificato in modo sostanziale prima del rilascio. Microsoft non fornisce alcuna garanzia, espressa o implicita, in relazione alle informazioni fornite qui.

Questo articolo illustra la sintassi della riga di comando che System.CommandLine riconosce. Le informazioni sono utili sia per gli utenti che per gli sviluppatori di app da riga di comando .NET, inclusa l'interfaccia della riga di comando di .NET.

Token

System.CommandLine analizza l'input della riga di comando in token, ovvero stringhe delimitate da spazi. Si consideri ad esempio la riga di comando seguente:

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

Questo input viene analizzato dall'applicazione dotnet in token tool, install, dotnet-suggest, --global, --verbosity e quiet.

I token vengono interpretati come comandi, opzioni o argomenti. L'app da riga di comando richiamata determina come vengono interpretati i token dopo il primo. La tabella seguente illustra come System.CommandLine interpretare l'esempio precedente:

Token di accesso Analizzato come
tool Sottocomando
install Sottocomando
dotnet-suggest Argomento per il comando di installazione
--global Opzione per il comando di installazione
--verbosity Opzione per il comando di installazione
quiet Argomento per l'opzione --verbosity

Un token può contenere spazi se è racchiuso tra virgolette ("). Ecco un esempio:

dotnet tool search "ef migrations add"

Comandi

Un comando nell'input della riga di comando è un token che specifica un'azione o definisce un gruppo di azioni correlate. Per esempio:

  • In dotnet run, run è un comando che specifica un'azione.
  • dotnet tool install In installè un comando che specifica un'azione ed tool è un comando che specifica un gruppo di comandi correlati. Sono disponibili altri comandi correlati agli strumenti, ad esempio tool uninstall, tool liste tool update.

Comando principale

Il comando radice è quello che specifica il nome dell'eseguibile dell'app. Ad esempio, il comando dotnet specifica l'eseguibile dotnet.exe.

System.CommandLine.Command è la classe per utilizzo generico per qualsiasi comando o sottocomando, mentre System.CommandLine.RootCommand è una versione specializzata destinata al punto di ingresso radice dell'applicazione, ereditando tutte le funzionalità di ma aggiungendo comportamenti e impostazioni predefinite specifiche della System.CommandLine.Command radice, ad esempio l'opzione Guida, l'opzione Version e la direttiva Suggest.

Sottocomandi

La maggior parte delle app della riga di comando supporta i sottocomandi, noti anche come verbi. Ad esempio, il dotnet comando ha un run sottocomando che si richiama immettendo dotnet run.

I sottocomandi possono avere sottocomandi propri. In dotnet tool install, install è un sottocomando di tool.

È possibile aggiungere sottocomandi come illustrato nell'esempio seguente:

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);

Il sottocomando più interno in questo esempio può essere richiamato come segue:

myapp sub1 sub1a

Opzioni

Un'opzione è un parametro denominato che può essere passato a un comando. POSIX interfacce CLI in genere prefissano il nome dell'opzione con due trattini (--). L'esempio seguente mostra due opzioni:

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

Come illustrato in questo esempio, il valore dell'opzione può essere esplicito (quiet per --verbosity) o implicito (nulla segue --global). Le opzioni senza valore specificato sono in genere parametri booleani che per impostazione predefinita sono impostati su true se l'opzione è specificata nella riga di comando.

Per alcune app della riga di comando di Windows, è possibile identificare un'opzione usando una barra iniziale (/) con il nome dell'opzione. Per esempio:

msbuild /version
        ^------^

System.CommandLine supporta sia le convenzioni dei prefissi POSIX che di Windows.

Quando si configura un'opzione, specificare il nome dell'opzione, incluso il prefisso:

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);

Per aggiungere un'opzione a un comando e in modo ricorsivo a tutti i relativi sottocomandi, utilizzare la System.CommandLine.Symbol.Recursive proprietà .

Opzioni obbligatorie

Alcune opzioni hanno argomenti obbligatori. Ad esempio, nell'interfaccia della riga di comando di .NET, --output richiede un argomento che sia il nome di una cartella. Se l'argomento non viene specificato, il comando ha esito negativo. Per rendere obbligatoria un'opzione, impostarne la System.CommandLine.Symbol.Required proprietà su true, come illustrato nell'esempio seguente:

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

Se un'opzione obbligatoria ha un valore predefinito (specificato tramite DefaultValueFactory la proprietà ), l'opzione non deve essere specificata nella riga di comando. In tal caso, il valore predefinito fornisce il valore dell'opzione richiesto.

Argomenti

Un argomento è un parametro senza nome che può essere passato a un comando. Nell'esempio seguente viene illustrato un argomento per il build comando .

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

Quando si configura un argomento, si specifica il nome dell'argomento (non viene usato per l'analisi, ma può essere usato per ottenere valori analizzati in base al nome o visualizzare la Guida) e digitare:

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);

Valori predefiniti

Entrambi gli argomenti e le opzioni possono avere valori predefiniti che si applicano se non viene specificato in modo esplicito alcun argomento. Ad esempio, molte opzioni sono parametri booleani in modo implicito con un valore predefinito true quando il nome dell'opzione si trova nella riga di comando. Gli esempi della riga di comando seguenti sono equivalenti:

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

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

Un argomento definito senza un valore predefinito viene considerato come argomento obbligatorio.

Analizzare gli errori

Le opzioni e gli argomenti hanno tipi previsti e viene generato un errore quando il valore non può essere analizzato. Ad esempio, gli errori di comando seguenti perché "silent" non è uno dei valori validi per --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'

Gli argomenti hanno anche aspettative sul numero di valori che è possibile specificare. Nella sezione relativa all'argomento arity vengono forniti esempi.

Ordine di opzioni e argomenti

È possibile fornire opzioni prima degli argomenti o degli argomenti prima delle opzioni nella riga di comando. I comandi seguenti sono equivalenti:

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

Le opzioni possono essere specificate in qualsiasi ordine. I comandi seguenti sono equivalenti:

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

Quando sono presenti più argomenti, l'ordine è importante. I comandi seguenti non sono equivalenti; differiscono nell'ordine dei valori, che potrebbero portare a risultati diversi:

myapp argument1 argument2
myapp argument2 argument1

Alias

Sia in POSIX che in Windows, è comune che alcuni comandi e opzioni abbiano alias. Queste sono in genere forme brevi che sono più facili da digitare. Gli alias possono essere usati anche per altri scopi, ad esempio per simulare la distinzione tra maiuscole e minuscole e per supportare ortografie alternative di una parola.

Le forme brevi POSIX in genere hanno un singolo trattino iniziale seguito da un singolo carattere. I comandi seguenti sono equivalenti:

dotnet build --verbosity quiet
dotnet build -v quiet

Lo standard GNU consiglia gli alias automatici. Ovvero, è possibile immettere qualsiasi parte di un comando o di un nome di opzione in formato lungo e verrà accettato. Questo comportamento renderebbe equivalenti le righe di comando seguenti:

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 non supporta gli alias automatici. Ogni alias deve essere specificato in modo esplicito. Entrambi i comandi e le opzioni espongono una Aliases proprietà. Option ha un costruttore che accetta alias come parametri, quindi è possibile definire un'opzione con più alias in una singola riga:

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

È consigliabile ridurre al minimo il numero di alias di opzione definiti ed evitare di definire determinati alias in particolare. Per ulteriori informazioni, vedere alias in forma breve.

Distinzione tra maiuscole e minuscole

I nomi dei comandi e delle opzioni e gli alias fanno distinzione tra maiuscole e minuscole per impostazione predefinita in base alla convenzione POSIX e System.CommandLine seguono questa convenzione. Se si vuole che il CLI sia insensibile alle maiuscole, definire gli alias per le varie alternative di maiuscole e minuscole. Ad esempio, --additional-probing-path potrebbe avere alias --Additional-Probing-Path e --ADDITIONAL-PROBING-PATH.

In alcuni strumenti da riga di comando, una differenza nelle maiuscole e minuscole specifica una differenza nella funzione. Ad esempio, git clean -X si comporta in modo diverso rispetto a git clean -x. L'acronimo .NET CLI è tutto in minuscolo.

La distinzione tra maiuscole e minuscole non si applica ai valori degli argomenti per le opzioni basate su enumerazioni. I nomi delle enumerazioni vengono confrontati indipendentemente dalla combinazione di maiuscole e minuscole.

Token --

La convenzione POSIX interpreta il token con trattino doppio (--) come meccanismo di escape. Tutto ciò che segue il token a trattino doppio viene interpretato come argomenti per il comando. Questa funzionalità può essere usata per inviare argomenti simili alle opzioni, perché impedisce che vengano interpretati come opzioni.

Supponi che myapp prenda un message argomento e desideri che il valore di message sia --interactive. La riga di comando seguente potrebbe restituire risultati imprevisti.

myapp --interactive

Se myapp non ha un'opzione --interactive , il --interactive token viene interpretato come argomento. Tuttavia, se l'app ha un'opzione --interactive , questo input verrà interpretato come riferimento a tale opzione.

La riga di comando seguente usa il token double-dash per impostare il valore dell'argomento message su "--interactive":

myapp -- --interactive
      ^^

System.CommandLine supporta questa funzionalità a trattino doppio.

Delimitatori di argomento di opzione

System.CommandLine consente di usare uno spazio, '=' o ':' come delimitatore tra un nome di opzione e il relativo argomento. Ad esempio, i comandi seguenti sono equivalenti:

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

Una convenzione POSIX consente di omettere il delimitatore quando si specifica un alias di opzione a carattere singolo. Ad esempio, i comandi seguenti sono equivalenti:

myapp -vquiet
myapp -v quiet

System.CommandLine supporta questa sintassi per impostazione predefinita.

Arità degli argomenti

L'arità dell'argomento di un'opzione o di un comando è il numero di valori che è possibile passare se viene specificata l'opzione o il comando.

Arity viene espresso con un valore minimo e un valore massimo, come illustrato nella tabella seguente:

Minuti Max Validità di esempio Esempio
0 0 Valido --file
Non valido: --file a.json
Non valido: --file a.json --file b.json
0 1 Valido --bandiera
Valido --flag vero
Valido --flag false
Non valido: --flag false --flag false
1 1 Valido --file a.json
Non valido: --file
Non valido: --file a.json --file b.json
0 n Valido --file
Valido --file a.json
Valido --file a.json --file b.json
1 n Valido --file a.json
Valido --file a.json b.json
Non valido: --file

System.CommandLine ha un System.CommandLine.ArgumentArity struct per definire l'arità, con i valori seguenti:

  • System.CommandLine.ArgumentArity.Zero - Nessun valore consentito.
  • System.CommandLine.ArgumentArity.ZeroOrOne - Può avere un valore, potrebbe non avere valori.
  • System.CommandLine.ArgumentArity.ExactlyOne - Deve avere un valore.
  • System.CommandLine.ArgumentArity.ZeroOrMore - Può avere un valore, più valori o nessun valore.
  • System.CommandLine.ArgumentArity.OneOrMore - Può avere più valori, deve avere almeno un valore.

È possibile impostare esplicitamente l'arità usando la Arity proprietà, ma nella maggior parte dei casi non è necessario. System.CommandLine determina automaticamente l'arità dell'argomento in base al tipo di argomento:

Tipo di argomento Arity predefinita
Boolean ArgumentArity.ZeroOrOne
Tipi di raccolta ArgumentArity.ZeroOrMore
Tutti gli altri elementi ArgumentArity.ExactlyOne

Sostituzioni di opzioni

Se il valore massimo di arità è 1, System.CommandLine può comunque essere configurato per accettare più istanze di un'opzione. In tal caso, l'ultima istanza di un'opzione ripetuta sovrascrive tutte le istanze precedenti. Nell'esempio seguente il valore 2 viene passato al myapp comando .

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

Più argomenti

Per impostazione predefinita, quando si chiama un comando, è possibile ripetere un nome di opzione per specificare più argomenti per un'opzione con la massima arità maggiore di una.

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

Per consentire più argomenti senza ripetere il nome dell'opzione, impostare System.CommandLine.Option.AllowMultipleArgumentsPerToken su true. Questa impostazione consente di immettere la riga di comando seguente.

myapp --items one two three

La stessa impostazione ha un effetto diverso se l'arità massima dell'argomento è 1. Consente di ripetere un'opzione, ma accetta solo l'ultimo valore sulla riga. Nell'esempio seguente il valore three viene passato all'app.

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

Creazione di bundle di opzioni

POSIX consiglia di supportare il raggruppamento di opzioni a carattere singolo, note anche come impilamento. Le opzioni raggruppate sono alias di opzione a carattere singolo specificati insieme dopo un singolo prefisso trattino. Solo l'ultima opzione può specificare un argomento. Ad esempio, le righe di comando seguenti sono equivalenti:

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

Se viene specificato un argomento dopo un bundle di opzioni, si applica all'ultima opzione nel bundle. Le righe di comando seguenti sono equivalenti:

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

In entrambe le varianti di questo esempio, l'argomento arg si applica solo all'opzione -c.

Opzioni booleane (flag)

Se true o false viene passato per un'opzione con un bool argomento, viene analizzato come previsto. Tuttavia, un'opzione il cui tipo di argomento è bool in genere non richiede che venga specificato un argomento. Le opzioni booleane, talvolta denominate "flag", in genere hanno un'arità di System.CommandLine.ArgumentArity.ZeroOrOne. La presenza del nome dell'opzione nella riga di comando, senza alcun argomento che lo segue, restituisce un valore predefinito di true. L'assenza del nome dell'opzione nell'input della riga di comando restituisce un valore di false. Se il myapp comando stampa il valore di un'opzione booleana denominata --interactive, l'input seguente crea l'output seguente:

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

False
True
False
True

Opzione Versione

Le app basate su System.CommandLine forniscono automaticamente il numero di versione in risposta all'opzione --version usata con il comando radice. Per esempio:

dotnet --version

6.0.100

File di risposta

Un file di risposta è un file che contiene un set di token per un'app da riga di comando. I file di risposta sono una funzionalità di System.CommandLine utile in due scenari:

  • Per richiamare un'app della riga di comando specificando un input superiore al limite di caratteri consentito dal terminale.
  • Per richiamare ripetutamente lo stesso comando senza digitare nuovamente l'intera riga.

Per usare un file di risposta, immettere il nome del file preceduto da un @ segno ovunque nella riga che si desidera inserire comandi, opzioni e argomenti. L'estensione di file con estensione rsp è una convenzione comune, ma è possibile usare qualsiasi estensione di file.

Le righe seguenti sono equivalenti:

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

Contenuto di sample1.rsp:

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

Contenuto di sample2.rsp:

--no-restore

Ecco le regole di sintassi che determinano come viene interpretato il testo in un file di risposta:

  • I token sono delimitati da spazi. Una riga che contiene Buongiorno! viene trattata come due token: Buon e giorno!.
  • Più token racchiusi tra virgolette vengono interpretati come un singolo token. Una riga che contiene "Buongiorno!" viene considerata come un token, Buongiorno!.
  • Qualsiasi testo tra un # simbolo e la fine della riga viene considerato come commento e ignorato.
  • I token preceduti da @ possono fare riferimento a file di risposta aggiuntivi.
  • Il file di risposta può avere più righe di testo. Le righe vengono concatenate e interpretate come una sequenza di token.

Direttive

System.CommandLine introduce un elemento sintattico denominato direttiva rappresentata dal System.CommandLine.Directive tipo . La [diagram] direttiva è un esempio. Quando includi [diagram] dopo il nome dell'app, System.CommandLine visualizza un diagramma del risultato dell'analisi invece di richiamare l'app da riga di comando:

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

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

Lo scopo delle direttive è fornire funzionalità trasversali che possono essere applicate tra le app della riga di comando. Poiché le direttive sono sintatticamente distinte dalla sintassi dell'app, possono fornire funzionalità che si applicano tra le app.

Una direttiva deve essere conforme alle regole di sintassi seguenti:

  • Si tratta di un token nella riga di comando che segue il nome dell'app, ma prima di qualsiasi sottocomando o opzione.
  • È racchiuso tra parentesi quadre.
  • Non contiene spazi.

Una direttiva non riconosciuta viene ignorata senza causare un errore di analisi.

Una direttiva può includere un argomento, separato dal nome della direttiva da due punti.

Le direttive seguenti sono incorporate:

La direttiva [diagram]

Sia gli utenti che gli sviluppatori potrebbero trovare utile vedere come l'app interpreterà un determinato input. Una delle funzionalità predefinite di un'app System.CommandLine è la [diagram] direttiva, che consente di visualizzare in anteprima il risultato dell'analisi del comando. Per esempio:

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

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

Nell'esempio precedente:

  • Il comando (myapp), le opzioni figlio e gli argomenti di tali opzioni vengono raggruppati usando parentesi quadre.
  • Per il risultato [ --delay !<not-an-int> ]dell'opzione , indica ! un errore di analisi. Il valore not-an-int di un'opzione int non può essere analizzato nel tipo previsto. L'errore viene contrassegnato anche da ! davanti al comando che contiene l'opzione errored: ![ myapp....
  • Per il risultato *[ --fgcolor <White> ]dell'opzione , l'opzione non è stata specificata nella riga di comando, quindi è stata usata l'impostazione predefinita configurata. White è il valore effettivo per questa opzione. L'asterisco indica che il valore è il valore predefinito.
  • ???--> punta all'input che non corrisponde a nessun comando o opzione dell'app.

Direttiva Suggerisci

La [suggest] direttiva consente di cercare i comandi quando non si conosce il comando esatto.

dotnet [suggest] buil

build
build-server
msbuild

Vedere anche