Register-ObjectEvent

Referenz

Modul:: Microsoft.PowerShell.Utility

Abonniert die Ereignisse, die von einem Microsoft .NET Framework -Objekt generiert werden.

Syntax

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

Beschreibung

Das cmdlet Register-ObjectEvent abonniert Ereignisse, die von .NET-Objekten auf dem lokalen Computer oder auf einem Remotecomputer generiert werden.

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

Sie können die Parameter von Register-ObjectEvent verwenden, um Eigenschaftswerte der Ereignisse anzugeben, die Ihnen helfen können, das Ereignis in der Warteschlange zu identifizieren. Sie können auch den Parameter Action verwenden, um Aktionen anzugeben, die ausgeführt werden sollen, wenn ein abonniertes Ereignis ausgelöst wird, und den Parameter Forward, um Remoteereignisse an die Ereigniswarteschlange in der lokalen Sitzung zu senden.

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

Beispiele

Beispiel 1: Abonnieren von Ereignissen beim Starten eines neuen Prozesses

In diesem Beispiel werden Ereignisse abonniert, die generiert werden, wenn ein neuer Prozess gestartet wird.

Der Befehl verwendet das ManagementEventWatcher--Objekt, um EventArrived--Ereignisse abzurufen. Ein Abfrageobjekt gibt an, dass die Ereignisse Instanzerstellungsereignisse für die Win32_Process Klasse sind.

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"

Beispiel 2: Angeben einer Aktion, die auf ein Ereignis reagiert

Wenn Sie eine Aktion angeben, werden ausgelöste Ereignisse nicht zur Ereigniswarteschlange hinzugefügt. Stattdessen antwortet die Aktion auf das Ereignis. Wenn in diesem Beispiel ein Instanzerstellungsereignis ausgelöst wird, das angibt, dass ein neuer Prozess gestartet wird, wird ein neues ProcessCreated-Ereignis ausgelöst.

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
$newEventArgs = @{
    SourceIdentifier = 'PowerShell.ProcessCreated'
    Sender = $Sender
    EventArguments = $EventArgs.NewEvent.TargetInstance
}
$Action = { New-Event @newEventArgs }
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action

Id   Name               PSJobTypeName   State       HasMoreData   Location   Command
--   ----               -------------   -----       -----------   --------   -------
 5   3db2d67a-efff-...                 NotStarted   False                    New-Event @newEventArgs

Die Aktion verwendet die $Sender und $EventArgs automatischen Variablen, die nur für Ereignisaktionen aufgefüllt werden.

Der Befehl Register-ObjectEvent gibt ein Auftragsobjekt zurück, das die Aktion darstellt, die als Hintergrundauftrag ausgeführt wird. Sie können die Job-Cmdlets wie Get-Job und Receive-Jobverwenden, um den Hintergrundauftrag zu verwalten. Weitere Informationen finden Sie unter about_Jobs.

Beispiel 3: Abonnieren von Objektereignissen auf Remotecomputern

In diesem Beispiel wird gezeigt, wie Objektereignisse auf Remotecomputern abonniert werden. In diesem Beispiel wird die Enable-ProcessCreationEvent-Funktion verwendet, die in der Skriptdatei ProcessCreationEvent.ps1 definiert ist. Dieses Skript ist für alle Computer im Beispiel verfügbar.

# ProcessCreationEvent.ps1
function  Enable-ProcessCreationEvent {
    $queryParameters = "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1),
        "TargetInstance isa 'Win32_Process'"
    $Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters

    $objectEventArgs = @{
        Input = New-Object System.Management.ManagementEventWatcher $Query
        EventName = 'EventArrived'
        SourceIdentifier = 'WMI.ProcessCreated'
        MessageData = 'Test'
        Forward = $True
    }
    Register-ObjectEvent @objectEventArgs
}

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
Invoke-Command -Session $S { Enable-ProcessCreationEvent }

Als erstes erstellen wir PSSessions auf zwei Remotecomputern und speichern sie in der $S Variablen. Als Nächstes führt das cmdlet Invoke-Command das ProcessCreationEvent.ps1 Skript in den einzelnen PSSessions in $Saus. Diese Aktion erstellt die Enable-ProcessCreationEvent-Funktion in den Remotesitzungen. Schließlich führen wir die Enable-ProcessCreationEvent-Funktion in den Remotesitzungen aus.

Die Funktion enthält einen Register-ObjectEvent-Befehl, der Instanzerstellungsereignisse für das Win32_Process-Objekt über das ManagementEventWatcher--Objekt und dessen EventArrived-Ereignis abonniert.

Beispiel 4: Verwenden des dynamischen Moduls im PSEventJob-Objekt

In diesem Beispiel wird gezeigt, wie Sie das dynamische Modul im PSEventJob--Objekt verwenden, das erstellt wird, wenn Sie eine Action- in eine Ereignisregistrierung einschließen. Zuerst erstellen und aktivieren wir ein Timerobjekt und legen dann das Intervall des Timers auf 500 (Millisekunden) fest. Das cmdlet Register-ObjectEvent registriert das Verstrichene Ereignis des Timerobjekts. Das PSEventJob--Objekt wird in der $Job Variablen gespeichert und ist auch in der Action-Eigenschaft des Ereignisabonnents verfügbar. Weitere Informationen finden Sie unter Get-EventSubscriber.

