Condividi tramite

Indicazioni per la progettazione

Le sezioni seguenti contengono indicazioni per 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 modificarla, soprattutto se gli utenti hanno usato l'interfaccia della riga di comando negli script che si aspettano di continuare a funzionare.

Simboli

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, provare a eseguire dotnet toole viene visualizzato un messaggio di errore perché il tool comando identifica solo un gruppo di sottocomandi correlati allo strumento, ad esempio install e list. È possibile eseguire dotnet tool install, ma dotnet tool da solo sarebbe 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 facoltativamente, come in docker build e docker image build. Se consenti facoltativamente agli utenti di digitare nell'area implicita, hai automaticamente anche accesso alla guida e al completamento automatico 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 rispettato da System.CommandLine (--help visualizza le informazioni di aiuto).

Denominazione

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 potrebbero essere richiesti input per domande a cui il comando deve rispondere. Ad esempio, richiedendo un nome utente. L'interfaccia della riga di comando potrebbe 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 altre informazioni, vedere L'opzione --verbosity 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 Debug configurazione. 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 CLI ha un comportamento diverso in base al TFM scelto, dovresti 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, prendere in considerazione il supporto --os e --arch anche. 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

Fai in modo che i nomi per i comandi, le opzioni e gli argomenti siano il più brevi e facili da scrivere possibile. Ad esempio, se class è abbastanza chiaro, non impostare il comando classification.

Nomi minuscoli

Definire i nomi solo in lettere minuscole, ma è possibile creare alias in maiuscolo per rendere i comandi o le opzioni senza distinzione tra maiuscole e minuscole.

Nomi in stile kebab case

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 al plurale e al singolare per le opzioni che possono avere valori multipli (con arità massima superiore a uno):

Nomi delle opzioni Consistenza
--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.

Opzione --verbosity

System.CommandLine le applicazioni 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]

Si tratta dei nomi standard, ma le app esistenti talvolta usano Silent al posto di Quiet, e Trace, Debugo 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:

  • Tranquillo
  • Normale
  • Diagnostico

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 allo stesso modo. Ciò consente agli utenti di digitare semplicemente ciò che hanno familiarità con e verrà usata la scelta migliore.

Si prevede Quiet che nella console non venga visualizzato alcun output. Tuttavia, se un'app offre una modalità interattiva, l'app deve eseguire una delle operazioni 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 rendere -v un alias, senza un argomento, per --verbosity Diagnostic. Usare -q per --verbosity Quiet.

Convenzioni della CLI di .NET e di 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 watche dotnet tool run, i token che seguono -- vengono passati all'app eseguita dal comando . Per esempio:

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

In questo esempio l'opzione --project viene passata al dotnet run comando 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 dotnet run comando passa automaticamente all'app in esecuzione tutte le opzioni non riconosciute come applicabili a dotnet run se 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-a-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.

Più argomenti 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 si verifica 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. Passare --no-restore false e 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, nell'interfaccia a riga di comando di .NET, è disponibile un'opzione denominata --additionalprobingpath anziché --additional-probing-path.

Vedere anche

  • Last updated on