Creazione di un cmdlet senza parametri

In questa sezione viene descritto come creare un cmdlet che recupera informazioni dal computer locale senza l'uso di parametri e quindi scrive le informazioni nella pipeline. Il cmdlet descritto di seguito è un cmdlet Get-Proc che recupera informazioni sui processi del computer locale e quindi visualizza tali informazioni nella riga di comando.

Nota

Tenere presente che durante la scrittura di cmdlet, gli assembly di riferimento di Windows PowerShell® vengono scaricati su disco (per impostazione predefinita in C:\Programmi\Assembly di riferimento\Microsoft\WindowsPowerShell\v1.0). Non sono installati nella Global Assembly Cache (GAC).

Denominazione del cmdlet

Un nome di cmdlet è costituito da un verbo che indica l'azione eseguita dal cmdlet e un sostantivo che indica gli elementi su cui agisce il cmdlet. Poiché questo esempio Get-Proc cmdlet recupera gli oggetti processo, usa il verbo "Get", definito dall'enumerazione System.Management.Automation.VerbsCommon e il sostantivo "Proc" per indicare che il cmdlet funziona sugli elementi del processo.

Quando si assegnano nomi ai cmdlet, non usare uno dei caratteri seguenti: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .

Scelta di un sostantivo

È consigliabile scegliere un sostantivo specifico. È consigliabile usare un sostantivo singolare preceduto da una versione abbreviata del nome del prodotto. Un nome di cmdlet di esempio di questo tipo è "Get-SQLServer".

Scelta di un verbo

È consigliabile usare un verbo del set di nomi dei verbi dei cmdlet approvati. Per altre informazioni sui verbi dei cmdlet approvati, vedere cmdlet Verb Names.

Definizione della classe cmdlet

Dopo aver scelto un nome di cmdlet, definire una classe .NET per implementare il cmdlet. Di seguito è riportata la definizione della classe per questo cmdlet di esempio Get-Proc:

[Cmdlet(VerbsCommon.Get, "Proc")]
  public class GetProcCommand : Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Si noti che, prima della definizione della classe, l'attributo System.Management.Automation.CmdletAttribute, con la sintassi [Cmdlet(verb, noun, ...)], viene usato per identificare questa classe come cmdlet. Questo è l'unico attributo obbligatorio per tutti i cmdlet e consente al runtime di Windows PowerShell di chiamarli correttamente. È possibile impostare le parole chiave degli attributi per dichiarare ulteriormente la classe, se necessario. Tenere presente che la dichiarazione di attributo per la classe GetProcCommand di esempio dichiara solo i nomi sostantivi e verbi per il cmdlet Get-Proc.

Nota

Per tutte le classi di attributi di Windows PowerShell, le parole chiave che è possibile impostare corrispondono alle proprietà della classe di attributi.

Quando si denomina la classe del cmdlet, è consigliabile riflettere il nome del cmdlet nel nome della classe. A tale scopo, usare il formato "VerbNounCommand" e sostituire "Verbo" e "Sostantivo" con il verbo e il sostantivo usati nel nome del cmdlet. Come illustrato nella definizione della classe precedente, il cmdlet di esempio Get-Proc definisce una classe denominata GetProcCommand, che deriva dalla classe base System.Management.Automation.Cmdlet.

Importante

Se si vuole definire un cmdlet che accede direttamente al runtime di Windows PowerShell, la classe .NET deve derivare dalla classe base System.Management.Automation.PSCmdlet. Per altre informazioni su questa classe, vedere Creazione di un cmdlet che definisce i set di parametri.

Nota

La classe per un cmdlet deve essere contrassegnata in modo esplicito come pubblica. Per impostazione predefinita, le classi non contrassegnate come pubbliche saranno interne e non verranno trovate dal runtime di Windows PowerShell.

Windows PowerShell usa il spazio dei nomi Microsoft.PowerShell.Commands per le relative classi di cmdlet. È consigliabile inserire le classi di cmdlet in uno spazio dei nomi Commands dello spazio dei nomi dell'API, ad esempio xxx.PS. Comandi.

Override di un metodo di elaborazione di input

La classe System.Management.Automation.Cmdlet fornisce tre metodi di elaborazione di input principali, almeno uno dei quali deve eseguire l'override del cmdlet. Per altre informazioni su come Windows PowerShell elabora i record, vedere Funzionamento di Windows PowerShell.

Per tutti i tipi di input, il runtime di Windows PowerShell chiama System.Management.Automation.Cmdlet.BeginProcessing per abilitare l'elaborazione. Se il cmdlet deve eseguire alcune operazioni di pre-elaborazione o installazione, è possibile eseguire questa operazione eseguendo l'override di questo metodo.

Nota

Windows PowerShell usa il termine "record" per descrivere il set di valori dei parametri forniti quando viene chiamato un cmdlet.

