Panoramica della sintassi della riga di comando per System.CommandLine

Articolo
04/05/2024

Importante

System.CommandLine è attualmente in ANTEPRIMA e questa documentazione si riferisce alla versione 2.0 beta 4. Alcune informazioni riguardano il prodotto in versione non definitiva che potrebbe essere modificato in modo sostanziale prima del rilascio. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

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

OAuth

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, installdotnet-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 interpreta l'esempio precedente:

Token	Interpretato 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. Ad esempio:

In dotnet run, run è un comando che specifica un'azione.
In dotnet tool install, install è un comando che specifica un'azione e tool è un comando che specifica un gruppo di comandi correlati. Esistono altri comandi correlati agli strumenti, ad esempio tool uninstall, tool list e tool update.

Comandi radice

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

Sottocomandi

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

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

Opzioni

Un'opzione è un parametro denominato che può essere passato a un comando. Le interfacce della riga di comando POSIX in genere antepongono il nome dell'opzione con due trattini (--). L'esempio seguente illustra 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 un valore specificato sono in genere parametri booleani che per impostazione predefinita sono 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. Ad 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.

Argomenti

Un argomento è un valore passato a un'opzione o a un comando. Negli esempi seguenti viene illustrato un argomento per l'opzione verbosity e un argomento per il comando build.

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

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

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

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

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

Alcune opzioni richiedono argomenti obbligatori. Ad esempio, nell'interfaccia della riga di comando di .NET, --output richiede un argomento nome cartella. Se l'argomento non viene fornito, il comando avrà esito negativo.

Gli argomenti possono avere tipi previsti e System.CommandLine visualizza un messaggio di errore se non è possibile analizzare un argomento nel tipo previsto. Ad esempio, il seguente comando genera errori perché "silent" non è uno dei valori validi per --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

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

Ordine di opzioni e argomenti

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

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

Le opzioni possono essere specificate in qualsiasi ordine. I comandi indicati di seguito 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 ha la sua importanza. I comandi seguenti non sono necessariamente equivalenti:

myapp argument1 argument2
myapp argument2 argument1

Questi comandi passano un elenco con gli stessi valori al codice del gestore comandi, ma differiscono nell'ordine dei valori, il che potrebbe portare a risultati diversi.

Alias

Sia in POSIX che in Windows, è comune che alcuni comandi e opzioni abbiano degli alias. Questi alias 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 indicati di seguito 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 forma estesa e questo 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.

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 segue questa convenzione. Se si vuole che l'interfaccia della riga di comando non faccia distinzione tra maiuscole e minuscole, definire gli alias per le varie alternative di maiuscole e minuscole. Ad esempio, --additional-probing-path potrebbe avere come alias --Additional-Probing-Path e --ADDITIONAL-PROBING-PATH.

In alcuni strumenti da riga di comando, una differenza nella combinazione di maiuscole e minuscole specifica una differenza nella funzione. Ad esempio, git clean -X si comporta in modo diverso rispetto a git clean -x. L'interfaccia della riga di comando di .NET è tutta 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.

Il token `--`

La convenzione POSIX interpreta il token con trattino doppio (--) come un 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, poiché impedisce che vengano interpretati come opzioni.

Si supponga che myapp prenda un argomento message, e si voglia 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 token --interactive 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 con trattino doppio per impostare il valore dell'argomento message su "--interactive":

myapp -- --interactive
      ^^

System.CommandLine supporta la funzionalità del trattino doppio.

Delimitatori di opzione-argomento

System.CommandLine consente di usare uno spazio, '=' o ':' come delimitatore tra un nome di opzione e il relativo argomento. Ad esempio, i comandi indicati di seguito 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 indicati di seguito sono equivalenti:

myapp -vquiet
myapp -v quiet

System.CommandLine supporta questa sintassi per impostazione predefinita.

Arità dell'argomento

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.

L'arità viene espressa con un valore minimo e un valore massimo, come illustrato nella tabella seguente:

Min	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:	--flag
		Valido:	--flag true
		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 uno struct ArgumentArity per definire l'arità, con i valori seguenti:

Zero - Nessun valore consentito.
ZeroOrOne - Potrebbe avere un valore, potrebbe non averne.
ExactlyOne - Deve avere un valore.
ZeroOrMore - Potrebbe avere un valore, più valori o nessun valore.
OneOrMore - Potrebbe avere più valori, deve avere almeno un valore.

L'arità può spesso essere dedotta dal tipo. Ad esempio, un'opzione int ha un'arità di ExactlyOne, mentre un'opzione List<int> ha un'arità di OneOrMore.

