Erstellen eines Cmdlet ohne Parameter

Artikel
03/25/2025

In diesem Abschnitt wird beschrieben, wie Sie ein Cmdlet erstellen, das Informationen vom lokalen Computer ohne Die Verwendung von Parametern abruft, und schreibt dann die Informationen in die Pipeline. Das hier beschriebene Cmdlet ist ein Get-Proc-Cmdlet, das Informationen über die Prozesse des lokalen Computers abruft, und zeigt diese Informationen dann an der Befehlszeile an.

Hinweis

Beachten Sie, dass beim Schreiben von Cmdlets die Windows PowerShell-Referenzassemblys® auf den Datenträger heruntergeladen werden (standardmäßig unter "C:\Programme\Referenzassemblys\Microsoft\WindowsPowerShell\v1.0"). Sie werden nicht im globalen Assemblycache (Global Assembly Cache, GAC) installiert.

Benennen des Cmdlets

Ein Cmdlet-Name besteht aus einem Verb, das die Aktion angibt, die das Cmdlet ausführt, und ein Substantiv, das die Elemente angibt, auf die das Cmdlet wirkt. Da dieses Beispiel Get-Proc Cmdlet Prozessobjekte abruft, verwendet es das Verb "Get", das durch die System.Management.Automation.VerbsCommon Enumeration definiert ist, und das Substantiv "Proc", um anzugeben, dass das Cmdlet für Prozesselemente funktioniert.

Verwenden Sie beim Benennen von Cmdlets keines der folgenden Zeichen: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .

Auswählen eines Substantivs

Sie sollten ein spezifisches Substantiv auswählen. Es empfiehlt sich, ein Singular-Substantiv zu verwenden, dem eine gekürzte Version des Produktnamens vorangestellt ist. Ein Beispiel für einen Cmdlet-Namen dieses Typs ist "Get-SQLServer".

Auswählen eines Verbs

Sie sollten ein Verb aus der Gruppe genehmigter Cmdlet-Verbnamen verwenden. Weitere Informationen zu den genehmigten Cmdlet-Verben finden Sie unter Cmdlet Verb Names.

Definieren der Cmdlet-Klasse

Nachdem Sie einen Cmdlet-Namen ausgewählt haben, definieren Sie eine .NET-Klasse, um das Cmdlet zu implementieren. Dies ist die Klassendefinition für dieses BeispielGet-Proc-Cmdlet:

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

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

Beachten Sie, dass vor der Klassendefinition das System.Management.Automation.CmdletAttribute Attribut mit der Syntax [Cmdlet(verb, noun, ...)]verwendet wird, um diese Klasse als Cmdlet zu identifizieren. Dies ist das einzige erforderliche Attribut für alle Cmdlets, und es ermöglicht der Windows PowerShell-Runtime, sie richtig aufzurufen. Sie können Attributstichwörter festlegen, um die Klasse bei Bedarf weiter zu deklarieren. Beachten Sie, dass die Attributdeklaration für unsere GetProcCommand-Beispielklasse nur die Substantiv- und Verbnamen für das Cmdlet Get-Proc deklariert.

Hinweis

Bei allen Windows PowerShell-Attributklassen entsprechen die Schlüsselwörter, die Sie festlegen können, den Eigenschaften der Attributklasse.

Beim Benennen der Klasse des Cmdlets empfiehlt es sich, den Cmdletnamen im Klassennamen widerzuspiegeln. Verwenden Sie dazu das Formular "VerbNounCommand" und ersetzen Sie "Verb" und "Nomen" durch das Verb und das Substantiv, das im Cmdlet-Namen verwendet wird. Wie in der vorherigen Klassendefinition gezeigt, definiert das Cmdlet Get-Proc Beispiel eine Klasse namens "GetProcCommand", die von der System.Management.Automation.Cmdlet Basisklasse abgeleitet wird.

Wichtig

Wenn Sie ein Cmdlet definieren möchten, das direkt auf die Windows PowerShell-Laufzeit zugreift, sollte Ihre .NET-Klasse von der System.Management.Automation.PSCmdlet Basisklasse abgeleitet werden. Weitere Informationen zu dieser Klasse finden Sie unter Erstellen eines Cmdlets, das Parametersätze definiert.

Hinweis

Die Klasse für ein Cmdlet muss explizit als öffentlich gekennzeichnet werden. Klassen, die nicht als öffentlich gekennzeichnet sind, werden standardmäßig intern und von der Windows PowerShell-Runtime nicht gefunden.

Windows PowerShell verwendet den Microsoft.PowerShell.Commands Namespace für seine Cmdlet-Klassen. Es wird empfohlen, Ihre Cmdlet-Klassen in einem Commands-Namespace Ihres API-Namespaces zu platzieren, z. B. xxx.PS. Befehle.

Überschreiben einer Eingabeverarbeitungsmethode

Die System.Management.Automation.Cmdlet Klasse stellt drei Haupteingabeverarbeitungsmethoden bereit, von denen ihr Cmdlet außer Kraft setzen muss. Weitere Informationen dazu, wie Windows PowerShell Datensätze verarbeitet, finden Sie unter How Windows PowerShell Works.

Für alle Eingabetypen ruft die Windows PowerShell-Laufzeit System.Management.Automation.Cmdlet.BeginProcessing auf, um die Verarbeitung zu aktivieren. Wenn Ihr Cmdlet eine Vorverarbeitung oder Einrichtung durchführen muss, kann dies durch Überschreiben dieser Methode erfolgen.

Hinweis

Windows PowerShell verwendet den Begriff "Record", um den Satz von Parameterwerten zu beschreiben, die angegeben werden, wenn ein Cmdlet aufgerufen wird.