Wenn das Zeitgeberintervall verstrichen ist, wird ein Ereignis ausgelöst und die Aktion ausgeführt. In diesem Fall generiert das Cmdlet Get-Random eine Zufallszahl zwischen 0 und 100 und speichert sie in der variablen $Random.

$Timer = New-Object Timers.Timer
$Timer.Interval = 500
$Timer.Enabled = $True
$objectEventArgs = @{
    InputObject = $Timer
    EventName = 'Elapsed'
    SourceIdentifier = 'Timer.Random'
    Action = {$Random = Get-Random -Min 0 -Max 100}
}
$Job = Register-ObjectEvent @objectEventArgs
$Job | Format-List -Property *
& $Job.module {$Random}
& $Job.module {$Random}

State         : Running
Module        : __DynamicModule_53113769-31f2-42dc-830b-8749325e28d6
StatusMessage :
HasMoreData   : True
Location      :
Command       : $Random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 47b5ec9f-bfe3-4605-860a-4674e5d44ca8
Id            : 7
Name          : Timer.Random
ChildJobs     : {}
PSBeginTime   : 6/27/2019 10:19:06 AM
PSEndTime     :
PSJobTypeName :
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}
60
47

Die PSEventJob- verfügt über eine Module--Eigenschaft, die ein dynamisches Skriptmodul enthält, das die Aktion implementiert. Mit dem Aufrufoperator (&) rufen wir den Befehl im Modul auf, um den Wert der $Random Variablen anzuzeigen.

Weitere Informationen zu Modulen finden Sie unter about_Modules.

Parameter

-Action

Gibt die Befehle an, die das Ereignis behandeln sollen. Die Befehle in der Aktion 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 Action-Parameters kann die $Event, $EventSubscriber, $Sender, $EventArgsund $Args automatischen Variablen enthalten. Diese Variablen stellen Informationen zum Ereignis zum Action Skriptblock bereit. Weitere Informationen finden Sie unter about_Automatic_Variables.

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

Typ:	ScriptBlock
Position:	101
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-EventName

Gibt das Ereignis an, für das Sie abonnieren.

Der Wert dieses Parameters muss der Name des Ereignisses sein, das vom .NET-Objekt verfügbar gemacht wird. Die ManagementEventWatcher- Klasse verfügt beispielsweise über Ereignisse namens EventArrived und Stopped. Verwenden Sie das Cmdlet Get-Member, um den Ereignisnamen eines Ereignisses zu finden.

Typ:	String
Position:	1
Standardwert:	None
Erforderlich:	True
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-Forward

Gibt an, dass das Cmdlet Ereignisse für dieses Abonnement an eine Remotesitzung 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

-InputObject

Gibt das .NET-Objekt an, das die Ereignisse generiert. Geben Sie eine Variable ein, die das Objekt enthält, oder geben Sie einen Befehl oder Ausdruck ein, der das Objekt abruft.

Typ:	PSObject
Position:	0
Standardwert:	None
Erforderlich:	True
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-MaxTriggerCount

Gibt an, wie oft ein Ereignis ausgelöst werden kann.

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

-MessageData

Gibt alle zusätzlichen Daten an, die diesem Ereignisabonnement zugeordnet werden sollen. Der Wert dieses Parameters wird in der MessageData-Eigenschaft aller Ereignisse angezeigt, die diesem Abonnement zugeordnet sind.

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

-SourceIdentifier

Gibt einen Namen an, den Sie für das Abonnement auswählen. Der von Ihnen ausgewählte Name muss in der aktuellen Sitzung eindeutig sein. Der Standardwert ist die GUID, die PowerShell zuweist.

Der Wert dieses Parameters wird im Wert der SourceIdentifier Eigenschaft des Abonnentenobjekts und aller diesem Abonnement zugeordneten Ereignisobjekte angezeigt.

Typ:	String
Position:	100
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-SupportEvent

Gibt an, dass das Cmdlet das Ereignisabonnement ausblendet. Verwenden Sie diesen Parameter, wenn das aktuelle Abonnement Teil eines komplexeren Ereignisregistrierungsmechanismus ist und nicht unabhängig ermittelt werden sollte.

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

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.

Freigeben über

Register-ObjectEvent

Syntax

Beschreibung

Beispiele

Beispiel 1: Abonnieren von Ereignissen beim Starten eines neuen Prozesses

Beispiel 2: Angeben einer Aktion, die auf ein Ereignis reagiert

Beispiel 3: Abonnieren von Objektereignissen auf Remotecomputern

Beispiel 4: Verwenden des dynamischen Moduls im PSEventJob-Objekt

Parameter

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Eingaben

Ausgaben

Hinweise

Zusätzliche Ressourcen

Freigeben über

Register-ObjectEvent

Syntax

Beschreibung

Beispiele

Beispiel 1: Abonnieren von Ereignissen beim Starten eines neuen Prozesses

Beispiel 2: Angeben einer Aktion, die auf ein Ereignis reagiert

Beispiel 3: Abonnieren von Objektereignissen auf Remotecomputern

Beispiel 4: Verwenden des dynamischen Moduls im PSEventJob-Objekt

Parameter

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Eingaben

Ausgaben

Hinweise

Ähnliche Themen

Zusätzliche Ressourcen