Override 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 comando myapp.

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

Argomenti multipli

Se il valore massimo di arità è maggiore di uno, System.CommandLine può essere configurato per accettare più argomenti per un'opzione senza ripetere il nome dell'opzione.

Nell'esempio seguente l'elenco passato al comando myapp contiene "a", "b", "c" e "d":

myapp --list a b c --list d

Creazione di bundle di opzioni

POSIX consiglia di supportare la creazione di bundle di opzioni a carattere singolo, note anche come stacking. Le opzioni raggruppate sono alias di opzioni a carattere singolo specificati insieme dopo un singolo prefisso trattino. Solo l'ultima opzione può specificare un argomento. Ad esempio, le righe di comando indicate di seguito sono equivalenti.

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

Se viene specificato un argomento dopo un bundle di opzioni, questo si applica all'ultima opzione nel bundle. Le righe di comando indicate di seguito 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 argomento bool, 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 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 comando myapp 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

L'opzione --help

Le app da riga di comando offrono in genere un'opzione per visualizzare una breve descrizione dei comandi, delle opzioni e degli argomenti disponibili. System.CommandLine genera automaticamente l'output della Guida. Ad esempio:

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.

Gli utenti delle app potrebbero essere abituati a diversi modi per richiedere assistenza su piattaforme diverse, quindi le app basate su System.CommandLine rispondono a molteplici modi per richiedere assistenza. I comandi indicati di seguito sono tutti equivalenti:

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

L'output della Guida non mostra necessariamente tutti i comandi, gli argomenti e le opzioni disponibili. Alcuni di essi possono essere nascosti, il che significa che non vengono visualizzati nell'output della Guida, ma possono essere specificati nella riga di comando.

L'opzione --version

Le app basate su System.CommandLine forniscono automaticamente il numero di versione in risposta all'opzione --version usata con il comando radice. Ad 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 l'input più lungo del limite di caratteri del 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 si desideri inserire comandi, opzioni e argomenti. L'estensione di file .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 Buon giorno! viene considerata come due token, Buon e giorno!.
Più token racchiusi tra virgolette vengono interpretati come un singolo token. Una riga che contiene Buon giorno! viene considerata come due token, Buon giorno!.
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. La direttiva [parse] è un esempio. Quando si include [parse] dopo il nome dell'app, System.CommandLine visualizza un diagramma del risultato dell'analisi invece di richiamare l'app da riga di comando:

dotnet [parse] 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 predefinite:

[parse]
[suggest]

La direttiva `[parse]`

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

myapp [parse] --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 dell'opzione [ --delay !<not-an-int> ], ! 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 con errore: ![ myapp....
Per il risultato dell'opzione *[ --fgcolor <White> ], 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.

La direttiva `[suggest]`

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

dotnet [suggest] buil

build
build-server
msbuild

Indicazioni per la progettazione

Le sezioni seguenti presentano indicazioni che è consigliabile seguire durante la progettazione di un'interfaccia della riga di comando. Si consideri l'aspetto previsto dall'app nella riga di comando come quello previsto da un server API REST nell'URL. Le regole coerenti per le API REST sono ciò che li rende facilmente utilizzabili per gli sviluppatori di app client. Allo stesso modo, gli utenti delle app da riga di comando avranno un'esperienza migliore se la progettazione dell'interfaccia della riga di comando segue modelli comuni.

Dopo aver creato un'interfaccia della riga di comando, è difficile modificare, soprattutto se gli utenti hanno usato l'interfaccia della riga di comando negli script che si aspettano continuino a funzionare. Le linee guida sono state sviluppate dopo l'interfaccia della riga di comando di .NET e non sempre seguono queste linee guida. È in corso l'aggiornamento dell'interfaccia della riga di comando di .NET in cui è possibile eseguire questa operazione senza introdurre modifiche di rilievo. Un esempio di questo lavoro è il nuovo progetto per dotnet new in .NET 7.

Comandi e sottocomandi

Se un comando dispone di sottocomandi, il comando deve funzionare come area o come identificatore di raggruppamento per i sottocomandi, anziché specificare un'azione. Quando si richiama l'app, specificare il comando di raggruppamento e uno dei relativi sottocomandi. Ad esempio, se si prova a eseguire dotnet tool viene visualizzato un messaggio di errore perché il comando tool identifica solo un gruppo di sottocomandi correlati allo strumento, ad esempio install e list. È possibile eseguire dotnet tool install, ma dotnet tool da solo risulterebbe incompleto.

Uno dei modi per definire le aree consente agli utenti di organizzare l'output della Guida.

