Register-EngineEvent

Referenz

Modul:: Microsoft.PowerShell.Utility

Abonniert Ereignisse, die vom PowerShell-Modul und vom cmdlet New-Event generiert werden.

Syntax

Register-EngineEvent
        [-SourceIdentifier] <String>
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

Beschreibung

Das cmdlet Register-EngineEvent abonniert Ereignisse, die vom PowerShell-Modul und dem Cmdlet New-Event generiert werden. Verwenden Sie den SourceIdentifier Parameter, um das Ereignis anzugeben.

Mit diesem Cmdlet können Sie sich für die OnIdle or Verlassen von Motorereignisse und Ereignisse, die von der New-Event cmdlet. Diese Ereignisse werden automatisch zur Ereigniswarteschlange in Ihrer Sitzung hinzugefügt, ohne dass sie abonniert werden. Durch Abonnieren können Sie die Ereignisse jedoch weiterleiten, eine Aktion angeben, die auf die Ereignisse reagiert, und das Abonnement kündigen.

Wenn Sie ein Ereignis abonnieren, wird der Sitzung ein Ereignisabonnent hinzugefügt. Um die Ereignisteilnehmer in der Sitzung zu erhalten, verwenden Sie die Get-EventSubscriber cmdlet. Verwenden Sie zum Kündigen des Abonnements das Cmdlet Unregister-Event, das den Ereignisabonnent aus der Sitzung löscht.

Wenn das abonnierte Ereignis ausgelöst wird, wird es der Ereigniswarteschlange der Sitzung hinzugefügt. Verwenden Sie das Cmdlet Get-Event, um Ereignisse in der Ereigniswarteschlange abzurufen.

Beispiele

Beispiel 1: Registrieren eines PowerShell-Engine-Ereignisses auf Remotecomputern

Dieses Beispiel registriert sich für ein PowerShell-Engine-Ereignis auf zwei Remotecomputern.

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
  Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}

New-PSSession erstellt eine benutzerverwaltete Sitzung (PSSession) auf jedem der entfernten Computer.Die Invoke-Command Cmdlet führt das Register-EngineEvent Befehl in den Remote-Sitzungen. Register-EngineEvent verwendet den SourceIdentifier Parameter, um das Ereignis zu identifizieren. Die Weiterleiten wird die Engine angewiesen, die Ereignisse aus der entfernten Sitzung an die lokale Sitzung weiterzuleiten.

Beispiel 2: Eine bestimmte Aktion ausführen, wenn das Ereignis „Beenden“ eintritt

Dieses Beispiel zeigt, wie man Register-EngineEvent eine bestimmte Maßnahme zu ergreifen, wenn die PowerShell.Exiting Ereignis eintritt.

Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
    Get-History | Export-Clixml $HOME\history.clixml
}

Die SupportEvent wird hinzugefügt, um das Ereignisabonnement auszublenden. Wenn PowerShell beendet wird, wird der Befehlsverlauf aus der beendeten Sitzung in diesem Fall in einer XML-Datei im $HOME-Verzeichnis des Benutzers exportiert.

Beispiel 3: Erstellen und Abonnieren eines benutzerdefinierten Ereignisses

In diesem Beispiel wird ein Abonnement für Ereignisse aus der Quelle MyEventSourceerstellt. Dies ist eine beliebige Quelle, die wir verwenden werden, um den Fortschritt eines Auftrags zu überwachen. Register-EngineEvent wird zur Erstellung 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..."
        $newEventSplat = @{
            SourceIdentifier = 'MyEventSource'
            MessageData      = ("{0} -  Work done..." -f (Get-Date))
        }
        New-Event @newEventSplat
    }
}
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 erstellt Job Id 18. Start-Job erstellt Job Id 19. In Beispiel Nr. 4 entfernen wir das Ereignisabonnement und die Aufträge und prüfen dann die Protokolldatei.

Beispiel 4: Aufhebung der Registrierung von Ereignissen und Bereinigung von Aufträgen

Dies ist eine Fortsetzung von Beispiel 3. In diesem Beispiel warten wir 10 Sekunden, damit mehrere Ereignisse auftreten können. Dann 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...

