Condividi tramite

Linee guida sullo sviluppo vivamente consigliate

  • Articolo

Questa sezione descrive le linee guida da seguire quando si scrivono i cmdlet. Sono suddivisi in linee guida per la progettazione di cmdlet e linee guida per la scrittura del codice dei cmdlet. È possibile che queste linee guida non siano applicabili per ogni scenario. Tuttavia, se si applicano e non si seguono queste linee guida, gli utenti potrebbero avere un'esperienza scadente quando usano i cmdlet.

Linee guida per la progettazione

Quando si progettano i cmdlet, è necessario seguire le linee guida seguenti per garantire un'esperienza utente coerente tra l'uso dei cmdlet e di altri cmdlet. Quando si trovano linee guida di progettazione applicabili alla situazione specifica, assicurarsi di esaminare le linee guida per il codice per linee guida simili.

Usare un sostantivo specifico per il nome di un cmdlet (SD01)

I nomi usati nella denominazione dei cmdlet devono essere molto specifici in modo che l'utente possa individuare i cmdlet. Prefissi nomi generici, ad esempio "server" con una versione abbreviata del nome del prodotto. Ad esempio, se un sostantivo fa riferimento a un server che esegue un'istanza di Microsoft SQL Server, usare un sostantivo come "SQLServer". La combinazione di sostantivi specifici e l'elenco breve di verbi approvati consentono all'utente di individuare e prevedere rapidamente le funzionalità evitando la duplicazione tra i nomi dei cmdlet.

Per migliorare l'esperienza utente, il sostantivo scelto per il nome di un cmdlet deve essere singolare. Ad esempio, usare il nome Get-Process anziché Get-Processes . È meglio seguire questa regola per tutti i nomi di cmdlet, anche quando è probabile che un cmdlet agirà su più di un elemento.

Usare la convenzione Pascal per i nomi dei cmdlet (SD02)

Usare la convenzione Pascal per i nomi dei parametri. In altre parole, convertire in maiuscolo la prima lettera del verbo e tutti i termini usati nel sostantivo. Ad esempio, "Clear-ItemProperty".

Linee guida per la progettazione di parametri (SD03)

Un cmdlet richiede parametri che ricevono i dati su cui deve operare e parametri che indicano le informazioni usate per determinare le caratteristiche dell'operazione. Ad esempio, un cmdlet potrebbe avere un parametro che riceve dati dalla pipeline e il cmdlet potrebbe avere un parametro per indicare che è possibile forzare il cmdlet a eseguire Name Force l'operazione. Non esiste alcun limite al numero di parametri che un cmdlet può definire.

Usare nomi di parametri standard

Il cmdlet deve usare nomi di parametro standard in modo che l'utente possa determinare rapidamente il significato di un determinato parametro. Se è necessario un nome più specifico, usare un nome di parametro standard e quindi specificare un nome più specifico come alias. Ad esempio, il cmdlet ha un parametro con un nome Get-Service generico ( ) e un alias più specifico ( Name ServiceName ). Entrambi i termini possono essere usati per specificare il parametro .

Per altre informazioni sui nomi dei parametri e sui relativi tipi di dati, vedere Cmdlet Parameter Name and Functionality Guidelines.

Usare nomi di parametro singolari

Evitare di usare nomi plurali per i parametri il cui valore è un singolo elemento. Sono inclusi i parametri che accettano matrici o elenchi perché l'utente potrebbe fornire una matrice o un elenco con un solo elemento.

I nomi dei parametri plurali devono essere usati solo nei casi in cui il valore del parametro è sempre un valore a più elementi. In questi casi, il cmdlet deve verificare che siano specificati più elementi e il cmdlet deve visualizzare un avviso all'utente se non vengono forniti più elementi.

Usare la convenzione Pascal per i nomi dei parametri

Usare la convenzione Pascal per i nomi dei parametri. In altre parole, convertire in maiuscolo la prima lettera di ogni parola nel nome del parametro, inclusa la prima lettera del nome. Ad esempio, il nome del parametro ErrorAction usa le maiuscole corrette. I nomi dei parametri seguenti usano maiuscole e minuscole non corrette:

  • errorAction
  • erroraction

Parametri che accettano un elenco di opzioni

