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.
Mit diesem Cmdlet können Sie die Vom Cmdlet generierten New-Event
Ereignisse und Ereignisse des OnIdle- oder Exiting-Moduls abonnieren. Diese Ereignisse werden automatisch der Ereigniswarteschlange in Ihrer Sitzung hinzugefügt, ohne dass sie abonniert werden. 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. Verwenden Sie das Get-EventSubscriber
Cmdlet, um die Ereignisabonnenten in der Sitzung abzurufen. Verwenden Sie zum Kündigen des Abonnements das Unregister-Event
Cmdlet, 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 Get-Event
Cmdlet, um Ereignisse in der Ereigniswarteschlange abzurufen.
Beispiele
Beispiel 1: Registrieren eines PowerShell-Modulereignisses auf Remotecomputern
In diesem Beispiel wird ein PowerShell-Modulereignis 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 vom Benutzer 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 teilt dem Modul mit, die Ereignisse von der Remotesitzung an die lokale Sitzung weiterzuleiten.
Beispiel 2: Ausführen einer angegebenen Aktion beim Auftreten des Exiting-Ereignisses
Dieses Beispiel zeigt, 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 beendigungssitzung eine XML-Datei im Verzeichnis des $HOME
Benutzers exportiert.
Beispiel 3: Erstellen 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 Aktionsparameter 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
die Auftrags-ID 18 erstellt. Start-Job
Die Auftrags-ID 19 wurde erstellt. In Beispiel Nr. 4 entfernen wir das Ereignisabonnement und die Aufträge und prüfen dann die Protokolldatei.
Beispiel 4: Aufheben der Registrierung von Ereignissen und sauber Aufwärtsaufträgen
Dies ist eine Fortsetzung von Beispiel 3. In diesem Beispiel warten wir 10 Sekunden, damit mehrere Ereignisse auftreten können. 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 neue Ereignisse erstellt. Wir verwenden die Auftrags-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. Die Befehle in der Aktion werden ausgeführt, 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 des Aktionsparameters kann die $Event
Variablen , $EventSubscriber
, $Sender
, $EventArgs
und $Args
automatische Variablen enthalten, die Informationen zum Ereignis für den Aktionsskriptblock bereitstellen. Weitere Informationen finden Sie unter about_Automatic_Variables.
Wenn Sie eine Aktion angeben, wird ein Ereignisauftragsobjekt zurückgegeben, Register-EngineEvent
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 die maximale Anzahl von Male an, mit denen die Aktion 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 das New-Event
Cmdlet erstellt haben. Das PowerShell-Modul 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 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 Get-EventSubscriber
Cmdlets hinzu Unregister-Event
.
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 weiterleiten.
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.
Das Modul gilt als im Leerlauf, wenn keine Pipeline ausgeführt wird. Das OnIdle-Ereignis wird ausgelöst, wenn PowerShell für 300 Millisekunden (ms) im Leerlauf war.
Hinweis
Wenn PSReadLine verwendet wird, wird das OnIdle-Ereignis ausgelöst, wenn ReadKey()
ein Zeitüberschreitung (keine Eingabe in 300 ms) erfolgt. 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. Ab PSReadLine 2.2.0-beta4 wurde das OnIdle-Verhalten geändert, um das Ereignis nur zu signalisieren, wenn ein ReadKey()
Timeout vorhanden ist und der aktuelle Bearbeitungspuffer leer ist.