Condividi tramite

Linee guida sullo sviluppo vivamente consigliate

Questa sezione descrive le linee guida da seguire quando si scrivono i cmdlet. Sono separati in linee guida per la progettazione di cmdlet e linee guida per la scrittura del codice del 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 scarsa quando usano i cmdlet.

Linee guida per la progettazione

Quando si progettano cmdlet, è consigliabile seguire le linee guida seguenti per garantire un'esperienza utente coerente tra l'uso dei cmdlet e altri cmdlet. Quando si trova una linea guida di progettazione applicabile alla situazione, assicurarsi di esaminare le linee guida del codice per linee guida simili.

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

I sostantivi usati nella denominazione dei cmdlet devono essere molto specifici in modo che l'utente possa individuare i cmdlet. Prefissi nomi generici come "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 la funzionalità evitando la duplicazione tra i nomi dei cmdlet.

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

Usare il caso Pascal per i nomi dei cmdlet (SD02)

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

Linee guida per la progettazione dei parametri (SD03)

Un cmdlet necessita di parametri che ricevono i dati su cui deve operare e parametri che indicano informazioni utilizzate per determinare le caratteristiche dell'operazione. Ad esempio, un cmdlet potrebbe avere un Name parametro che riceve dati dalla pipeline e il cmdlet potrebbe avere un Force parametro per indicare che il cmdlet può essere forzato a eseguire 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 parametri standard in modo che l'utente possa determinare rapidamente il significato di un parametro specifico. Se è necessario un nome più specifico, usare un nome di parametro standard e quindi specificare un nome più specifico come alias. Ad esempio, il Get-Service cmdlet ha un parametro con un nome generico (Name) e un alias più specifico (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.For more information about parameter names and their data types, see Cmdlet Parameter Name and Functionality Guidelines.

Usare nomi di parametri 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 in quei casi in cui il valore del parametro è sempre un valore a più elementi. In questi casi, il cmdlet deve verificare che vengano forniti più elementi e che il cmdlet visualizzi un avviso all'utente se non vengono forniti più elementi.

Usare il PascalCase per i nomi dei parametri

Usare la notazione Pascal per i nomi dei parametri. In altre parole, in maiuscolo la prima lettera di ogni parola nel nome del parametro, inclusa la prima lettera del nome. Ad esempio, il nome ErrorAction del parametro usa la maiuscola corretta. 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 tale tipo.

  • Aggiungere l'attributo ValidateSet alla dichiarazione di parametro. Per altre informazioni su questo attributo, vedere Dichiarazione di attributo ValidateSet.

Utilizzare 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 che devono essere usati per parametri diversi, vedere Standard Cmdlet Parameter Names and Types. In questo argomento vengono forniti collegamenti a diversi argomenti che descrivono i nomi e i tipi di framework .NET per i gruppi di parametri standard, ad esempio i "parametri attività".

Usare i tipi Strongly-Typed del .NET Framework

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

Usare tipi di parametri coerenti

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

Parametri che accettano True e False

Se il parametro accetta solo true e false, definire il parametro come tipo System.Management.Automation.SwitchParameter. Un [switch] parametro viene considerato come true 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 specificati", definire un parametro di tipo Nullable<bool>. La necessità di un valore "non specificato" di terze parti 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à.

Supportare 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 variabile di PowerShell Windows. 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 il PassThru parametro per forzare la restituzione di un oggetto da parte del cmdlet. Quando si specifica il PassThru parametro , il cmdlet restituisce un oggetto utilizzando una chiamata al metodo System.Management.Automation.Cmdlet.WriteObject . Ad esempio, il comando seguente arresta il calcolo (CalculatorApp.exe) e passa il processo risultante alla pipeline.

Stop-Process -Name CalculatorApp -PassThru

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

Set di parametri di supporto

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

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

Quando vengono usati i set di parametri, il set di parametri predefinito viene definito dall'attributo Cmdlet . Il set di parametri predefinito deve includere i parametri che è più probabile usare in una sessione interattiva di PowerShell Windows. 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 consapevoli di ciò che si sta verificando nel sistema e di prendere decisioni amministrative migliori.

Il runtime di PowerShell Windows consente a un utente di specificare come gestire l'output da 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 una query sull'utente prima di eseguire ulteriori azioni.

Supportare i 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 eseguite dal 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 Debug parametro presenta entrambi i set di informazioni.

Supporto di WriteProgress per le operazioni che richiedono molto tempo

Le operazioni sui cmdlet che richiedono 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. A livello più specifico, offre anche modi per leggere e scrivere singole chiavi e per gestire i buffer.

A meno che un cmdlet non sia progettato specificamente 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.

Annotazioni

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

Creare un file di guida dei cmdlet (SD05)

Per ogni assembly di cmdlet, creare un file Help.xml che contiene informazioni sul cmdlet. Queste informazioni includono una descrizione del cmdlet, le descrizioni dei parametri del cmdlet, esempi dell'uso del cmdlet e altro ancora.

Linee guida per il codice

Quando si codificano i cmdlet, è necessario seguire le linee guida seguenti per garantire un'esperienza utente coerente tra l'uso dei cmdlet e altri cmdlet. Quando si trova una linea guida del codice applicabile alla situazione, assicurarsi di esaminare le linee guida di progettazione per le 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 derivata per il cmdlet . Per ulteriori informazioni su come dichiarare l'attributo Parameter, vedere Dichiarazione attributo Parameter.

Supporto per i percorsi di Windows PowerShell

Il percorso di Windows PowerShell è il meccanismo per standardizzare l'accesso agli spazi dei nomi. Quando si assegna un percorso di Windows PowerShell a un parametro nel cmdlet, l'utente può definire un "collegamento" personalizzato che funge da scorciatoia a un percorso specifico. Quando un utente designa tale unità, 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 un array. Il nome del parametro deve essere Path, con un alias di PSPath. Inoltre, il Path parametro deve supportare caratteri jolly. Se non è necessario il supporto per i caratteri jolly, definire un parametro LiteralPath.

Se i dati che il cmdlet legge o scrive devono essere un file, il cmdlet deve accettare l'input del percorso di Windows PowerShell e deve utilizzare la proprietà System.Management.Automation.SessionState.Path per convertire i percorsi di Windows PowerShell in percorsi riconosciuti dal file system. 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 (Content membro) per leggere 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 i caratteri jolly. Il supporto per i caratteri speciali viene supportato in molteplici parti in un cmdlet, in particolare quando un parametro accetta una stringa per identificare un oggetto all'interno di un insieme di oggetti. Ad esempio, il cmdlet di esempio Stop-Procdell'esercitazione StopProc definisce un Name parametro per gestire stringhe che rappresentano i nomi dei processi. Questo parametro supporta i caratteri speciali, permettendo all'utente di 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 solo un singolo elemento alla volta. Ad esempio, il cmdlet Set-Location non deve supportare una matrice perché l'utente sta impostando solo una singola posizione. In questo caso, il cmdlet supporta ancora 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 degli oggetti esistenti.

Definire i membri standard

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

Definire ObjectMembers da usare come parametri

Se si progetta un oggetto per un cmdlet, assicurarsi che i membri dell'oggetto eseguano il mapping direttamente ai parametri dei cmdlet che lo utilizzeranno. Questo mapping consente di inviare facilmente l'oggetto alla pipeline e di passare da un cmdlet a un altro.

Gli oggetti .NET Framework preesistenti restituiti dai cmdlet mancano spesso alcuni membri importanti o pratici necessari per lo sviluppatore o l'utente di script. Questi membri mancanti possono essere particolarmente importanti per la visualizzazione e per 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 Mode proprietà script al tipo System.IO.FileInfo per visualizzare più chiaramente gli attributi di un file. È anche possibile aggiungere una Count proprietà alias al tipo System.Array per consentire l'uso coerente di tale nome di proprietà 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 inviati tramite pipe a vari cmdlet di ordinamento e analisi.

Aggiorna informazioni di visualizzazione

Se la visualizzazione di un oggetto non fornisce i risultati previsti, creare un file <YourProductName>.Format.ps1xml personalizzato per tale oggetto.

Supportare un input ben definito della pipeline (SC02)

Implementare per una fase intermedia di una pipeline

Implementare un cmdlet presupponendo che venga chiamato dal centro di una pipeline, ovvero altri cmdlet produrranno l'input o ne utilizzeranno l'output. Si supponga, ad esempio, che il Get-Process cmdlet , poiché genera dati, venga usato solo come primo cmdlet in una pipeline. Tuttavia, poiché questo cmdlet è progettato per il centro di una pipeline, questo cmdlet consente ai cmdlet o ai dati precedenti nella pipeline di specificare i processi da recuperare.

Supporto per l'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 input dalla pipeline se l'attributo Parameter include la ValueFromPipeline parola chiave, l'attributo ValueFromPipelineByPropertyName keyword o entrambe le parole chiave nella relativa dichiarazione. Se nessuno dei parametri in un set di parametri supporta le ValueFromPipeline parole chiave o ValueFromPipelineByPropertyName , il cmdlet non può essere inserito in modo significativo dopo un altro cmdlet perché ignorerà 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 chiama questo metodo più volte, una volta per ogni record inviato al cmdlet.

Scrivere record singoli nella pipeline (SC03)

Quando un cmdlet restituisce oggetti, il cmdlet deve scrivere gli oggetti immediatamente quando vengono generati. Il cmdlet non dovrebbe trattenerli per bufferizzarli in un array combinato. I cmdlet che ricevono gli oggetti come input potranno quindi elaborare e/o visualizzare gli oggetti di output senza ritardi. 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 stesso non fa distinzione tra maiuscole e minuscole. Tuttavia, poiché si occupa di molti sistemi preesistenti, Windows PowerShell mantiene la distinzione tra maiuscole e minuscole per facilitare l'operatività e la compatibilità. In altre parole, se viene fornito un carattere in lettere maiuscole, Windows PowerShell lo mantiene in lettere maiuscole. Per il corretto funzionamento dei sistemi, è necessario che un cmdlet segua questa convenzione. Se possibile, deve operare in modo case-insensitive. È tuttavia consigliabile mantenere il caso originale per i cmdlet che si verificano in un secondo momento in un comando o nella pipeline.

Vedere anche

Linee guida per lo sviluppo richieste

Linee guida per lo sviluppo di consulenza

Scrittura di un cmdlet di PowerShell Windows

  • Last updated on