Esistono due modi per creare un parametro il cui valore può essere selezionato da un set di opzioni.

  • Definire un tipo di enumerazione (o usare un tipo di enumerazione esistente) che specifica i valori validi. Usare quindi il tipo di enumerazione per creare un parametro di quel tipo.

  • Aggiungere l'attributo ValidateSet alla dichiarazione del parametro. Per altre informazioni su questo attributo, vedere ValidateSet Attribute Declaration.

Usare tipi standard per i parametri

Per garantire la coerenza con altri cmdlet, usare i tipi standard per i parametri laddove possibile. Per altre informazioni sui tipi da usare per parametri diversi, vedere Nomi e tipi di parametri dei cmdlet standard. In questo argomento vengono forniti collegamenti a diversi argomenti che descrivono i nomi e i .NET Framework per i gruppi di parametri standard, ad esempio i "parametri dell'attività".

Usare i Strongly-Typed .NET Framework seguenti

I parametri devono essere definiti come tipi .NET Framework per fornire una migliore convalida dei parametri. Ad esempio, i parametri limitati a un valore da un set di valori devono essere definiti come tipo di enumerazione. Per supportare un Uniform Resource Identifier (URI), definire il parametro come tipo System.Uri. Evitare i parametri di stringa di base per tutte le proprietà di testo in formato libero, ad esempio .

Usare tipi di parametro coerenti

Quando lo stesso parametro viene usato da più cmdlet, usare sempre lo stesso tipo di parametro. Ad esempio, se il parametro è un tipo System.Int16 per un cmdlet, non impostare il parametro per un altro Process cmdlet come tipo Process System.Uint16.

Parametri che accettano True e False

Se il parametro accetta solo true e , definire il parametro come tipo false System.Management.Automation.SwitchParameter. Un parametro switch viene considerato true come quando viene specificato in un comando. Se il parametro non è incluso in un comando, Windows PowerShell considera il valore del parametro come false . Non definire parametri booleani.

Se il parametro deve distinguere tra 3 valori: $true, $false e "non specificato", definire un parametro di tipo <bool> Nullable. La necessità di un terzo valore "non specificato" si verifica in genere quando il cmdlet può modificare una proprietà booleana di un oggetto. In questo caso "non specificato" significa non modificare il valore corrente della proprietà.

Supporto di matrici per i parametri

Spesso gli utenti devono eseguire la stessa operazione su più argomenti. Per questi utenti, un cmdlet deve accettare una matrice come input di parametro in modo che un utente possa passare gli argomenti nel parametro come Windows PowerShell variabile. Ad esempio, il cmdlet Get-Process usa una matrice per le stringhe che identificano i nomi dei processi da recuperare.

Supporto del parametro PassThru

Per impostazione predefinita, molti cmdlet che modificano il sistema, ad esempio il cmdlet Stop-Process, fungono da "sink" per gli oggetti e non restituiscono un risultato. Questi cmdlet devono implementare PassThru il parametro per forzare il cmdlet a restituire un oggetto. Quando il parametro viene specificato, il cmdlet restituisce un oggetto usando una chiamata al PassThru metodo System.Management.Automation.Cmdlet.WriteObject. Ad esempio, il comando seguente arresta il processo Calc e passa il processo risultante alla pipeline.

Stop-Process calc -passthru

Nella maggior parte dei casi, i cmdlet Add, Set e New devono supportare un PassThru parametro .

Set di parametri di supporto

Un cmdlet è progettato per eseguire un singolo scopo. Tuttavia, spesso esiste più di un modo per descrivere l'operazione o la destinazione dell'operazione. Ad esempio, un processo può essere identificato dal nome, dal relativo identificatore o da un oggetto processo. Il cmdlet deve supportare tutte le rappresentazioni ragionevoli delle destinazioni. In genere, il cmdlet soddisfa questo requisito specificando set di parametri (definiti set di parametri) che operano insieme. Un singolo parametro può appartenere a un numero qualsiasi di set di parametri. Per altre informazioni sui set di parametri, vedere Set di parametri dei cmdlet.

Quando si specificano set di parametri, impostare un solo parametro nel set su ValueFromPipeline. Per altre informazioni su come dichiarare l'attributo Parameter, vedere Dichiarazione ParameterAttribute.