Die Unregister-Event hält den mit dem Ereignisabonnement verbundenen Auftrag an (Auftragsnummer 18). Job Id 19 läuft noch und erzeugt neue Ereignisse. Wir verwenden die Job Cmdlets, um den Job zu beenden und die nicht benötigten Job-Objekte zu entfernen. Get-Content zeigt den Inhalt der Protokolldatei an.

Parameter

-Action

Gibt Befehle zur Behandlung der Ereignisse an. Die Befehle im Abschnitt Aktion ausführen, wenn ein Ereignis ausgelöst wird, anstatt das Ereignis an die Ereigniswarteschlange zu senden. Schließen Sie die Befehle in geschweifte Klammern ({}) ein, um einen Skriptblock zu erstellen.

Der Wert der Aktion kann den Parameter $Event, $EventSubscriber, $Sender, $EventArgs, und $Args automatische Variablen, die Informationen über das Ereignis an den Action Skript-Block. Weitere Informationen finden Sie unter about_Automatic_Variables.

Wenn Sie eine Aktion angeben, gibt Register-EngineEvent ein Event-Job-Objekt zurück, das diese Aktion darstellt. Sie können die Job-Cmdlets verwenden, um den Ereignisauftrag zu verwalten.

Typ:	ScriptBlock
Position:	101
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	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 für Ereignisse auf einem Remotecomputer oder in einer Remotesitzung registrieren.

Typ:	SwitchParameter
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-MaxTriggerCount

Gibt an, wie oft die Aktion für das Ereignisabonnement maximal ausgeführt wird.

Typ:	Int32
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-MessageData

Dieser Parameter ist Teil der Basisklasse für alle Event-Cmdlets. Der Register-EngineEvent verwendet diesen Parameter nicht. Alle an diesen Parameter übergebenen Daten werden ignoriert.

Typ:	PSObject
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-SourceIdentifier

Gibt den Quellbezeichner des Ereignisses an, für das Sie abonnieren. Der Quellbezeichner muss in der aktuellen Sitzung eindeutig sein. Dieser Parameter ist erforderlich.

Der Wert dieses Parameters erscheint im Wert des Feldes SourceIdentifier des Abonnentenobjekts und aller mit diesem Abonnement verbundenen Ereignisobjekte.

Der Wert ist spezifisch für die Quelle des Ereignisses. Dies kann ein beliebiger Wert sein, den Sie eigens erstellt haben, um ihn mit dem Cmdlet New-Event zu verwenden. Die PowerShell-Engine unterstützt die PSEngineEvent Werte PowerShell.Exiting und PowerShell.OnIdle.

Typ:	String
Position:	100
Standardwert:	None
Erforderlich:	True
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	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 er nicht unabhängig erkannt werden sollte.

Wenn Sie ein Abonnement anzeigen oder kündigen möchten, das mit dem Parameter SupportEvent erstellt wurde, fügen Sie den Parameter Force zu den Cmdlets Get-EventSubscriber oder Unregister-Event hinzu.

Typ:	SwitchParameter
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben

None

Standardmäßig gibt dieses Cmdlet keine Ausgabe zurück.

PSEventJob

Wenn Sie den parameter Action 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 der Verlassen von Ereignis, die Cmdlets, die von der Datenbank ausgeführt werden können Aktion Parameter sind auf die Cmdlets in der Datei Microsoft.PowerShell.Core und Microsoft.PowerShell.Utility Module. Die Verlassen von 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.

Der Motor gilt als im Leerlauf, wenn er keine Rohrleitung betreibt. Die OnIdle Ereignis wird ausgelöst, wenn PowerShell 300 Millisekunden (ms) lang im Leerlauf war.

Anmerkung

Wenn PSReadLine verwendet wird, wird die OnIdle Ereignis wird ausgelöst, wenn ReadKey() eine Zeitüberschreitung (keine Eingabe in 300ms). Das Ereignis könnte signalisiert werden, während sich der Benutzer in der Mitte der Bearbeitung einer Befehlszeile befindet, z. B. wenn der Benutzer Hilfe liest, um zu entscheiden, welcher Parameter verwendet werden soll. Beginnend mit PSReadLine 2.2.0-beta4, OnIdle Verhalten geändert, um das Ereignis nur dann zu signalisieren, wenn es eine ReadKey() Timeout und der aktuelle Bearbeitungspuffer ist leer.