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 Register-ObjectEvent Cmdlet 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 der Sitzung hinzugefügt. Verwenden Sie das Get-Event Cmdlet, um Ereignisse in der Ereigniswarteschlange abzurufen.

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

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.

Beispiele

Beispiel 1: Abonnieren von Ereignissen beim Starten eines neuen Prozesses

In diesem Beispiel werden Ereignisse abonniert, die beim Starten neuer Prozesse generiert werden.

Der Befehl verwendet das ManagementEventWatcher-Objekt zum Abrufen von EventArrived-Ereignissen . 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 der Ereigniswarteschlange hinzugefügt. Die Aktion reagiert stattdessen 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 die automatischen Variablen, die nur für Ereignisaktionen aufgefüllt werden.

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

Beispiel 3: Abonnieren von Objektereignissen auf Remotecomputern

Dieses Beispiel zeigt, wie Sie Objektereignisse auf Remotecomputern abonnieren können. In diesem Beispiel wird die Enable-ProcessCreationEvent Funktion verwendet, die in der ProcessCreationEvent.ps1 Skriptdatei 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 Invoke-Command Cmdlet das ProcessCreationEvent.ps1 Skript in den einzelnen PSSessions in $S. 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 das zugehörige 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 Aktion in eine Ereignisregistrierung einschließen. Zuerst erstellen und aktivieren wir ein Timerobjekt und legen dann das Intervall des Timers auf 500 (Millisekunden) fest. Das Register-ObjectEvent Cmdlet registriert das Elapsed-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 Get-Random Cmdlet eine Zufallszahl zwischen 0 und 100 und speichert sie in der $Random Variablen.

$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

Der PSEventJob verfügt über eine Moduleigenschaft , 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 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, , $Senderund $EventArgs$Args automatische Variablen enthalten. Diese Variablen stellen Informationen zum Ereignis für den Aktionsskriptblock bereit. Weitere Informationen finden Sie unter about_Automatic_Variables.

Wenn Sie eine Aktion angeben, wird ein Ereignisauftragsobjekt zurückgegeben, Register-ObjectEvent 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

-EventName

Gibt das Ereignis an, 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 Get-Member Cmdlet, um den Ereignisnamen eines Ereignisses zu finden.

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Forward

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

-InputObject

Gibt das .NET-Objekt an, das die Ereignisse generiert. Geben Sie eine Variable ein, die das Objekte enthält, oder geben Sie einen Befehl oder einen Ausdruck ein, mit dem das Objekt abgerufen wird.

Type:	PSObject
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxTriggerCount

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

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MessageData

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

Type:	PSObject
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	String
Position:	100
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

Um ein Abonnement anzuzeigen oder zu kündigen, das mit dem Parameter "SupportEvent" erstellt wurde, verwenden Sie den Force-Parameter der und Unregister-Event cmdletsGet-EventSubscriber.

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.

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

Feedback

Zusätzliche Ressourcen

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

Feedback

Zusätzliche Ressourcen