Se il cmdlet accetta l'input della pipeline, deve eseguire l'override del metodo System.Management.Automation.Cmdlet.ProcessRecord e facoltativamente il metodo System.Management.Automation.Cmdlet.EndProcessing. Ad esempio, un cmdlet potrebbe eseguire l'override di entrambi i metodi se raccoglie tutti gli input usando System.Management.Automation.Cmdlet.ProcessRecord e quindi opera sull'input nel suo complesso anziché su un elemento alla volta, come fa il cmdlet Sort-Object.

Se il cmdlet non accetta l'input della pipeline, deve eseguire l'override del metodo System.Management.Automation.Cmdlet.EndProcessing. Tenere presente che questo metodo viene spesso usato al posto di System.Management.Automation.Cmdlet.BeginProcessing quando il cmdlet non può operare su un elemento alla volta, come avviene per un cmdlet di ordinamento.

Poiché questo cmdlet di esempio Get-Proc deve ricevere l'input della pipeline, esegue l'override del metodo System.Management.Automation.Cmdlet.ProcessRecord e usa le implementazioni predefinite per System.Management.Automation.Cmdlet.BeginProcessing e System.Management.Automation.Cmdlet.EndProcessing. L'override System.Management.Automation.Cmdlet.ProcessRecord recupera i processi e li scrive nella riga di comando usando il metodo System.Management.Automation.Cmdlet.WriteObject.

protected override void ProcessRecord()
{
  // Get the current processes
  Process[] processes = Process.GetProcesses();

  // Write the processes to the pipeline making them available
  // to the next cmdlet. The second parameter of this call tells
  // PowerShell to enumerate the array, and send one process at a
  // time to the pipeline.
  WriteObject(processes, true);
}

Protected Overrides Sub ProcessRecord()

    '/ Get the current processes.
    Dim processes As Process()
    processes = Process.GetProcesses()

    '/ Write the processes to the pipeline making them available
    '/ to the next cmdlet. The second parameter of this call tells
    '/ PowerShell to enumerate the array, and send one process at a
    '/ time to the pipeline.
    WriteObject(processes, True)

End Sub 'ProcessRecord

Aspetti da ricordare sull'elaborazione dell'input

L'origine predefinita per l'input è un oggetto esplicito ,ad esempio una stringa, fornito dall'utente nella riga di comando. Per altre informazioni, vedere Creazione di un cmdlet per elaborare l'input della riga di comando.
Un metodo di elaborazione di input può anche ricevere input dall'oggetto di output di un cmdlet upstream nella pipeline. Per altre informazioni, vedere Creazione di un cmdlet per elaborare l'input della pipeline. Tenere presente che il cmdlet può ricevere input da una combinazione di origini della riga di comando e della pipeline.
Il cmdlet downstream potrebbe non restituire per molto tempo o non affatto. Per questo motivo, il metodo di elaborazione di input nel cmdlet non deve contenere blocchi durante le chiamate a System.Management.Automation.Cmdlet.WriteObject, in particolare i blocchi per cui l'ambito si estende oltre l'istanza del cmdlet.

Importante

I cmdlet non devono mai chiamare System.Console.Writeline* o il relativo equivalente.

Il cmdlet potrebbe avere variabili oggetto da pulire al termine dell'elaborazione, ad esempio se apre un handle di file nel metodo System.Management.Automation.Cmdlet.BeginProcess ing e mantiene aperto l'handle per l'uso da parte di System.Management.Automation.Cmdlet.ProcessRecord). È importante ricordare che il runtime di Windows PowerShell non chiama sempre il metodo System.Management.Automation.Cmdlet.EndProcessing, che deve eseguire la pulizia degli oggetti.

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

Codice di esempio

Per il codice di esempio C# completo, vedere Esempio getProcessSample01.

Definizione di tipi di oggetto e formattazione

Windows PowerShell passa informazioni tra i cmdlet usando oggetti .NET. Di conseguenza, un cmdlet potrebbe dover definire il proprio tipo oppure potrebbe essere necessario estendere un tipo esistente fornito da un altro cmdlet. Per altre informazioni sulla definizione di nuovi tipi o sull'estensione dei tipi esistenti, vedere Estensione dei tipi di oggetto e formattazione.

Compilazione del cmdlet

Dopo aver implementato un cmdlet, è necessario registrarlo con Windows PowerShell tramite uno snap-in di Windows PowerShell. Per altre informazioni sulla registrazione dei cmdlet, vedere Come registrare cmdlet, provider e applicazioni host.

Test del cmdlet

Quando il cmdlet è stato registrato con Windows PowerShell, è possibile testarlo eseguendolo nella riga di comando. Il codice per il cmdlet di esempio Get-Proc è ridotto, ma usa ancora il runtime di Windows PowerShell e un oggetto .NET esistente, che è sufficiente per renderlo utile. Verrà ora testato per comprendere meglio cosa Get-Proc può fare e come può essere usato il relativo output. Per altre informazioni sull'uso dei cmdlet dalla riga di comando, vedere l'Introduzione a Windows PowerShell.

Avviare Windows PowerShell e ottenere i processi correnti in esecuzione nel computer.

Get-Proc