All'interno di un'interfaccia della riga di comando è spesso presente un'area implicita. Nell'interfaccia della riga di comando di .NET, ad esempio, l'area implicita è il progetto e nell'interfaccia della riga di comando di Docker è l'immagine. Di conseguenza, è possibile usare dotnet build senza includere un'area. Valutare se l'interfaccia della riga di comando ha un'area implicita. In caso affermativo, valutare se consentire all'utente di includere o ometterlo come in docker build e docker image build. Se facoltativamente si consente la digitazione dell'area implicita da parte dell'utente, si dispone anche automaticamente della Guida e del completamento della scheda per questo raggruppamento di comandi. Specificare l'uso facoltativo del gruppo implicito definendo due comandi che eseguono la stessa operazione.

Opzioni come parametri

Le opzioni devono fornire parametri ai comandi, anziché specificare le azioni stesse. Si tratta di un principio di progettazione consigliato, anche se non sempre seguito da System.CommandLine (--help visualizza le informazioni della Guida).

Alias in formato breve

In generale, è consigliabile ridurre al minimo il numero di alias di opzioni di forma breve definiti dall'utente.

In particolare, evitare di usare uno degli alias seguenti in modo diverso rispetto all'uso comune nell'interfaccia della riga di comando di .NET e in altre app della riga di comando .NET:

-i per --interactive.

Questa opzione segnala all'utente che potrebbe essere richiesto l'input alle domande a cui il comando deve rispondere. Ad esempio, richiedendo un nome utente. L'interfaccia della riga di comando può essere usata negli script, quindi prestare attenzione per richiedere agli utenti che non hanno specificato questa opzione.
-o per --output.

Alcuni comandi producono file come risultato dell'esecuzione. Questa opzione deve essere usata per determinare dove devono trovarsi tali file. Nei casi in cui viene creato un singolo file, questa opzione deve essere un percorso di file. Nei casi in cui vengono creati molti file, questa opzione deve essere un percorso di directory.
-v per --verbosity.

I comandi spesso forniscono l'output all'utente nella console; questa opzione viene usata per specificare la quantità di output richieste dall'utente. Per ulteriori informazioni, vedere l'--verbosityopzione più avanti in questo articolo.

Esistono anche alcuni alias con utilizzo comune limitato all'interfaccia della riga di comando di .NET. È possibile usare questi alias per altre opzioni nelle app, ma tenere presente la possibilità di confusione.

-c per --configuration

Questa opzione spesso fa riferimento a una configurazione di compilazione denominata, ad esempio Debug o Release. È possibile usare qualsiasi nome desiderato per una configurazione, ma la maggior parte degli strumenti prevede uno di questi. Questa impostazione viene spesso usata per configurare altre proprietà in modo appropriato per tale configurazione, ad esempio un'ottimizzazione del codice inferiore durante la compilazione della configurazione Debug. Prendere in considerazione questa opzione se il comando ha modalità diverse di funzionamento.
-f per --framework

Questa opzione viene usata per selezionare un singolo moniker del framework di destinazione (TFM) da eseguire, quindi se l'applicazione dell'interfaccia della riga di comando ha un comportamento diverso in base al tfm scelto, è necessario supportare questo flag.
-p per --property

Se l'applicazione richiama infine MSBuild, l'utente dovrà spesso personalizzare tale chiamata in qualche modo. Questa opzione consente di specificare le proprietà di MSBuild nella riga di comando e passate alla chiamata MSBuild sottostante. Se l'app non usa MSBuild ma richiede un set di coppie chiave-valore, è consigliabile usare questo stesso nome di opzione per sfruttare le aspettative degli utenti.
-r per --runtime

Se l'applicazione può essere eseguita in runtime diversi o ha una logica specifica del runtime, è consigliabile supportare questa opzione come metodo per specificare un identificatore di runtime. Se l'app supporta --runtime, è consigliabile supportare --os e anche --arch. Queste opzioni consentono di specificare solo il sistema operativo o le parti dell'architettura del RID, lasciando la parte non specificata per essere determinata dalla piattaforma corrente. Per altre informazioni, vedere dotnet publish.

Nomi brevi

Consente di creare nomi per comandi, opzioni e argomenti il più brevi e semplici da scrivere possibile. Ad esempio, se class è abbastanza chiaro, non usare il comando classification.

Nomi in minuscolo

Definire i nomi solo in lettere minuscole, tranne che è possibile creare alias maiuscoli per fare in modo che i comandi o le opzioni non facciano distinzione tra maiuscole e minuscole.

Nomi in case kebab

Usare il caso kebab per distinguere le parole. Ad esempio: --additional-probing-path.

