Abonniert die Ereignisse, die von einem Microsoft .NET Framework-Objekt generiert werden. (Register-ObjectEvent)
NAMERegister-ObjectEventÜBERSICHTAbonniert die Ereignisse, die von einem Microsoft .NET Framework-Objekt generiert werden.SYNTAXRegister-ObjectEvent [-InputObject] <psobject> [-EventName] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]BESCHREIBUNGMit dem Cmdlet "Register-ObjectEvent" werden Ereignisse abonniert, die von .NET Framework-Objekten auf dem lokalen Computer oder einem Remotecomputer generiert werden. Wenn das abonnierte Ereignis ausgelöst wird, wird es der Ereigniswarteschlange in der Sitzung hinzugefügt. Verwenden Sie das Cmdlet "Get-Event", um Ereignisse in der Ereigniswarteschlange abzurufen. Sie können mit den Parametern von Register-ObjectEvent Eigenschaftenwerte für die Ereignisse angeben, mit denen Sie das Ereignis in der Warteschlange leichter identifizieren können. Sie können auch mit dem Action-Parameter Aktionen angeben, die ausgeführt werden sollen, wenn ein abonniertes Ereignis ausgelöst wird, und Sie können mit dem Forward-Parameter Remoteereignisse an die Ereigniswarteschlange in der lokalen Sitzung senden. 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 zum Behandeln der Ereignisse an. Beim Auslösen eines Ereignisses werden die Befehle in der Action 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-ObjectEvent ein Ereignisauftragsobjekt zurück, das diese Aktion darstellt. Sie können die Job-Cmdlets verwenden, um den Ereignisauftrag zu verwalten. Erforderlich? false Position? 102 Standardwert Keiner. Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -EventName <string> Gibt das Ereignis an, das Sie abonnieren. Geben Sie den Ereignisnamen ein. Dieser Parameter ist erforderlich. Der Wert dieses Parameters ist kein Name, den Sie für das Ereignisabonnement auswählen. Es ist der Name eines Ereignisses, das vom .NET Framework-Objekt verfügbar gemacht wird. Beispielsweise verfügt die ManagementEventWatcher-Klasse über Ereignisse mit dem Namen "EventArrived" und "Stopped". Um den Ereignisnamen eines Ereignisses zu suchen, verwenden Sie das Cmdlet "Get-Member". Erforderlich? true Position? 2 Standardwert Keiner Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -Forward [<SwitchParameter>] Sendet Ereignisse für dieses Abonnement an eine Remotesitzung. Verwenden Sie diesen Parameter, wenn Sie sich auf einem Remotecomputer oder in einer Remotesitzung für Ereignisse registrieren. Erforderlich? false Position? named Standardwert False Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -InputObject <psobject> Gibt das .NET Framework-Objekt an, das die Ereignisse generiert. Geben Sie eine Variable ein, die das Objekt enthält, oder geben Sie einen Befehl oder einen Ausdruck ein, mit dem das Objekt abgerufen wird. Dieser Parameter ist erforderlich. Erforderlich? true Position? 1 Standardwert Keiner 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 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 [<SwitchParameter>] 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 <CommonParameters> Dieses Cmdlet unterstützt folgende allgemeine Parameter: "Verbose", "Debug", "ErrorAction", "ErrorVariable", "WarningAction", "WarningVariable", "OutBuffer" und "OutVariable". Weitere Informationen erhalten Sie mit dem Befehl "get-help about_commonparameters".EINGABENKeiner Objekte können nicht über die Pipeline an Register-ObjectEvent übergeben werden.AUSGABENKeiner Dieses Cmdlet generiert keine Ausgabe.HINWEISEEreignisse, 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.Beispiele
BEISPIEL 1C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived" Beschreibung ----------- In diesem Beispiel werden Ereignisse abonniert, die beim Starten eines neuen Prozesses generiert werden. Der Befehl ruft EventArrived-Ereignisse mithilfe des ManagementEventWatcher-Objekts ab. Ein Abfrageobjekt gibt an, dass die Ereignisse Instanzerstellungsereignisse für die Win32_Process-Klasse sind.BEISPIEL 2C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query C:\PS> $action = { New-Event "PowerShell.ProcessCreated" -Sender $sender -EventArguments $SourceEventArgs.NewEvent.TargetInstance } C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived" -action $action Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- 2 422cfe5a-65e... Running True New-Event "PowerShe... Beschreibung ----------- In diesem Beispiel wird das Angeben einer Aktion als Antwort auf ein Ereignis veranschaulicht. Wenn Sie eine Aktion angeben, werden die ausgelösten Ereignisse keiner Ereigniswarteschlange hinzugefügt. Stattdessen reagiert die Aktion auf das Ereignis. In diesem Beispiel wird ein neues ProcessCreated-Ereignis ausgelöst, wenn ein Instanzerstellungsereignis ausgelöst wird, das angibt, dass ein neuer Prozess gestartet wurde. Die Aktion verwendet die automatische Variable "$Sender" und "$SourceEventArgs", die nur für Ereignisaktionen aufgefüllt werden. Mit dem Befehl "Register-ObjectEvent" wird ein Auftragsobjekt zurückgegeben, das die als Hintergrundauftrag ausgeführte Aktion darstellt. Sie können den Hintergrundauftrag mit den Job-Cmdlets, z. B. Get-Job und Receive-Job, verwalten. Weitere Informationen finden Sie unter "about_Jobs".BEISPIEL 3C:\PS>$s = new-pssession -computername Server01, Server02 C:\PS> invoke-command -session $s -filepath ProcessCreationEvent.ps1 C:\PS> invoke-command -session $s { get-event } # ProcessCreationEvent.ps1 function Enable-ProcessCreationEvent { $query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", ` (New-Object TimeSpan 0,0,1), ` "TargetInstance isa 'Win32_Process'" $processWatcher = New-Object System.Management.ManagementEventWatcher $query $identifier = "WMI.ProcessCreated" Register-ObjectEvent -input $processWatcher -eventName "EventArrived" ` -sourceIdentifier $identifier -messageData "Test" -forward } } EnableProcessCreationEvent Beschreibung ----------- In diesem Beispiel wird gezeigt, wie Objektereignisse auf Remotecomputern abonniert werden. Im ersten Befehl werden PSSessions auf zwei Remotecomputern erstellt und in der Variablen "$s" gespeichert. Im zweiten Befehl wird das Skript "ProcessCreationEvent.ps1" mithilfe des FilePath-Parameters des Cmdlet "Invoke-Command" in jeder PSSession in $s ausgeführt. Das Skript enthält den Befehl "Register-ObjectEvent", mit dem Instanzerstellungsereignisse für das Win32_Process-Objekt über das ManagementEventWatcher-Objekt und das zugehörige EventArrived-Ereignis abonniert werden.BEISPIEL 4C:\PS>$timer = New-Object Timers.Timer C:\PS> $timer.Interval = 500 C:\PS> $job = Register-ObjectEvent -inputObject $timer -eventName Elapsed -sourceIdentifier Timer.Random -Action {$random = Get-Random -Min 0 -Max 100} C:\PS> $job.gettype().fullname System.Management.Automation.PSEventJob C:\PS> $job | format-list -property * State : Running Module : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0 StatusMessage : HasMoreData : True Location : Command : $random = Get-Random -Min 0 -Max 100 JobStateInfo : Running Finished : System.Threading.ManualResetEvent InstanceId : 88944290-133d-4b44-8752-f901bd8012e2 Id : 1 Name : Timer.Random ChildJobs : {} ... C:\PS> $timer.Enabled = $true C:\PS> & $job.module {$random} 60 C:\PS> & $job.module {$random} 47 Beschreibung ----------- In diesem Beispiel wird veranschaulicht, wie das dynamische Modul im PSEventJob-Objekt verwendet wird, das beim Einschließen einer Aktion in eine Ereignisregistrierung erstellt wird. Der erste Befehl erstellt mit dem Cmdlet "New-Object" ein Zeitgeberobjekt. Mit dem zweiten Befehl wird das Intervall des Zeitgebers auf 500 (Millisekunden) festgelegt. Mit dem dritten Befehl wird das Cmdlet "Register-ObjectEvent" verwendet, um das Elapsed-Ereignis des Zeitgeberobjekts zu registrieren. Der Befehl schließt eine Aktion ein, die das Ereignis behandelt. Jedes Mal, wenn das Zeitgeberintervall abläuft, wird ein Ereignis ausgelöst und die Befehle in der Aktion ausgeführt. In diesem Fall generiert das Cmdlet "Get-Random" eine Zufallszahl zwischen 0 und 100 und speichert sie in der Variablen "$random". Wenn Sie in einem Register-ObjectEvent-Befehl einen Action-Parameter verwenden, gibt der Befehl ein PSEventJob-Objekt zurück, das die Aktion darstellt. Mit dem Befehl wird das Auftragsobjekt in der Variablen "$job" gespeichert. Das PSEventJob-Objekt, das vom Cmdlet "Register-ObjectEvent" zurückgegeben wird, ist auch in der Action-Eigenschaft des Ereignisabonnenten verfügbar. Weitere Informationen finden Sie unter "Get-EventSubscriber". Der vierte Befehl zeigt, dass die Variable "$job" ein PSEventJob-Objekt enthält. Mit dem fünften Befehl wird das Cmdlet "Format-List" verwendet, um alle Eigenschaften des PSEventJob-Objekts in einer Liste anzuzeigen. PSEventJob verfügt über eine Module-Eigenschaft, die ein dynamisches Skriptmodul enthält, das die Aktion implementiert. Mit dem sechsten Befehl wird der Zeitgeber aktiviert. In den verbleibenden Befehlen wird der Aufrufoperator (&) verwendet, um den Befehl im Modul aufzurufen und den Wert der Variablen "$random" anzuzeigen. Sie können den Aufrufoperator verwenden, um einen beliebigen Befehl im Modul aufzurufen, einschließlich nicht exportierter Befehle. In diesem Fall zeigen die Befehle die Zufallsnummer an, die bei Auftreten des Elapsed-Ereignisses generiert wird. Weitere Informationen zu Modulen finden Sie unter "about_Modules". VERWANDTE LINKS Online version: http://go.microsoft.com/fwlink/?LinkID=135244 (möglicherweise auf Englisch) Register-EngineEvent Register-WmiEvent Unregister-Event Get-Event New-Event Remove-Event Wait-Event C:\Windows>powershell get-help Register-EngineEvent -full
Microsoft Windows [Version 10.0.19045.3693]
Copyright (c) 2023 Microsoft Corporation.
ColorConsole [Version 3.7.1000] PowerShell 2.0-Export
