Register-WmiEvent

Artikel
10/30/2009

Abonniert ein WMI-Ereignis (Windows Management Instrumentation, Windows-Verwaltungsinstrumentation).

Syntax

Register-WmiEvent [-Class] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Register-WmiEvent [-Query] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Beschreibung

Das Cmdlet "Register-WmiEvent" abonniert WMI-Ereignisse auf dem lokalen Computer oder einem Remotecomputer.

Wenn das abonnierte WMI-Ereignis ausgelöst wird, wird es der Ereigniswarteschlange in der lokalen Sitzung hinzugefügt, auch wenn das Ereignis auf einem Remotecomputer eintritt. Verwenden Sie das Cmdlet "Get-Event", um Ereignisse in der Ereigniswarteschlange abzurufen.

Sie können mit den Parametern von Register-WmiEvent Ereignisse auf Remotecomputern abonnieren und Eigenschaftenwerte für die Ereignisse angeben, mit denen Sie das Ereignis in der Warteschlange leichter identifizieren können. Außerdem können Sie mit dem Action-Parameter Aktionen angeben, die beim Auslösen eines abonnierten Ereignisses ausgelöst werden.

Wenn Sie ein Ereignis abonnieren, wird der Sitzung ein Ereignisabonnent hinzugefügt. Verwenden Sie das Cmdlet "Get-EventSubscriber", um die Ereignisabonnenten in der Sitzung abzurufen. Wenn das Abonnement abgebrochen werden soll, verwenden Sie das Cmdlet "Unregister-Event". Hierdurch wird der Ereignisabonnent aus der Sitzung gelöscht.

Parameter

-Action <scriptblock>

Gibt Befehle an, die die Ereignisse behandeln. Beim Auslösen eines Ereignisses werden die Befehle im Action-Parameter ausgeführt, statt das Ereignis an die Ereigniswarteschlange zu senden. Schließen Sie die Befehle in geschweifte Klammern ({}) ein, um einen Skriptblock zu erstellen.

Der Wert des Action-Parameters kann die automatischen Variablen "$Event", "$EventSubscriber", "$Sender", "$SourceEventArgs" und "$SourceArgs" enthalten. Diese stellen Informationen zu dem Ereignis im Action-Skriptblock bereit. Weitere Informationen finden Sie unter "about_Automatic_Variables".

Wenn Sie eine Aktion angeben, gibt Register-WmiEvent ein Ereignisauftragsobjekt zurück, das diese Aktion darstellt. Sie können Cmdlets, die das Substantiv "Job" enthalten (die Job-Cmdlets) verwenden, um den Ereignisauftrag zu verwalten.

Erforderlich?	false
Position?	102
Standardwert	Das Ereignis wird der Ereigniswarteschlange hinzugefügt.
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Class <string>

Gibt das Ereignis an, das Sie abonnieren. Geben Sie die WMI-Klasse ein, die die Ereignisse generiert. Ein Class-Parameter oder ein Query-Parameter ist in jedem Befehl erforderlich.

Erforderlich?	true
Position?	1
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-ComputerName <string>

Gibt einen Remotecomputer an. Der Standardwert ist der lokale Computer. Geben Sie einen NetBIOS-Namen, eine IP-Adresse oder einen vollqualifizierten Domänennamen ein.

Erforderlich?	false
Position?	named
Standardwert	Lokaler Computer
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Credential <PSCredential>

Gibt ein Benutzerkonto an, das über die Berechtigung zum Ausführen dieser Aktion verfügt. Geben Sie einen Benutzernamen ein, z. B. "User01" oder "Domain01\User01". Oder geben Sie ein PSCredential-Objekt ein, z. B. ein vom Cmdlet "Get-Credential" zurückgegebenes Objekt. Wenn Sie einen Benutzernamen eingeben, werden Sie zur Eingabe eines Kennworts aufgefordert.

Erforderlich?	false
Position?	named
Standardwert	Die Anmeldeinformationen des aktuellen Benutzers
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Forward

Sendet Ereignisse für dieses Abonnement an die Sitzung auf dem lokalen Computer. Verwenden Sie diesen Parameter, wenn Sie sich auf einem Remotecomputer oder in einer Remotesitzung für Ereignisse registrieren.

Erforderlich?	false
Position?	named
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-MessageData <psobject>

Gibt alle weiteren Daten an, die diesem Ereignisabonnement zugeordnet werden sollen. Der Wert dieses Parameters wird in der MessageData-Eigenschaft aller diesem Abonnement zugeordneten Ereignisse angezeigt.

Erforderlich?	false
Position?	named
Standardwert	Keiner. Die MessageData-Eigenschaft ist NULL.
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Namespace <string>

Gibt den Namespace der WMI-Klasse an.

