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 Ihrer 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 $EventVariablen , $EventSubscriber, $Sender, $EventArgsund $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.

PSEventJob

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.