Wenn Ihr Cmdlet Pipelineeingaben akzeptiert, muss es die System.Management.Automation.Cmdlet.ProcessRecord-Methode und optional die System.Management.Automation.Cmdlet.EndProcessing-Methode überschreiben. Ein Cmdlet kann z. B. beide Methoden außer Kraft setzen, wenn alle Eingaben mithilfe von System.Management.Automation.Cmdlet.ProcessRecord gesammelt werden, und dann wird die Eingabe als Ganzes anstelle eines Elements gleichzeitig ausgeführt, wie das cmdlet Sort-Object.

Wenn Ihr Cmdlet keine Pipelineeingaben verwendet, sollte die System.Management.Automation.Cmdlet.EndProcessing-Methode außer Kraft setzen. Beachten Sie, dass diese Methode häufig anstelle von System.Management.Automation.Cmdlet.BeginProcessing verwendet wird, wenn das Cmdlet nicht gleichzeitig für ein Element verwendet werden kann, wie bei einem Sortier-Cmdlet.

Da dieses Beispiel-Get-Proc-Cmdlet Pipelineeingaben empfangen muss, überschreibt es die methode System.Management.Automation.Cmdlet.ProcessRecord und verwendet die Standardimplementierungen für System.Management.Automation.Cmdlet.BeginProcessing und System.Management.Automation.Cmdlet.EndProcessing. Die System.Management.Automation.Cmdlet.ProcessRecord Außerkraftsetzung ruft Prozesse ab und schreibt sie mithilfe der System.Management.Automation.Cmdlet.WriteObject-Methode in die Befehlszeile.

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

Wichtige Informationen zur Eingabeverarbeitung

Die Standardquelle für die Eingabe ist ein explizites Objekt (z. B. eine Zeichenfolge), das vom Benutzer in der Befehlszeile bereitgestellt wird. Weitere Informationen finden Sie unter Erstellen eines Cmdlets zum Verarbeiten der Befehlszeileneingabe.
Eine Eingabeverarbeitungsmethode kann auch Eingaben aus dem Ausgabeobjekt eines upstream-Cmdlets in der Pipeline empfangen. Weitere Informationen finden Sie unter Erstellen eines Cmdlets zum Verarbeiten von Pipelineeingaben. Beachten Sie, dass Ihr Cmdlet Eingaben aus einer Kombination aus Befehlszeilen- und Pipelinequellen empfangen kann.
Das nachgeschaltete Cmdlet gibt möglicherweise nicht lange oder gar nicht zurück. Aus diesem Grund sollte die Eingabeverarbeitungsmethode in Ihrem Cmdlet keine Sperren bei Aufrufen von System.Management.Automation.Cmdlet.WriteObjectenthalten, insbesondere Sperren, für die der Bereich über die Cmdlet-Instanz hinausgeht.

Wichtig

Cmdlets sollten niemals System.Console.Writeline* oder dessen Entsprechung aufrufen.

Das Cmdlet verfügt möglicherweise über Objektvariablen, um die Verarbeitung zu bereinigen (z. B. wenn es ein Dateihandle im System.Management.Automation.Cmdlet.BeginProcessing Methode öffnet und das Handle für die Verwendung durch System.Management.Automation.Cmdlet.ProcessRecord) geöffnet bleibt. Es ist wichtig zu beachten, dass die Windows PowerShell-Laufzeit nicht immer die System.Management.Automation.Cmdlet.EndProcessing-Methode aufruft, die die Objektbereinigung durchführen sollte.

Beispielsweise werden System.Management.Automation.Cmdlet.EndProcessing möglicherweise nicht aufgerufen, wenn das Cmdlet mitte des Weges abgebrochen wird oder ein Beendigungsfehler in einem Teil des Cmdlets auftritt. Daher sollte ein Cmdlet, das die Objektbereinigung erfordert, das vollständige System.IDisposable Muster implementieren, einschließlich des Finalizers, damit die Laufzeit sowohl System.Management.Automation.Cmdlet.EndProcessing als auch System.IDisposable.Dispose* am Ende der Verarbeitung aufrufen kann.

Codebeispiel

Den vollständigen C#-Beispielcode finden Sie unter GetProcessSample01 Sample.

Definieren von Objekttypen und Formatierungen

Windows PowerShell übergibt Informationen zwischen Cmdlets mithilfe von .NET-Objekten. Daher muss ein Cmdlet möglicherweise einen eigenen Typ definieren, oder das Cmdlet muss einen vorhandenen Typ erweitern, der von einem anderen Cmdlet bereitgestellt wird. Weitere Informationen zum Definieren neuer Typen oder zum Erweitern vorhandener Typen finden Sie unter Erweitern von Objekttypen und Formatierungen.

Erstellen des Cmdlets

Nach der Implementierung eines Cmdlets müssen Sie es über ein Windows PowerShell-Snap-In bei Windows PowerShell registrieren. Weitere Informationen zum Registrieren von Cmdlets finden Sie unter Registrieren von Cmdlets, Anbietern und Hostanwendungen.

Testen des Cmdlets

Wenn Ihr Cmdlet bei Windows PowerShell registriert wurde, können Sie es testen, indem Sie es in der Befehlszeile ausführen. Der Code für unser Beispiel-Get-Proc-Cmdlet ist klein, verwendet aber weiterhin die Windows PowerShell-Runtime und ein vorhandenes .NET-Objekt, das ausreicht, um es nützlich zu machen. Testen wir es, um besser zu verstehen, was Get-Proc tun und wie seine Ausgabe verwendet werden kann. Weitere Informationen zur Verwendung von Cmdlets über die Befehlszeile finden Sie in der Erste Schritte mit Windows PowerShell.

Starten Sie Windows PowerShell, und rufen Sie die aktuellen Prozesse ab, die auf dem Computer ausgeführt werden.

Get-Proc