Linee guida sullo sviluppo necessarie
Quando si scrivono i cmdlet, è necessario seguire le linee guida seguenti. Sono suddivisi in linee guida per la progettazione di cmdlet e linee guida per la scrittura del codice dei cmdlet. Se non si seguono queste linee guida, i cmdlet potrebbero non riuscire e gli utenti potrebbero avere un'esperienza scadente quando usano i cmdlet.
Contenuto dell'argomento
Linee guida per la progettazione
Nomi dei cmdlet: caratteri che non possono essere usati (RD02)
Supporto del parametro Force per le sessioni interattive (RD05)
Linee guida per il codice
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.
Usa solo verbi approvati (RD01)
Il verbo specificato nell'attributo Cmdlet deve pro venire dal set riconosciuto di verbi forniti da Windows PowerShell. Non deve essere uno dei sinonimi non consentiti. Usare le stringhe costanti definite dalle enumerazioni seguenti per specificare i verbi dei cmdlet:
Per altre informazioni sui nomi dei verbi approvati, vedere Verbi di cmdlet.
Gli utenti necessitano di un set di nomi di cmdlet individuabili e previsti. Usare il verbo appropriato in modo che l'utente possa eseguire una rapida valutazione delle funzionalità di un cmdlet e individuare facilmente le funzionalità del sistema. Ad esempio, il comando della riga di comando seguente ottiene un elenco di tutti i comandi nel sistema i cui nomi iniziano con "start": get-command start-* . Usare i sostantivi nei cmdlet per differenziare i cmdlet da altri cmdlet. Il sostantivo indica la risorsa su cui verrà eseguita l'operazione. L'operazione stessa è rappresentata dal verbo.
Nomi dei cmdlet: caratteri che non possono essere usati (RD02)
Quando si denonono i cmdlet, non usare i caratteri speciali seguenti.
| Carattere | Nome |
|---|---|
| # | simbolo di cancelletto |
| , | virgola |
| () | parentesi |
| {} | apparecchio per i denti |
| [] | parentesi quadre |
| & | Commerciale |
| - | trattino Nota: il trattino può essere usato per separare il verbo dal sostantivo, ma non all'interno del sostantivo o all'interno del verbo. |
| / | barra |
| \ | barra rovesciata |
| $ | segno di dollaro |
| ^ | accento circonflesso |
| ; | punto e virgola |
| : | Colon |
| " | virgolette doppie |
| ' | virgoletta singola |
| <> | parentesi uncinate |
| | | barra verticale |
| ? | punto interrogativo |
| @ | simbolo di chiocciola |
| ` | back tick (accento grave) |
| * | asterisco |
| % | segno di percentuale |
| + | Segno |
| = | segno di uguale |
| ~ | Tilde |
Nomi di parametri che non possono essere usati (RD03)
Windows PowerShell fornisce un set comune di parametri per tutti i cmdlet e parametri aggiuntivi che vengono aggiunti in situazioni specifiche. Quando si progettano cmdlet personalizzati, non è possibile usare i nomi seguenti: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction e Verbose. Per altre informazioni su questi parametri, vedere Nomi di parametri comuni.
Richieste di conferma del supporto (RD04)
Per i cmdlet che eseguono un'operazione che modifica il sistema, devono chiamare il metodo System.Management.Automation.Cmdlet.ShouldProcess* per richiedere la conferma e, in casi speciali, chiamare il metodo System.Management.Automation.Cmdlet.ShouldContinue*. Il metodo System.Management.Automation.Cmdlet.ShouldContinue* deve essere chiamato solo dopo la chiamata del metodo System.Management.Automation.Cmdlet.ShouldProcess*.
Per eseguire queste chiamate, il cmdlet deve specificare che supporta le richieste di conferma impostando la SupportsShouldProcess parola chiave dell'attributo Cmdlet. Per altre informazioni sull'impostazione di questo attributo, vedere Dichiarazione di attributi dei cmdlet.
Nota
Se l'attributo Cmdlet della classe cmdlet indica che il cmdlet supporta le chiamate al metodo System.Management.Automation.Cmdlet.ShouldProcess* e il cmdlet non riesce a effettuare la chiamata al metodo System.Management.Automation.Cmdlet.ShouldProcess*, l'utente potrebbe modificare il sistema in modo imprevisto.
Usare il metodo System.Management.Automation.Cmdlet.ShouldProcess* per qualsiasi modifica del sistema. Una preferenza utente e il WhatIf parametro controllano il metodo System.Management.Automation.Cmdlet.ShouldProcess*. Al contrario, la chiamata System.Management.Automation.Cmdlet.ShouldContinue* esegue un controllo aggiuntivo per verificare la presenza di modifiche potenzialmente pericolose. Questo metodo non è controllato da preferenze dell'utente o dal WhatIf parametro . Se il cmdlet chiama il metodo System.Management.Automation.Cmdlet.ShouldContinue*, deve avere un parametro che ignora le chiamate a questi due metodi e che procede con Force l'operazione. Questo è importante perché consente di usare il cmdlet in host e script non interattivi.
Se i cmdlet supportano queste chiamate, l'utente può determinare se l'azione deve essere effettivamente eseguita. Ad esempio, il cmdlet Stop-Process chiama il metodo System.Management.Automation.Cmdlet.ShouldContinue* prima di arrestare un set di processi critici, inclusi i processi System, Winlogon e Spoolsv.
Per altre informazioni sul supporto di questi metodi, vedere Richiesta di conferma.
Supporto del parametro Force per le sessioni interattive (RD05)
Se il cmdlet viene usato in modo interattivo, specificare sempre un parametro Force per eseguire l'override delle azioni interattive, ad esempio richieste o lettura di righe di input. Questo è importante perché consente di usare il cmdlet in host e script non interattivi. I metodi seguenti possono essere implementati da un host interattivo.
System.Management.Automation.Host.PSHostUserInterface.Prompt*
System.Management.Automation.Host.Pshostuserinterface.PromptForChoice
System.Management.Automation.Host.Ihostuisupportsmultiplechoiceselection.PromptForChoice
System.Management.Automation.Host.Pshostuserinterface.PromptForCredential*
System.Management.Automation.Host.Pshostuserinterface.ReadLine*
System.Management.Automation.Host.Pshostuserinterface.ReadLineAsSecureString*
Oggetti di output del documento (RD06)
Windows PowerShell usa gli oggetti scritti nella pipeline. Per consentire agli utenti di sfruttare gli oggetti restituiti da ogni cmdlet, è necessario documentare gli oggetti restituiti ed è necessario documentare i membri di tali oggetti restituiti.
Linee guida per il codice
Quando si scrive il codice del cmdlet, è necessario seguire le linee guida seguenti. Quando si trova una guida al codice applicabile alla situazione, assicurarsi di esaminare le linee guida di progettazione per linee guida simili.
Derivare dalle classi Cmdlet o PSCmdlet (RC01)
Un cmdlet deve derivare dalla classe di base System.Management.Automation.Cmdlet o System.Management.Automation.PSCmdlet. I cmdlet che derivano dalla classe System.Management.Automation.Cmdlet non dipendono dalla Windows PowerShell runtime. Possono essere chiamati direttamente da qualsiasi lingua .NET Framework Microsoft. I cmdlet che derivano dalla classe System.Management.Automation.PSCmdlet dipendono dalla Windows PowerShell runtime. Di conseguenza, vengono eseguite all'interno di uno spazio di esecuzione.
Tutte le classi di cmdlet implementate devono essere classi pubbliche. Per altre informazioni su queste classi di cmdlet, vedere Panoramica dei cmdlet.
Specificare l'attributo cmdlet (RC02)
Perché un cmdlet sia riconosciuto da Windows PowerShell, la relativa .NET Framework deve essere decorata con l'attributo Cmdlet. Questo attributo specifica le funzionalità seguenti del cmdlet .
Coppia verbo-sostantivo che identifica il cmdlet.
Set di parametri predefinito utilizzato quando vengono specificati più set di parametri. Il set di parametri predefinito viene usato quando Windows PowerShell dispone di informazioni sufficienti per determinare quale set di parametri usare.
Indica se il cmdlet supporta le chiamate al metodo System.Management.Automation.Cmdlet.ShouldProcess*. Questo metodo visualizza un messaggio di conferma all'utente prima che il cmdlet a apporta una modifica al sistema. Per altre informazioni sul modo in cui vengono effettuate le richieste di conferma, vedere Richiesta di conferma.
Indicare il livello di impatto (o gravità) dell'azione associata al messaggio di conferma. Nella maggior parte dei casi, deve essere usato il valore predefinito Medio. Per altre informazioni sul modo in cui il livello di impatto influisce sulle richieste di conferma visualizzate all'utente, vedere Richiesta di conferma.
Per altre informazioni su come dichiarare l'attributo cmdlet, vedere Dichiarazione CmdletAttribute.
Eseguire l'override di un metodo di elaborazione dell'input (RC03)
Perché il cmdlet partecipi all'ambiente Windows PowerShell, deve eseguire l'override di almeno uno dei metodi di elaborazione di input seguenti.
System.Management.Automation.Cmdlet.BeginProcessing Questo metodo viene chiamato una volta e viene usato per fornire funzionalità di pre-elaborazione.
System.Management.Automation.Cmdlet.ProcessRecord Questo metodo viene chiamato più volte e viene usato per fornire funzionalità record per record.
System.Management.Automation.Cmdlet.EndProcessing Questo metodo viene chiamato una volta e viene usato per fornire funzionalità di post-elaborazione.
Specificare l'attributo OutputType (RC04)
L'attributo OutputType (introdotto in Windows PowerShell 2.0) specifica il .NET Framework che il cmdlet restituisce alla pipeline. Specificando il tipo di output dei cmdlet, gli oggetti restituiti dal cmdlet sono più individuabili da altri cmdlet. Per altre informazioni sulla decorazione della classe cmdlet con questo attributo, vedere Dichiarazione dell'attributo OutputType.
Non mantenere handle per gli oggetti di output (RC05)
Il cmdlet non deve mantenere alcun handle per gli oggetti passati al metodo System.Management.Automation.Cmdlet.WriteObject*. Questi oggetti vengono passati al cmdlet successivo nella pipeline o vengono usati da uno script. Se si mantengono gli handle per gli oggetti, due entità saranno proprietarie di ogni oggetto, causando errori.
Gestire gli errori in modo affidabile (RC06)
Un ambiente di amministrazione rileva e apporta modifiche importanti al sistema che si sta amministrando. Pertanto, è essenziale che i cmdlet gestino correttamente gli errori. Per altre informazioni sui record degli errori, vedere Windows PowerShell Segnalazione errori.
Quando un errore impedisce a un cmdlet di continuare a elaborare altri record, si tratta di un errore di terminazione. Il cmdlet deve chiamare il metodo System.Management.Automation.Cmdlet.ThrowTerminatingError* che fa riferimento a un oggetto System.Management.Automation.ErrorRecord. Se il cmdlet non rileva un'eccezione, il runtime Windows PowerShell genera un errore di terminazione che contiene meno informazioni.
Per un errore non di terminazione che non arresta l'operazione sul record successivo proveniente dalla pipeline (ad esempio, un record prodotto da un processo diverso), il cmdlet deve chiamare il metodo System.Management.Automation.Cmdlet.WriteError* che fa riferimento a un oggetto System.Management.Automation.ErrorRecord. Un esempio di errore non di terminazione è l'errore che si verifica se un determinato processo non viene interrotta. La chiamata al metodo System.Management.Automation.Cmdlet.WriteError* consente all'utente di eseguire in modo coerente le azioni richieste e di mantenere le informazioni per determinate azioni che hanno esito negativo. Il cmdlet deve gestire ogni record nel modo più indipendente possibile.
L'oggetto System.Management.Automation.ErrorRecord a cui fanno riferimento i metodi System.Management.Automation.Cmdlet.ThrowTerminatingError* e System.Management.Automation.Cmdlet.WriteError* richiede un'eccezione alla base. Seguire le .NET Framework di progettazione quando si determina l'eccezione da usare. Se l'errore è semanticamente uguale a un'eccezione esistente, usare tale eccezione o derivare da tale eccezione. In caso contrario, derivare una nuova gerarchia di eccezioni direttamente dal tipo System.Exception.
Un oggetto System.Management.Automation.ErrorRecord richiede anche una categoria di errori che raggruppa gli errori per l'utente. L'utente può visualizzare gli errori in base alla categoria impostando il valore della variabile $ErrorView della shell su CategoryView. Le categorie possibili sono definite dall'enumerazione System.Management.Automation.ErrorCategory.
Se un cmdlet crea un nuovo thread e se il codice in esecuzione in tale thread genera un'eccezione non gestita, Windows PowerShell non intercetterà l'errore e terminerà il processo.
Se nel distruttore di un oggetto è presente codice che causa un'eccezione non gestita, Windows PowerShell l'errore non verrà rilevato e il processo verrà terminato. Ciò si verifica anche se un oggetto chiama metodi Dispose che causano un'eccezione non gestita.
Usare un Windows PowerShell per distribuire i cmdlet (RC07)
Creare un Windows PowerShell per creare un pacchetto e distribuire i cmdlet. Il supporto per i moduli è stato introdotto in Windows PowerShell 2.0. È possibile usare gli assembly che contengono le classi di cmdlet direttamente come file di modulo binario (questo è molto utile quando si testano i cmdlet) oppure è possibile creare un manifesto del modulo che fa riferimento agli assembly dei cmdlet. È anche possibile aggiungere assembly snap-in esistenti quando si usano moduli. Per altre informazioni sui moduli, vedere Writing a Windows PowerShell Module.
Vedere anche
Linee guida sullo sviluppo vivamente consigliate
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per