Linee guida sullo sviluppo consigliate

Questa sezione descrive le linee guida da considerare per garantire buone esperienze di sviluppo e utente. A volte potrebbero essere applicabili e a volte potrebbero non essere applicabili.

Linee guida per la progettazione

Quando si progettano i cmdlet, è necessario considerare le linee guida seguenti. Quando si trova una linea guida di progettazione applicabile alla situazione, assicurarsi di esaminare le linee guida del codice per linee guida simili.

Supporto di un parametro InputObject (AD01)

Poiché Windows PowerShell funziona direttamente con gli oggetti di Microsoft .NET Framework, un oggetto .NET Framework è spesso disponibile che corrisponde esattamente al tipo che l'utente deve eseguire un'operazione specifica. InputObject è il nome standard di un parametro che accetta tale oggetto come input. Ad esempio, il cmdlet di esempio Stop-Procnell'esercitazione StopProc definisce un InputObject parametro di tipo Process che supporta l'input dalla pipeline. L'utente può ottenere un set di oggetti di processo, modificarli per selezionare gli oggetti esatti da arrestare e quindi passarli direttamente al Stop-Proc cmdlet.

Supportare il parametro Force (AD02)

In alcuni casi, un cmdlet deve proteggere l'utente dall'esecuzione di un'operazione richiesta. Tale cmdlet deve supportare un parametro Force per consentire all'utente di eseguire l'override di tale protezione se l'utente dispone delle autorizzazioni per eseguire l'operazione.

Ad esempio, il cmdlet Remove-Item non rimuove in genere un file di sola lettura. Tuttavia, questo cmdlet supporta un parametro Force in modo che un utente possa forzare la rimozione di un file di sola lettura. Se l'utente dispone già dell'autorizzazione per modificare l'attributo di sola lettura e l'utente rimuove il file, l'uso del parametro Force semplifica l'operazione. Tuttavia, se l'utente non dispone dell'autorizzazione per rimuovere il file, il parametro Force non ha alcun effetto.

Gestire le credenziali tramite Windows PowerShell (AD03)

Un cmdlet deve definire un Credential parametro per rappresentare le credenziali. Questo parametro deve essere di tipo System.Management.Automation.PSCredential e deve essere definito usando una dichiarazione di attributo Credential. Questo supporto richiede automaticamente all'utente il nome utente, la password o entrambi quando non viene fornita direttamente una credenziale completa. Per altre informazioni sull'attributo Credential, vedere Dichiarazione dell'attributo Credential.

Supporto dei parametri di codifica (AD04)

Se il cmdlet legge o scrive testo in o da una maschera binaria, ad esempio la scrittura o la lettura da un file in un file system, il cmdlet deve avere un parametro Encoding che specifica come il testo viene codificato nel formato binario.

I cmdlet di test devono restituire un valore booleano (AD05)

I cmdlet che eseguono test sulle risorse devono restituire un tipo System.Boolean alla pipeline in modo che possano essere usati nelle espressioni condizionali.

Linee guida per il codice

Quando si scrive codice cmdlet, è necessario considerare le linee guida seguenti. Quando trovi una linea guida che si applica alla tua situazione, assicurati di esaminare le linee guida di progettazione per linee guida simili.

Seguire le convenzioni di denominazione della classe cmdlet (AC01)

Seguendo le convenzioni di denominazione standard, è possibile rendere i cmdlet più individuabili e consentire all'utente di comprendere esattamente le operazioni eseguite dai cmdlet. Questa procedura è particolarmente importante per altri sviluppatori che usano Windows PowerShell perché i cmdlet sono tipi pubblici.

Definire un cmdlet nello spazio dei nomi corretto

In genere si definisce la classe per un cmdlet in uno spazio dei nomi .NET Framework che aggiunge .Commands allo spazio dei nomi che rappresenta il prodotto in cui viene eseguito il cmdlet. Ad esempio, i cmdlet inclusi in Windows PowerShell vengono definiti nello spazio dei Microsoft.PowerShell.Commands nomi .

Denominare la classe cmdlet in modo che corrisponda al nome del cmdlet

Quando si assegna un nome alla classe .NET Framework che implementa un cmdlet, denominare la classe <Verb><Noun>Command, dove sostituire i <Verb> segnaposto e <Noun> con il verbo e il sostantivo usati per il nome del cmdlet. Ad esempio, il cmdlet Get-Process viene implementato da una classe denominata GetProcessCommand.

