Register-ObjectEvent

Register-ObjectEvent [-InputObject] <psobject> [-EventName] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]

C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" 

C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query 

C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived"

Description
-----------
Cet exemple crée un abonnement aux événements générés au démarrage d'un nouveau processus. 

La commande utilise l'objet ManagementEventWatcher pour obtenir des événements EventArrived. Un objet requête spécifie que les événements sont des événements de création d'instance pour la classe Win32_Process.

C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" 

C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query 

C:\PS> $action = { New-Event "PowerShell.ProcessCreated" -Sender $sender -EventArguments $SourceEventArgs.NewEvent.TargetInstance } 

C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived" -action $action

Id    Name            State      HasMoreData     Location             Command
--    ----            -----      -----------     --------             -------
2     422cfe5a-65e... Running    True                                 New-Event "PowerShe...

Description
-----------
Cet exemple montre comment spécifier une action pour répondre à un événement. Lorsque vous spécifiez une action, les événements déclenchés ne sont pas ajoutés à la file d'attente d'événements. Au lieu de cela, l'action répond à l'événement. 

Dans cet exemple, lorsqu'un événement de création d'instance est déclenché, indiquant qu'un nouveau processus est démarré, un nouvel événement ProcessCreated est déclenché.

L'action utilise les variables automatiques $Sender et $SourceEventArgs qui sont remplies uniquement pour les actions d'événement. 

La commande Register-ObjectEvent retourne un objet de traitement représentant l'action, qui s'exécute en tant que tâche en arrière-plan. Vous pouvez utiliser les applets de commande Job, telles que Get-Job et Receive-Job, pour gérer la tâche en arrière-plan. 

Pour plus d'informations, consultez about_Jobs.

C:\PS>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s -filepath ProcessCreationEvent.ps1

C:\PS> invoke-command -session $s { get-event }

# ProcessCreationEvent.ps1

function Enable-ProcessCreationEvent 
{ 
   $query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", ` 
       (New-Object TimeSpan 0,0,1), ` 
       "TargetInstance isa 'Win32_Process'" 
   $processWatcher = New-Object System.Management.ManagementEventWatcher $query 

   $identifier = "WMI.ProcessCreated" 
   Register-ObjectEvent -input $processWatcher -eventName "EventArrived" `
      -sourceIdentifier $identifier -messageData "Test" -forward 
   } 
} 

EnableProcessCreationEvent

Description
-----------
Cet exemple montre comment s'abonner à des événements d'objet sur les ordinateurs distants.

La première commande crée des sessions PSSession sur deux ordinateurs distants et les enregistre dans la variable $s.

La deuxième commande utilise le paramètre FilePath de l'applet de commande Invoke-Command pour exécuter le script ProcessCreationEvent.ps1 dans chaque session PSSession de la variable $s. 

Le script inclut une commande Register-ObjectEvent qui crée un abonnement à des événements de création d'instance sur l'objet Win32_Process à travers l'objet ManagementEventWatcher et son événement EventArrived.

C:\PS>$timer  = New-Object Timers.Timer

C:\PS> $timer.Interval = 500

C:\PS> $job = Register-ObjectEvent -inputObject $timer -eventName Elapsed -sourceIdentifier Timer.Random -Action {$random = Get-Random -Min 0 -Max 100}

C:\PS> $job.gettype().fullname
System.Management.Automation.PSEventJob

C:\PS> $job | format-list -property *

State         : Running
Module        : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0
StatusMessage :
HasMoreData   : True
Location      :
Command       : $random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 88944290-133d-4b44-8752-f901bd8012e2
Id            : 1
Name          : Timer.Random
ChildJobs     : {}
...

C:\PS> $timer.Enabled = $true

C:\PS> & $job.module {$random}
60

C:\PS> & $job.module {$random}
47

Description
-----------
Cet exemple montre comment utiliser le module dynamique dans l'objet PSEventJob créé lorsque vous incluez un paramètre Action dans une inscription d'événement.

La première commande utilise l'applet de commande New-Object pour créer un objet minuteur (Timer). La deuxième commande définit l'intervalle du minuteur à 500 (millisecondes).

La troisième commande utilise l'applet de commande Register-ObjectEvent pour inscrire l'événement Elapsed de l'objet minuteur. Elle inclut une action qui gère l'événement. Chaque fois que l'intervalle du minuteur s'écoule, un événement est déclenché et les commandes spécifiées dans Action s'exécutent. Dans ce cas, l'applet de commande Get-Random génère un nombre aléatoire compris entre 0 et 100, et l'enregistre dans la variable $random.

Lorsque vous utilisez un paramètre Action dans une commande Register-ObjectEvent, la commande retourne un objet PSEventJob qui représente l'action. Elle enregistre l'objet de traitement dans la variable $job.

L'objet PSEventJob que l'applet de commande Register-ObjectEvent retourne est également disponible dans la propriété Action de l'abonné aux événements. Pour plus d'informations, consultez Get-EventSubscriber.

La quatrième commande montre que la variable $job contient un objet PSEventJob. La cinquième commande utilise l'applet de commande Format-List pour afficher toutes les propriétés de l'objet PSEventJob dans une liste. 

L'objet PSEventJob a une propriété Module qui contient un module de script dynamique qui implémente l'action.

La sixième commande active le minuteur.

Les commandes restantes utilisent l'opérateur d'appel (&) pour appeler la commande dans le module et afficher la valeur de la variable $random. Vous pouvez utiliser l'opérateur d'appel pour appeler toute commande dans un module, notamment les commandes qui ne sont pas exportées. Dans ce cas, les commandes indiquent le nombre aléatoire généré lorsque l'événement Elapsed se produit.

Pour plus d'informations sur les modules, consultez about_Modules.