Pluralizzazione

All'interno di un'app, essere coerenti nella pluralizzazione. Ad esempio, non combinare nomi plurali e singolari per le opzioni che possono avere più valori (maggiore di uno):

Nomi opzioni	Coerenza
`--additional-probing-paths` e `--sources`	✔️
`--additional-probing-path` e `--source`	✔️
`--additional-probing-paths` e `--source`	❌
`--additional-probing-path` e `--sources`	❌

Verbi e sostantivi

Usare verbi anziché sostantivi per i comandi che fanno riferimento alle azioni (quelle senza sottocomandi), ad esempio: dotnet workload remove, non dotnet workload removal. E usare sostantivi anziché verbi per le opzioni, ad esempio, --configuration, non --configure.

L'opzione `--verbosity`

Le applicazioni System.CommandLine offrono in genere un'opzione --verbosity che specifica la quantità di output inviata alla console. Ecco le cinque impostazioni standard:

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

Questi sono i nomi standard, ma le app esistenti talvolta usano Silent al posto di Quiet, e Trace, Debug o Verbose al posto di Diagnostic.

Ogni app definisce i propri criteri che determinano cosa viene visualizzato a ogni livello. In genere un'app richiede solo tre livelli:

Quiet
Normale
Diagnostic

Se un'app non richiede cinque livelli diversi, l'opzione deve comunque definire le stesse cinque impostazioni. In tal caso, Minimal e Normal produrranno lo stesso output, e Detailed e Diagnostic saranno uguali. Ciò consente agli utenti di digitare semplicemente ciò che hanno familiarità con e verrà usata la scelta migliore.

Si prevede che per Quiet non venga visualizzato alcun output nella console. Tuttavia, se un'app offre una modalità interattiva, l'app deve eseguire una delle alternative seguenti:

Visualizza le richieste di input quando --interactive viene specificato, anche se --verbosity è Quiet.
Non consentire l'uso di --verbosity Quiet e --interactive insieme.

In caso contrario, l'app attenderà l'input senza indicare all'utente cosa sta aspettando. Verrà visualizzato che l'applicazione si blocca e l'utente non avrà idea che l'applicazione sia in attesa di input.

Se si definiscono alias, usare -v per --verbosity e creare -v senza un argomento un alias per --verbosity Diagnostic. Usare -q per --verbosity Quiet.

Convenzioni dell'interfaccia della riga di comando di .NET e POSIX

L'interfaccia della riga di comando di .NET non segue in modo coerente tutte le convenzioni POSIX.

Trattino doppio

Diversi comandi nell'interfaccia della riga di comando di .NET hanno un'implementazione speciale del token a trattino doppio. Nel caso di dotnet run, dotnet watch e dotnet tool run, i token che seguono -- vengono passati all'app eseguita dal comando. Ad esempio:

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

In questo esempio l'opzione --project viene passata al comando dotnet run e l'opzione --message con il relativo argomento viene passata come opzione della riga di comando a myapp durante l'esecuzione.

Il token -- non è sempre necessario per passare le opzioni a un'app eseguita tramite dotnet run. Senza il trattino doppio, il comando dotnet run passa automaticamente all'app in esecuzione tutte le opzioni non riconosciute come applicabili a dotnet run stesso o a MSBuild. Le righe di comando seguenti sono quindi equivalenti perché dotnet run non riconosce gli argomenti e le opzioni:

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

Omissione del delimitatore opzione-argomento

L'interfaccia della riga di comando di .NET non supporta la convenzione POSIX che consente di omettere il delimitatore quando si specifica un alias di opzione a carattere singolo.

Argomenti multipli senza ripetere il nome dell'opzione

L'interfaccia della riga di comando di .NET non accetta più argomenti per un'opzione senza ripetere il nome dell'opzione.

Opzioni booleane

Nell'interfaccia della riga di comando di .NET alcune opzioni booleane comportano lo stesso comportamento quando si passa false come quando si passa true. Questo comportamento determina quando il codice dell'interfaccia della riga di comando di .NET che implementa l'opzione controlla solo la presenza o l'assenza dell'opzione, ignorando il valore. Un esempio è --no-restore per il comando dotnet build. Se si passa no-restore false, l'operazione di ripristino verrà ignorata come quando si specifica no-restore true o no-restore.

Caso kebab

In alcuni casi, l'interfaccia della riga di comando di .NET non usa il case kebab per i nomi di comandi, opzioni o argomenti. Ad esempio, è disponibile un'opzione dell'interfaccia della riga di comando di .NET denominata --additionalprobingpath anziché --additional-probing-path.

Share via