Quando si usa un set di parametri, il set di parametri predefinito viene definito dall'attributo Cmdlet . Il set di parametri predefinito deve includere i parametri che probabilmente verranno usati in una sessione Windows PowerShell interattiva. Per altre informazioni su come dichiarare l'attributo Cmdlet, vedere Dichiarazione CmdletAttribute.

Inviare commenti e suggerimenti all'utente (SD04)

Usare le linee guida in questa sezione per fornire commenti e suggerimenti all'utente. Questo feedback consente all'utente di essere a conoscenza di ciò che accade nel sistema e di prendere decisioni amministrative migliori.

Il Windows PowerShell runtime consente a un utente di specificare come gestire l'output di ogni chiamata al metodo Write impostando una variabile di preferenza. L'utente può impostare diverse variabili di preferenza, tra cui una variabile che determina se il sistema deve visualizzare informazioni e una variabile che determina se il sistema deve eseguire query sull'utente prima di eseguire altre azioni.

Supporto dei metodi WriteWarning, WriteVerbose e WriteDebug

Un cmdlet deve chiamare il metodo System.Management.Automation.Cmdlet.WriteWarning quando il cmdlet sta per eseguire un'operazione che potrebbe avere un risultato imprevisto. Ad esempio, un cmdlet deve chiamare questo metodo se il cmdlet sta per sovrascrivere un file di sola lettura.

Un cmdlet deve chiamare il metodo System.Management.Automation.Cmdlet.WriteVerbose quando l'utente richiede alcuni dettagli sulle operazioni del cmdlet. Ad esempio, un cmdlet deve chiamare queste informazioni se l'autore del cmdlet ritiene che ci siano scenari che potrebbero richiedere altre informazioni sulle operazioni del cmdlet.

Il cmdlet deve chiamare il metodo System.Management.Automation.Cmdlet.WriteDebug quando uno sviluppatore o un tecnico del supporto tecnico del prodotto deve comprendere cosa ha danneggiato l'operazione del cmdlet. Non è necessario che il cmdlet chiami il metodo System.Management.Automation.Cmdlet.WriteDebug nello stesso codice che chiama il metodo System.Management.Automation.Cmdlet.WriteVerbose perché il parametro presenta entrambi i set di Debug informazioni.

Supporto di WriteProgress per operazioni che durano molto tempo

Le operazioni dei cmdlet che durano molto tempo e che non possono essere eseguite in background devono supportare la creazione di report sullo stato di avanzamento tramite chiamate periodiche al metodo System.Management.Automation.Cmdlet.WriteProgress.

Usare le interfacce host

In alcuni casi, un cmdlet deve comunicare direttamente con l'utente anziché usando i vari metodi Write o Should supportati dalla classe System.Management.Automation.Cmdlet. In questo caso, il cmdlet deve derivare dalla classe System.Management.Automation.PSCmdlet e usare la proprietà System.Management.Automation.PSCmdlet.Host*. Questa proprietà supporta diversi livelli di tipo di comunicazione, inclusi i tipi PromptForChoice, Prompt e WriteLine/ReadLine. Al livello più specifico, offre anche modi per leggere e scrivere singole chiavi e per gestire i buffer.

A meno che un cmdlet non sia specificamente progettato per generare un'interfaccia utente grafica (GUI), non deve ignorare l'host usando la proprietà System.Management.Automation.PSCmdlet.Host*. Un esempio di cmdlet progettato per generare un'interfaccia utente grafica è il cmdlet Out-GridView.

Nota

I cmdlet non devono usare l'API System.Console.

Creare un file della Guida dei cmdlet (SD05)

Per ogni assembly di cmdlet, creare un Help.xml contenente informazioni sul cmdlet. Queste informazioni includono una descrizione del cmdlet, descrizioni dei parametri del cmdlet, esempi di utilizzo del cmdlet e altro ancora.

Linee guida per il codice

Le linee guida seguenti devono essere seguite quando si codificano i cmdlet per garantire un'esperienza utente coerente tra l'uso dei cmdlet e altri cmdlet. Quando si trova una guida al codice applicabile alla situazione, assicurarsi di esaminare le linee guida di progettazione per linee guida simili.

Parametri di codifica (SC01)