Se nessun input della pipeline esegue l'override del metodo BeginProcessing (AC02)

Se il cmdlet non accetta input dalla pipeline, l'elaborazione deve essere implementata nel metodo System.Management.Automation.Cmdlet.BeginProcessing . L'uso di questo metodo consente a Windows PowerShell di mantenere l'ordinamento tra i cmdlet. Il primo cmdlet nella pipeline restituisce sempre i relativi oggetti prima che i cmdlet rimanenti nella pipeline ottengano la possibilità di avviare l'elaborazione.

Per gestire le richieste di arresto eseguire l'override del metodo StopProcessing (AC03)

Eseguire l'override del metodo System.Management.Automation.Cmdlet.StopProcessing in modo che il cmdlet possa gestire il segnale di arresto. Alcuni cmdlet richiedono molto tempo per completare l'operazione e consentono di passare molto tempo tra le chiamate al runtime di Windows PowerShell, ad esempio quando il cmdlet blocca il thread nelle chiamate RPC a esecuzione prolungata. Sono inclusi i cmdlet che effettuano chiamate al metodo System.Management.Automation.Cmdlet.WriteObject , al metodo System.Management.Automation.Cmdlet.WriteError e ad altri meccanismi di feedback che potrebbero richiedere molto tempo. Per questi casi, l'utente potrebbe dover inviare un segnale di arresto a questi cmdlet.

Implementare l'interfaccia IDisposable (AC04)

Se il cmdlet contiene oggetti che non vengono eliminati (scritti nella pipeline) dal metodo System.Management.Automation.Cmdlet.ProcessRecord , il cmdlet potrebbe richiedere un'ulteriore eliminazione di oggetti. Ad esempio, se il cmdlet apre un handle di file nel relativo metodo System.Management.Automation.Cmdlet.BeginProcessing e mantiene aperto l'handle per l'uso dal metodo System.Management.Automation.Cmdlet.ProcessRecord , questo handle deve essere chiuso alla fine dell'elaborazione.

Il runtime di Windows PowerShell non chiama sempre il metodo System.Management.Automation.Cmdlet.EndProcessing . Ad esempio, il metodo System.Management.Automation.Cmdlet.EndProcessing potrebbe non essere chiamato se il cmdlet viene annullato a metà dell'operazione o se si verifica un errore irreversibile in qualsiasi parte del cmdlet. Pertanto, la classe .NET Framework per un cmdlet che richiede la pulizia degli oggetti deve implementare il modello di interfaccia System.IDisposable completo, incluso il finalizzatore, in modo che il runtime di Windows PowerShell possa chiamare sia i metodi System.Management.Automation.Cmdlet.EndProcessing che System.IDisposable.Dispose* alla fine dell'elaborazione.

Usare tipi di parametri descrittivi per la serializzazione (AC05)

Per supportare l'esecuzione del cmdlet nei computer remoti, usare tipi che possono essere serializzati nel computer client e quindi riattivati nel computer server. I tipi seguenti sono descrittivi per la serializzazione.

Tipi primitivi:

• Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 e UInt64.
• Boolean, Guid, Byte[], TimeSpan, DateTime, Uri e Version.
• Char, String, XmlDocument.

Tipi riattivabili predefiniti:

• PSPrimitiveDictionary
• Parametro di interruttore
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Altri tipi:

• Stringa sicura
• Contenitori (elenchi e dizionari del tipo precedente)

Usare SecureString per i dati sensibili (AC06)

Quando si gestiscono dati sensibili, usare sempre il tipo di dati System.Security.SecureString . Ciò può includere l'input della pipeline per i parametri, nonché la restituzione di dati sensibili alla pipeline.

Anche se .NET consiglia di usare SecureString per il nuovo sviluppo, PowerShell continua a supportare la classe SecureString per la compatibilità con le versioni precedenti. L'uso di secureString è ancora più sicuro rispetto all'uso di una stringa di testo normale. PowerShell si basa ancora sul tipo SecureString per evitare di esporre accidentalmente il contenuto alla console o nei log. Usare SecureString con attenzione, perché può essere facilmente convertito in una stringa di testo normale. Per una discussione completa sull'uso di SecureString, vedere la documentazione della classe System.Security.SecureString.

Vedere anche

linee guida di sviluppo necessarie

linee guida per lo sviluppo fortemente incoraggiate

scrittura di un cmdlet di Windows PowerShell