Creazione di un cmdlet senza parametri

Articolo
09/27/2021

Questa sezione descrive come creare un cmdlet che recupera le 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 quando si scrivono i cmdlet, gli assembly di riferimento Windows PowerShell® vengono scaricati su disco (per impostazione predefinita in C:\Programmi\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0). Non vengono 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 da un sostantivo che indica gli elementi su cui agisce il cmdlet. Poiché questo cmdlet Get-Proc di esempio 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 i caratteri seguenti: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .

Scelta di un sostantivo

È consigliabile scegliere un sostantivo specifico. È meglio 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 dal set di nomi di verbi di cmdlet approvati. Per altre informazioni sui verbi dei cmdlet approvati, vedere Nomi dei verbi dei cmdlet.

Definizione della classe Cmdlet

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

[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 , viene usato per identificare questa classe [Cmdlet(verb, noun, ...)] come cmdlet. Questo è l'unico attributo obbligatorio per tutti i cmdlet e consente al runtime Windows PowerShell di chiamarli correttamente. È possibile impostare parole chiave di attributo per dichiarare ulteriormente la classe, se necessario. Tenere presente che la dichiarazione di attributo per la classe GetProcCommand di esempio dichiara solo i nomi di sostantivo e verbo per il cmdlet Get-Proc.

Nota

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

Quando si assegna un nome alla 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 di classe precedente, il cmdlet Get-Proc di esempio definisce una classe denominata GetProcCommand, che deriva dalla classe di base System.Management.Automation.Cmdlet.

Importante

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

Nota

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

Windows PowerShell usa lo 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.Commands.

Override di un metodo di elaborazione di input

La classe System.Management.Automation.Cmdlet fornisce tre metodi di elaborazione dell'input principali, almeno uno dei quali deve essere sottoposto a override dal cmdlet. Per altre informazioni su come Windows PowerShell i record, vedere How Windows PowerShell Works (Funzionamento di Windows PowerShell).

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

Nota

Windows PowerShell usa il termine "record" per descrivere il set di valori di parametro 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, del metodo System.Management.Automation.Cmdlet.EndProcessing. Ad esempio, un cmdlet potrebbe eseguire l'override di entrambi i metodi se raccoglie tutto l'input usando System.Management.Automation.Cmdlet.ProcessRecord e quindi opera sull'input nel suo complesso anziché su un elemento alla volta, come fa il Sort-Object cmdlet.

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 nel caso di un cmdlet di ordinamento.

Poiché questo cmdlet Get-Proc di esempio 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 dell'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 pipeline.
Il cmdlet downstream potrebbe non essere restituito per molto tempo o non restituire affatto. Per questo motivo, il metodo di elaborazione dell'input nel cmdlet non deve contenere blocchi durante le chiamate a System.Management.Automation.Cmdlet.WriteObject,in particolare i blocchi per i quali 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.BeginProcessing e mantiene aperto l'handle per l'uso da parte di System.Management.Automation.Cmdlet.ProcessRecord). È importante ricordare che il runtime 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 di terminazione in qualsiasi parte del cmdlet. Pertanto, un cmdlet che richiede la pulizia degli oggetti deve implementare il modello System.IDisposable completo, incluso il finalizzatore, in modo che il runtime possa chiamare sia System.Management.Automation.Cmdlet.EndProcessing che System.IDisposable.Dispose* al termine dell'elaborazione.

Codice di esempio

Per il codice di esempio C# completo, vedere l'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 o il cmdlet potrebbe dover estendere un tipo esistente fornito da un altro cmdlet. Per altre informazioni sulla definizione di nuovi tipi o sull'estensione di 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 Windows PowerShell di configurazione. Per altre informazioni sulla registrazione dei cmdlet, vedere How to Register Cmdlets, Providers, and Host Applications.

Test del cmdlet

Dopo aver registrato il cmdlet con Windows PowerShell, è possibile testarlo eseguendolo nella riga di comando. Il codice per il cmdlet Get-Proc di esempio è ridotto, ma usa comunque il runtime di Windows PowerShell e un oggetto .NET esistente, sufficiente per renderlo utile. Verrà ora testato per comprendere meglio le Get-Proc possibile eseguire e come può essere usato l'output. Per altre informazioni sull'uso dei cmdlet dalla riga di comando, vedere l'Attività iniziali con Windows PowerShell.

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

get-proc