Definire un parametro dichiarando una proprietà pubblica della classe cmdlet decorata con l'attributo Parameter. I parametri non devono essere membri statici della classe .NET Framework per il cmdlet. Per altre informazioni su come dichiarare l'attributo Parameter, vedere Dichiarazione di attributi di parametro.

Supportare Windows PowerShell percorsi

Il Windows PowerShell è il meccanismo per normalizzare l'accesso agli spazi dei nomi. Quando si assegna un Windows PowerShell a un parametro nel cmdlet, l'utente può definire una "unità" personalizzata che funge da collegamento a un percorso specifico. Quando un utente designa un'unità di questo tipo, i dati archiviati, ad esempio i dati nel Registro di sistema, possono essere usati in modo coerente.

Se il cmdlet consente all'utente di specificare un file o un'origine dati, deve definire un parametro di tipo System.String. Se sono supportate più unità, il tipo deve essere una matrice. Il nome del parametro deve essere Path , con un alias di PSPath . Inoltre, il parametro Path deve supportare i caratteri jolly. Se il supporto per i caratteri jolly non è necessario, definire un LiteralPath parametro.

Se i dati letti o scritti dal cmdlet devono essere un file, il cmdlet deve accettare l'input di percorso Windows PowerShell e il cmdlet deve usare la proprietà System.Management.Automation.Sessionstate.Path per convertire i percorsi Windows PowerShell in percorsi che il file system riconosce. I meccanismi specifici includono i metodi seguenti:

Se i dati letti o scritti dal cmdlet sono solo un set di stringhe anziché un file, il cmdlet deve usare le informazioni sul contenuto del provider (membro) per leggere Content e scrivere. Queste informazioni vengono ottenute dalla proprietà System.Management.Automation.Provider.CmdletProvider.InvokeProvider. Questi meccanismi consentono ad altri archivi dati di partecipare alla lettura e alla scrittura dei dati.

Supporto dei caratteri jolly

Se possibile, un cmdlet deve supportare caratteri jolly. Il supporto per i caratteri jolly si verifica in molte posizioni in un cmdlet( in particolare quando un parametro accetta una stringa per identificare un oggetto da un set di oggetti). Ad esempio, il cmdlet di Stop-Proc esempio dell'esercitazione StopProc definisce un parametro per gestire Name le stringhe che rappresentano i nomi dei processi. Questo parametro supporta i caratteri jolly in modo che l'utente possa specificare facilmente i processi da arrestare.

Quando è disponibile il supporto per i caratteri jolly, un'operazione cmdlet produce in genere una matrice. In alcuni casi, non ha senso supportare una matrice perché l'utente potrebbe usare un solo elemento alla volta. Ad esempio, il cmdlet Set-Location non deve supportare una matrice perché l'utente sta impostando una sola posizione. In questo caso, il cmdlet supporta comunque i caratteri jolly, ma forza la risoluzione in un'unica posizione.

Per altre informazioni sui modelli di caratteri jolly, vedere Supporto dei caratteri jolly nei parametri dei cmdlet.

Definizione di oggetti

Questa sezione contiene linee guida per la definizione di oggetti per i cmdlet e per l'estensione di oggetti esistenti.

Definire membri standard

Definire membri standard per estendere un tipo di oggetto in un file Types.ps1xml personalizzato (usare il file Types.ps1xml Windows PowerShell come modello). I membri standard sono definiti da un nodo con il nome PSStandardMembers. Queste definizioni consentono ad altri cmdlet e Windows PowerShell runtime di usare l'oggetto in modo coerente.

Definire oggetti ObjectMember da usare come parametri

Se si progetta un oggetto per un cmdlet, assicurarsi che i relativi membri esercitino il mapping direttamente ai parametri dei cmdlet che lo useranno. Questo mapping consente all'oggetto di essere facilmente inviato alla pipeline e di essere passato da un cmdlet a un altro.

Gli oggetti .NET Framework preesistenti restituiti dai cmdlet spesso mancano alcuni membri importanti o pratici necessari per lo sviluppatore o l'utente dello script. Questi membri mancanti possono essere particolarmente importanti per la visualizzazione e la creazione dei nomi dei membri corretti in modo che l'oggetto possa essere passato correttamente alla pipeline. Creare un file Types.ps1xml personalizzato per documentare questi membri necessari. Quando si crea questo file, è consigliabile usare la convenzione di denominazione seguente:<Your_Product_Name>. Types.ps1xml.

