Register-EngineEvent
Abonniert Ereignisse, die von der PowerShell-Engine 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 von der PowerShell-Engine 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 automatisch der Ereigniswarteschlange in Ihrer Sitzung hinzugefügt, ohne ein Abonnement zu erstellen. 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 der 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-Engine-Ereignisses 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 auf jedem Remotecomputer eine vom Benutzer verwaltete Sitzung (PSSession). 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 die Engine 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 ausgeführt Register-EngineEvent
wird, 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 zum Erstellen des Abonnements verwendet. 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
hat die Auftrags-ID 18 erstellt. Start-Job
hat die 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). Die Auftrags-ID 19 wird weiterhin ausgeführt, und es werden neue Ereignisse erstellt. 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 geschweifte Klammern ({}
) ein, um einen Skriptblock zu erstellen.
Der Wert des Action-Parameters kann die $Event
automatischen Variablen , $EventSubscriber
, $Sender
, $EventArgs
und $Args
enthalten, die Dem Action-Skriptblock Informationen über das Ereignis 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 maximal für das Ereignisabonnement 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 soll.
Um ein Abonnement anzuzeigen oder zu kündigen, das mit dem Parameter SupportEvent erstellt wurde, fügen Sie den Cmdlets oder Unregister-Event
den Cmdlets 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 Objekte an dieses Cmdlet übergeben.
Ausgaben
None
Standardmäßig gibt dieses Cmdlet keine Ausgabe zurück.
Wenn Sie den Action-Parameter verwenden, gibt dieses Cmdlet ein PSEventJob-Objekt zurück.
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 gilt als im Leerlauf, wenn sie keine Pipeline ausführt. Das OnIdle-Ereignis wird ausgelöst, wenn PowerShell 300 Millisekunden (ms) im Leerlauf war.
Hinweis
Wenn PSReadLine verwendet wird, wird das OnIdle-Ereignis ausgelöst, wenn ReadKey()
ein Zeitüberschreitung aufgetreten ist (keine Eingabe in 300 ms). Das Ereignis kann signalisiert werden, während sich der Benutzer gerade in 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 wurde das OnIdle-Verhalten so geändert, dass das Ereignis nur dann signalisiert wird, wenn ein ReadKey()
Timeout vorliegt und der aktuelle Bearbeitungspuffer leer ist.