Abonniert Ereignisse, die vom Windows PowerShell-Modul und dem Cmdlet "New-Event" generiert werden.
Syntax
Register-EngineEvent [-SourceIdentifier] <string> [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]
Beschreibung
Mit dem Cmdlet "Register-EngineEvent" werden Ereignisse abonniert, die vom Windows PowerShell-Modul und dem Cmdlet "New-Event" generiert werden. Geben Sie das Ereignis mit dem SourceIdentifier-Parameter an.
Sie können dieses Cmdlet verwenden, um das Modulereignis "Exiting" und vom Cmdlet "New-Event" generierte Ereignisse zu abonnieren. Diese Ereignisse werden automatisch der Ereigniswarteschlange in der Sitzung hinzugefügt, ohne dass sie abonniert werden. Durch das Abonnieren von Ereignissen können Sie jedoch die Ereignisse weiterleiten, eine Aktion angeben, mit der auf die Ereignisse reagiert wird, und das Abonnement abbrechen.
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.
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-EngineEvent 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 |
keine |
|
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 |
False |
|
Pipelineeingaben akzeptieren? |
false |
|
Platzhalterzeichen akzeptieren? |
false |
-MessageData <psobject>
Gibt weitere dem Ereignis zugeordnete Daten an. Der Wert dieses Parameters wird in der MessageData-Eigenschaft des Ereignisobjekts angezeigt.
|
Erforderlich? |
false |
|
Position? |
named |
|
Standardwert |
keine |
|
Pipelineeingaben akzeptieren? |
false |
|
Platzhalterzeichen akzeptieren? |
false |
-SourceIdentifier <string>
Gibt die Quell-ID des Ereignisses an, das Sie abonnieren. Die Quell-ID muss in der aktuellen Sitzung eindeutig sein. Dieser Parameter ist erforderlich.
Der Wert dieses Parameters ist im Wert der SourceIdentifier-Eigenschaft des Abonnentenobjekts und aller diesem Abonnement zugeordneten Ereignisobjekte vorhanden.
|
Erforderlich? |
true |
|
Position? |
101 |
|
Standardwert |
|
|
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 |
<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 |
None Eingaben können nicht über die Pipeline an Register-EngineEvent übergeben werden. |
|
Ausgaben |
None oder System.Management.Automation.PSEventJob Wenn Sie den Action-Parameter verwenden, gibt Register-EngineEvent ein System.Management.Automation.PSEventJob-Objekt zurück. Andernfalls wird keine Ausgabe generiert. |
Hinweise
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>$s = new-pssession -computername Server01, Server02
C:\PS> invoke-command -session $s { Register-EngineEvent -sourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -forward }
Beschreibung
-----------
Mit diesem Befehl wird ein Windows PowerShell-Modulereignis auf zwei Remotecomputern registriert.
Im ersten Befehl wird auf jedem Remotecomputer eine PSSession erstellt.
Im zweiten Befehl wird der Befehl "Register-EngineEvent" in den Remotesitzungen mit dem Cmdlet "Invoke-Command" ausgeführt.
Der Befehl "Register-EngineEvent" identifiziert das Ereignis mithilfe des SourceIdentifier-Parameters. Die Ereignisse werden mit dem Forward-Parameter von der Remotesitzung an die lokale Sitzung weitergeleitet.
Beispiel 2
C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated -action { $processName | add-content processLog.txt }
C:\PS> get-event
C:\PS> $results = $j | receive-job
C:\PS> unregister-event PowerShell.ProcessCreated
Beschreibung
-----------
Dieser Befehl zeigt, wie das Ereignisauftragsobjekt, das von Register-EngineEvent zurückgegeben wird, wenn Sie den Action-Parameter verwenden, mit den Job-Cmdlets verwaltet wird.
Ein Ereignisauftrag wird wie jeder andere Windows PowerShell-Auftrag verwaltet. Weitere Informationen finden Sie unter "about_jobs". In diesem Beispiel werden die Ergebnisse des Auftrags mit dem Cmdlet "Receive-Job" abgerufen.
Um den Auftrag aus der Sitzung zu löschen, verwenden Sie Remove-Job. Verwenden Sie zum Abbrechen des Ereignisabonnements das Cmdlet "Unregister-Event". Verwenden Sie zum Löschen der Ereignisse in der Ereigniswarteschlange Remove-Event.
Siehe auch