Erforderlich?	false
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Query <string>

Gibt eine Abfrage in WMI Query Language (WQL) an, die die WMI-Ereignisklasse identifiziert, z. B. "select * from __InstanceDeletionEvent".

Erforderlich?	true
Position?	1
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-SourceIdentifier <string>

Gibt einen Namen an, den Sie für das Abonnement auswählen. Der von Ihnen ausgewählte Name muss in der aktuellen Sitzung eindeutig sein. Der Standardwert ist die von Windows PowerShell zugewiesene GUID.

Der Wert dieses Parameters ist im Wert der SourceIdentifier-Eigenschaft des Abonnentenobjekts und aller diesem Abonnement zugeordneten Ereignisobjekte vorhanden.

Erforderlich?	false
Position?	101
Standardwert	GUID
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-SupportEvent

Blendet das Ereignisabonnement aus. Verwenden Sie diesen Parameter, wenn das aktuelle Abonnement Teil eines komplexeren Ereignisregistrierungsmechanismus ist und nicht unabhängig erfasst werden soll.

Um ein Abonnement anzuzeigen oder abzubrechen, das mit dem SupportEvent-Parameter erstellt wurde, verwenden Sie den Force-Parameter der Cmdlets "Get-EventSubscriber" und "Unregister-Event".

Erforderlich?	false
Position?	named
Standardwert	False
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Timeout <Int64>

Bestimmt, wie lange Windows PowerShell auf den Abschluss dieses Befehls wartet.

Der Standardwert 0 (null) bedeutet, dass es kein Timeout gibt und Windows PowerShell unbegrenzt wartet.

Erforderlich?	false
Position?	named
Standardwert	0
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

<CommonParameters>

Dieses Cmdlet unterstützt die folgenden allgemeinen Parameter: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer und -OutVariable. Weitere Informationen finden Sie unter about_Commonparameters.

Eingaben und Ausgaben

Der Eingabetyp ist der Typ der Objekte, die über die Pipeline an das Cmdlet übergeben werden können. Der Rückgabetyp ist der Typ der Objekte, die das Cmdlet zurückgibt.

Eingaben

Keiner

Objekte können nicht über die Pipeline an Register-WmiEvent übergeben werden.

Ausgaben

Keiner

Dieses Cmdlet generiert keine Ausgabe.

Hinweise

Wenn Sie dieses Cmdlet in Windows Vista und höheren Versionen von Windows verwenden möchten, starten Sie Windows PowerShell mit der Option "Als Administrator ausführen".

Ereignisse, Ereignisabonnements und die Ereigniswarteschlange sind nur in der aktuellen Sitzung vorhanden. Wenn Sie die aktuelle Sitzung schließen, wird die Ereigniswarteschlange verworfen, und das Ereignisabonnement wird abgebrochen.

Beispiel 1

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted"

Beschreibung
-----------
Dieser Befehl abonniert die von der Win32_ProcessStartTrace-Klasse generierten Ereignisse. Diese Klasse löst immer dann ein Ereignis aus, wenn ein Prozess gestartet wird.

Beispiel 2

C:\PS>register-wmiEvent -query "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'" -sourceIdentifier "WMIProcess" -messageData "Test 01" -timeout 500

Beschreibung
-----------
In diesem Befehl werden Win32_process-Instanzerstellungsereignisse mithilfe einer Abfrage abonniert.

Beispiel 3

C:\PS>$action = { get-history | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }

C:\PS> register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted" -action $action

Id    Name            State      HasMoreData   Location  Command
--    ----            -----      -----------   --------  -------
1     ProcessStarted  NotStarted False                   get-history | where {...

Beschreibung
-----------
In diesem Beispiel wird die Verwendung einer Aktion als Antwort auf ein Ereignis veranschaulicht. In diesem Fall werden beim Starten eines Prozesses alle Start-Process-Befehle in der aktuellen Sitzung in eine XML-Datei geschrieben. 

Wenn Sie den Action-Parameter verwenden, gibt Register-WmiEvent einen Hintergrundauftrag zurück, der die Ereignisaktion darstellt. Sie können die Job-Cmdlets verwenden, um den Ereignisauftrag zu verwalten, z. B. Get-Job und Receive-Job.

Weitere Informationen finden Sie unter "about_Jobs".

Beispiel 4

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "Start" -computername Server01 

C:\PS> get-event -sourceIdentifier "Start"

Beschreibung
-----------
In diesem Beispiel werden Ereignisse auf dem Remotecomputer "Server01" registriert. 

WMI gibt die Ereignisse an den lokalen Computer zurück und speichert sie in der Ereigniswarteschlange in der aktuellen Sitzung. Führen Sie den lokalen Befehl "Get-Event" aus, um die Ereignisse abzurufen.

Freigeben über