Crée un abonnement aux événements générés par un objet Microsoft .NET Framework.

Syntaxe

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

Description

L'applet de commande Register-ObjectEvent crée un abonnement aux événements générés par des objets .NET Framework sur l'ordinateur local ou sur un ordinateur distant.

Lorsque l'événement auquel vous êtes abonné est déclenché, il est ajouté à la file d'attente d'événements de votre session. Pour obtenir les événements qui se trouvent dans la file d'attente des événements, utilisez l'applet de commande Get-Event.

Vous pouvez utiliser les paramètres de Register-ObjectEvent pour spécifier les valeurs de propriété des événements qui peuvent vous aider à identifier l'événement figurant dans la file d'attente. Vous pouvez également utiliser le paramètre Action pour spécifier les actions à entreprendre lorsqu'un événement faisant l'objet d'un abonnement est déclenché, ainsi que le paramètre Forward pour envoyer des événements distants vers la file d'attente d'événements de la session locale.

Lorsque vous vous abonnez à un événement, un abonné est ajouté à votre session. Pour obtenir les abonnés d'événement qui se trouvent dans la session, utilisez l'applet de commande Get-EventSubscriber. Pour annuler l'abonnement, utilisez l'applet de commande Unregister-Event, qui supprime l'abonné d'événement de la session.

Paramètres

-Action <scriptblock>

Spécifie les commandes permettant de gérer les événements. Les commandes spécifiées dans Action s'exécutent quand un événement est déclenché, au lieu d'envoyer l'événement à la file d'attente d'événements. Placez les commandes entre accolades ( { } ) pour créer un bloc de script.

La valeur du paramètre Action peut inclure les variables automatiques $Event, $EventSubscriber, $Sender, $SourceEventArgs et $SourceArgs, qui fournissent des informations sur l'événement au bloc de script Action. Pour plus d'informations, consultez about_Automatic_Variables.

Lorsque vous spécifiez une action, Register-ObjectEvent retourne un objet de traitement d'événement qui représente cette action. Vous pouvez utiliser les applets de commande Job pour gérer la tâche d'événement.

Obligatoire ?

false

Position ?

102

Valeur par défaut

None.

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-EventName <string>

Spécifie l'événement auquel vous vous abonnez. Entrez le nom de l'évènement. Ce paramètre est obligatoire.

La valeur de ce paramètre n'est pas un nom que vous sélectionnez pour l'abonnement aux événements. Il s'agit du nom d'un événement exposé par l'objet .NET Framework. Par exemple, la classe ManagementEventWatcher contient des événements intitulés « EventArrived » et « Stopped ». Pour rechercher le nom d'un événement, utilisez l'applet de commande Get-Member.

Obligatoire ?

true

Position ?

2

Valeur par défaut

aucun

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-Forward

Envoie les événements de cet abonnement à une session à distance. Utilisez ce paramètre lorsque vous vous inscrivez aux événements sur un ordinateur distant ou dans une session à distance.

Obligatoire ?

false

Position ?

named

Valeur par défaut

False

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-InputObject <psobject>

Spécifie l'objet .NET Framework qui génère les événements. Entrez une variable contenant l'objet, ou tapez une commande ou une expression permettant d'obtenir cet objet. Ce paramètre est obligatoire.

Obligatoire ?

true

Position ?

1

Valeur par défaut

aucun

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-MessageData <psobject>

Spécifie toutes les données supplémentaires à associer à cet abonnement aux événements. La valeur de ce paramètre apparaît dans la propriété MessageData de tous les événements associés à cet abonnement.

Obligatoire ?

false

Position ?

named

Valeur par défaut

aucun

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-SourceIdentifier <string>

Spécifie un nom que vous sélectionnez pour l'abonnement. Le nom que vous sélectionnez doit être unique dans la session active. La valeur par défaut est le GUID affecté par Windows PowerShell.

La valeur de ce paramètre apparaît dans la valeur de la propriété SourceIdentifier de l'objet abonné et de tous les objets événements associés à cet abonnement.

Obligatoire ?

false

Position ?

101

Valeur par défaut

GUID

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-SupportEvent

Masque l'abonnement aux événements. Utilisez ce paramètre lorsque l'abonnement actuel fait partie d'un mécanisme d'inscription d'événement plus complexe et qu'il ne doit pas être découvert indépendamment.

Pour afficher ou annuler un abonnement qui a été créé avec le paramètre SupportEvent, utilisez le paramètre Force des applets de commande Get-EventSubscriber et Unregister-Event.

Obligatoire ?

false

Position ?

named

Valeur par défaut

False

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

<CommonParameters>

Cette applet de commande prend en charge les paramètres courants : -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer et -OutVariable. Pour plus d'informations, consultez about_Commonparameters.

Entrées et sorties

Le type d'entrée est le type des objets que vous pouvez diriger vers l'applet de commande. Le type de retour est le type des objets que l'applet de commande retourne.

Entrées

Aucun

Vous ne pouvez pas diriger d'objets vers Register-ObjectEvent.

Sorties

Aucun

Cette applet de commande ne génère aucune sortie.

Remarques

Les événements, les abonnements aux événements et la file d'attente d'événements existent uniquement dans la session active. Si vous fermez la session active, la file d'attente des événements est ignorée et l'abonnement aux événements est annulé.

Exemple 1

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.






Exemple 2

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.






Exemple 3

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.






Exemple 4

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.






Voir aussi




Table des matières