Ad esempio, è possibile aggiungere una proprietà script al tipo Mode System.IO.FileInfo per visualizzare più chiaramente gli attributi di un file. È anche possibile aggiungere una proprietà alias al tipo System.Array per consentire l'uso coerente del nome della proprietà Count (anziché Length ).

Implementare l'interfaccia IComparable

Implementare un'interfaccia System.IComparable in tutti gli oggetti di output. In questo modo gli oggetti di output possono essere facilmente reindirizzati a vari cmdlet di ordinamento e analisi.

Aggiornare le informazioni di visualizzazione

Se la visualizzazione per un oggetto non fornisce i risultati previsti, creare un oggetto <YourProductName> personalizzato. File Format.ps1xml per l'oggetto.

Supporto dell'input pipeline ben definito (SC02)

Implementare per il centro di una pipeline

Implementare un cmdlet presupponendo che verrà chiamato dal centro di una pipeline, ovvero altri cmdlet produrranno l'input o ne consumeranno l'output. Ad esempio, si potrebbe presupporre che il cmdlet , poiché genera dati, venga usato solo come Get-Process primo cmdlet in una pipeline. Tuttavia, poiché questo cmdlet è progettato per la metà di una pipeline, questo cmdlet consente ai cmdlet o ai dati precedenti nella pipeline di specificare i processi da recuperare.

Supporto dell'input dalla pipeline

In ogni set di parametri per un cmdlet includere almeno un parametro che supporta l'input dalla pipeline. Il supporto per l'input della pipeline consente all'utente di recuperare dati o oggetti, di inviarli al set di parametri corretto e di passare i risultati direttamente a un cmdlet.

Un parametro accetta l'input dalla pipeline se l'attributo Parameter include la parola chiave , l'attributo della parola chiave ValueFromPipeline o ValueFromPipelineByPropertyName entrambe le parole chiave nella relativa dichiarazione. Se nessuno dei parametri in un set di parametri supporta le parole chiave o , il cmdlet non può essere inserito in modo significativo dopo un altro cmdlet perché ignorerà ValueFromPipeline ValueFromPipelineByPropertyName qualsiasi input della pipeline.

Supporto del metodo ProcessRecord

Per accettare tutti i record del cmdlet precedente nella pipeline, il cmdlet deve implementare il metodo System.Management.Automation.Cmdlet.ProcessRecord. Windows PowerShell questo metodo più volte, una volta per ogni record inviato al cmdlet.

Scrivere singoli record nella pipeline (SC03)

Quando un cmdlet restituisce oggetti, il cmdlet deve scrivere gli oggetti immediatamente quando vengono generati. Il cmdlet non deve contenerli per poterli bufferare in una matrice combinata. I cmdlet che ricevono gli oggetti come input potranno quindi elaborare, visualizzare o elaborare gli oggetti di output senza ritardo. Un cmdlet che genera oggetti di output uno alla volta deve chiamare il metodo System.Management.Automation.Cmdlet.WriteObject. Un cmdlet che genera oggetti di output in batch ,ad esempio perché un'API sottostante restituisce una matrice di oggetti di output, deve chiamare il metodo System.Management.Automation.Cmdlet.WriteObject con il secondo parametro impostato su true .

Creare cmdlet Case-Insensitive e Case-Preserving (SC04)

Per impostazione predefinita, Windows PowerShell non fa distinzione tra maiuscole e minuscole. Tuttavia, poiché si occupa di molti sistemi preesistenti, Windows PowerShell la distinzione tra maiuscole e minuscole per semplificare il funzionamento e la compatibilità. In altre parole, se un carattere viene fornito in lettere maiuscole, Windows PowerShell lo mantiene in lettere maiuscole. Per il funzionamento dei sistemi, un cmdlet deve seguire questa convenzione. Se possibile, deve funzionare senza distinzione tra maiuscole e minuscole. Deve tuttavia mantenere il caso originale per i cmdlet che si verificano in un secondo momento in un comando o nella pipeline.

Vedere anche

Linee guida sullo sviluppo necessarie

Linee guida sullo sviluppo consigliate

Scrittura di un cmdlet di Windows PowerShell