Register-EngineEvent
Abonniert Ereignisse, die vom PowerShell-Modul und vom New-Event Cmdlet generiert werden.
Syntax
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Beschreibung
Das Register-EngineEvent Cmdlet abonniert Ereignisse, die vom PowerShell-Modul und dem New-Event Cmdlet generiert werden. Verwenden Sie den SourceIdentifier-Parameter, um das Ereignis anzugeben.
Sie können dieses Cmdlet verwenden, um die Vom New-Event Cmdlet generierten Ereignisse der OnIdle- oder Exiting-Engine zu abonnieren. Diese Ereignisse werden der Ereigniswarteschlange in Ihrer Sitzung ohne Abonnement automatisch hinzugefügt. Ein Abonnement ermöglicht es Ihnen jedoch, Ereignisse weiterzuleiten, eine Aktion für die Reaktion auf Ereignisse anzugeben und das Abonnement zu stornieren.
Wenn Sie ein Ereignis abonnieren, wird Ihrer Sitzung ein Ereignisabonnent hinzugefügt. Rufen Sie die Ereignisabonnenten in der Sitzung mithilfe des Cmdlets Get-EventSubscriber ab. Brechen Sie das Abonnement mit dem Cmdlet Unregister-Event ab, wodurch die Ereignisabonnenten aus der Sitzung gelöscht werden.
Wenn das abonnierte Ereignis ausgelöst wird, wird es der Ereigniswarteschlange der Sitzung hinzugefügt. Verwenden Sie das Get-Event Cmdlet, um Ereignisse in der Ereigniswarteschlange abzurufen.
Beispiele
Beispiel 1: Registrieren eines PowerShell-Modulereignisses auf Remotecomputern
In diesem Beispiel wird für ein PowerShell-Engine-Ereignis auf zwei Remotecomputern registriert.
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}New-PSSession erstellt eine benutzerseitig verwaltete Sitzung (PSSession) auf jedem der Remotecomputer. Das Invoke-Command Cmdlet führt den Register-EngineEvent Befehl in den Remotesitzungen aus.
Register-EngineEvent verwendet den SourceIdentifier-Parameter , um das Ereignis zu identifizieren. Der Forward-Parameter weist das Modul an, die Ereignisse von der Remotesitzung an die lokale Sitzung weiterzuleiten.
Beispiel 2: Ausführen einer angegebenen Aktion, wenn das Exiting-Ereignis auftritt
In diesem Beispiel wird gezeigt, wie sie ausgeführt werden Register-EngineEvent , um eine bestimmte Aktion auszuführen, wenn das PowerShell.Exiting-Ereignis auftritt.
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}Der Parameter SupportEvent wird hinzugefügt, um das Ereignisabonnement auszublenden. Wenn PowerShell beendet wird, wird in diesem Fall der Befehlsverlauf aus der beendenden Sitzung eine XML-Datei im Verzeichnis des $Home Benutzers exportiert.
Beispiel 3: Create und abonnieren eines benutzerdefinierten Ereignisses
In diesem Beispiel wird ein Abonnement für Ereignisse aus der Quelle MyEventSource erstellt. Dies ist eine beliebige Quelle, die wir verwenden werden, um den Fortschritt eines Auftrags zu überwachen. Register-EngineEvent wird verwendet, um das Abonnement zu erstellen. Der Skriptblock für den Action-Parameter protokolliert die Ereignisdaten in einer Textdatei.
Register-EngineEvent -SourceIdentifier MyEventSource -Action {
"Event: {0}" -f $event.messagedata | Out-File c:\temp\MyEvents.txt -Append
}
Start-Job -Name TestJob -ScriptBlock {
While ($True) {
Register-EngineEvent -SourceIdentifier MyEventSource -Forward
Start-Sleep -seconds 2
"Doing some work..."
New-Event -SourceIdentifier MyEventSource -Message ("{0} - Work done..." -f (Get-Date))
}
}
Start-Sleep -seconds 4
Get-EventSubscriber
Get-Job
SubscriptionId : 12
SourceObject :
EventName :
SourceIdentifier : MyEventSource
Action : System.Management.Automation.PSEventJob
HandlerDelegate :
SupportEvent : False
ForwardEvent : False
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Running True …
19 TestJob BackgroundJob Running True localhost …Register-EngineEvent Auftrags-ID 18 erstellt. Start-Job Auftrags-ID 19 erstellt. In Beispiel 4 entfernen wir das Ereignisabonnement und die Aufträge und überprüfen dann die Protokolldatei.
Beispiel 4: Aufheben der Registrierung von Ereignissen und sauber Aufträgen
Dies ist eine Fortsetzung von Beispiel 3. In diesem Beispiel warten wir 10 Sekunden, um mehrere Ereignisse auftreten zu lassen. Anschließend heben wir die Registrierung des Ereignisabonnements auf.
PS> Start-Sleep -seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Stopped False …
19 TestJob BackgroundJob Running True localhost …
PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM - Work done...
Event: 2/18/2020 2:36:21 PM - Work done...
Event: 2/18/2020 2:36:23 PM - Work done...
Event: 2/18/2020 2:36:25 PM - Work done...
Event: 2/18/2020 2:36:27 PM - Work done...
Event: 2/18/2020 2:36:29 PM - Work done...
Event: 2/18/2020 2:36:31 PM - Work done...Das Unregister-Event Cmdlet beendet den Auftrag, der dem Ereignisabonnement zugeordnet ist (Auftrags-ID 18). Auftrags-ID 19 wird weiterhin ausgeführt und erstellt neue Ereignisse. Wir verwenden die Job-Cmdlets , um den Auftrag zu beenden und die nicht benötigten Auftragsobjekte zu entfernen. Get-Content zeigt den Inhalt der Protokolldatei an.
Parameter
-Action
Gibt Befehle zur Behandlung der Ereignisse an. Beim Auslösen eines Ereignisses werden die Befehle in Action ausgeführt, statt das Ereignis an die Ereigniswarteschlange zu senden. Schließen Sie die Befehle in Klammern ({}) ein, um einen Skriptblock zu erstellen.
Der Wert des Aktionsparameters kann die $Eventautomatischen Variablen , $EventSubscriber, $Sender, $EventArgsund $Args enthalten, die Informationen zum Ereignis für den Aktionsskriptblock bereitstellen. Weitere Informationen finden Sie unter about_Automatic_Variables.
Wenn Sie eine Aktion angeben, Register-EngineEvent gibt ein Ereignisauftragsobjekt zurück, das diese Aktion darstellt. Sie können die Job-Cmdlets verwenden, um den Ereignisauftrag zu verwalten.
| Type: | ScriptBlock |
| Position: | 101 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Forward
Gibt an, dass das Cmdlet Ereignisse für dieses Abonnement an die Sitzung auf dem lokalen Computer sendet. Verwenden Sie diesen Parameter, wenn Sie sich auf einem Remotecomputer oder in einer Remotesitzung für Ereignisse registrieren.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaxTriggerCount
Gibt an, wie oft die Aktion für das Ereignisabonnement maximal ausgeführt wird.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MessageData
Gibt zusätzliche Daten an, die dem Ereignis zugeordnet sind. Der Wert dieses Parameters wird in der MessageData-Eigenschaft des Ereignisobjekts angezeigt.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SourceIdentifier
Gibt den Quellbezeichner des Ereignisses an, das Sie abonnieren. Der Quellbezeichner muss in der aktuellen Sitzung eindeutig sein. Dieser Parameter ist erforderlich.
Der Wert dieses Parameters wird im Wert der SourceIdentifier-Eigenschaft des Abonnentenobjekts und aller diesem Abonnement zugeordneten Ereignisobjekte angezeigt.
Der Wert ist spezifisch für die Quelle des Ereignisses. Dies kann ein beliebiger Wert sein, den Sie für die Verwendung mit dem New-Event Cmdlet erstellt haben. Die PowerShell-Engine unterstützt die PSEngineEvent-WertePowerShell.Exiting und PowerShell.OnIdle.
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SupportEvent
Gibt an, dass das Cmdlet das Ereignisabonnement ausblendet. Fügen Sie diesen Parameter hinzu, wenn das aktuelle Abonnement Teil eines komplexeren Ereignisregistrierungsmechanismus ist und nicht unabhängig ermittelt werden sollte.
Um ein Abonnement anzuzeigen oder zu kündigen, das mit dem Parameter SupportEvent erstellt wurde, fügen Sie den Cmdlets oder Unregister-Event den Get-EventSubscriber Parameter Force hinzu.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Eingaben
None
Sie können keine Eingabe an übergeben Register-EngineEvent.
Ausgaben
None or System.Management.Automation.PSEventJob
Wenn Sie den Action-Parameter verwenden, Register-EngineEvent wird ein System.Management.Automation.PSEventJob-Objekt zurückgegeben. 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.
Beim Abonnieren des Exiting-Ereignisses sind die Cmdlets, die vom Action-Parameter ausgeführt werden können, auf die Cmdlets in den Modulen Microsoft.PowerShell.Core und Microsoft.PowerShell.Utility beschränkt. Das Exiting-Ereignis wird nur ausgelöst, wenn die Sitzung unter der Kontrolle von PowerShell beendet wird. Das Ereignis wird nicht ausgelöst, wenn die Hostanwendung oder das Terminalfenster geschlossen wird.
Die Engine wird als Leerlauf betrachtet, wenn keine Pipeline ausgeführt wird. Das OnIdle-Ereignis wird ausgelöst, wenn sich PowerShell seit 300 Millisekunden (ms) im Leerlauf befindet.
Hinweis
Wenn PSReadLine verwendet wird, wird das OnIdle-Ereignis ausgelöst, wenn ReadKey() das Zeitüberschreitungsereignis (keine Eingabe in 300 ms) erfolgt. Das Ereignis kann signalisiert werden, während sich der Benutzer in der Mitte der Bearbeitung einer Befehlszeile befindet, z. B. liest der Benutzer Hilfe, um zu entscheiden, welcher Parameter verwendet werden soll. Ab PSReadLine 2.2.0-beta4 hat sich das OnIdle-Verhalten geändert, um das Ereignis nur dann zu signalisieren, wenn ein ReadKey() Timeout vorhanden ist und der aktuelle Bearbeitungspuffer leer ist.