S'abonne à un événement Windows Management Instrumentation (WMI).

Syntaxe

Register-WmiEvent [-Class] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Register-WmiEvent [-Query] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Description

L'applet de commande Register-WmiEvent s'abonne aux événements WMI sur l'ordinateur local ou sur un ordinateur distant.

Lorsque l'événement WMI abonné se déclenche, il est ajouté à la file d'attente des événements dans votre session locale, même si l'événement se produit sur un ordinateur distant. 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-WmiEvent pour vous abonner à des événements sur des ordinateurs distants et spécifier les valeurs de propriété des événements qui peuvent vous aider à identifier l'événement qui figure dans la file d'attente. Vous pouvez également utiliser le paramètre Action pour spécifier les actions à effectuer lorsqu'un événement abonné se déclenche.

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 qui gèrent les événements. Les commandes spécifiées dans le paramètre 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-WmiEvent retourne un objet de traitement d'événement qui représente cette action. Vous pouvez utiliser les applets de commande qui contiennent Job (les applets de commande Job) pour gérer la tâche d'événement.

Obligatoire ?

false

Position ?

102

Valeur par défaut

The event is added to the event queue.

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-Class <string>

Spécifie l'événement auquel vous vous abonnez. Entrez la classe WMI qui génère les événements. Un paramètre Class ou Query est obligatoire dans chaque commande.

Obligatoire ?

true

Position ?

1

Valeur par défaut

aucun

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-ComputerName <string>

Spécifie un ordinateur distant. La valeur par défaut est l'ordinateur local. Entrez un nom NetBIOS, une adresse IP ou un nom de domaine complet.

Obligatoire ?

false

Position ?

named

Valeur par défaut

Local computer

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-Credential <PSCredential>

Spécifie un compte d'utilisateur qui a l'autorisation d'exécuter cette action. Tapez un nom d'utilisateur, tel que « User01 » ou « Domain01\User01 ». Vous pouvez également entrer un objet PSCredential, tel que celui généré par l'applet de commande Get-Credential. Si vous tapez un nom d'utilisateur, vous êtes invité à entrer un mot de passe.

Obligatoire ?

false

Position ?

named

Valeur par défaut

The credentials of the current user

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-Forward

Envoie les événements pour cet abonnement à la session sur l'ordinateur local. 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

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

None. The MessageData property is NULL.

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-Namespace <string>

Spécifie l'espace de noms de la classe WMI.

Obligatoire ?

false

Position ?

named

Valeur par défaut

aucun

Accepter l'entrée de pipeline ?

false

Accepter les caractères génériques ?

false

-Query <string>

Spécifie une requête dans Langage de requêtes WMI (WQL) qui identifie la classe d'événements WMI (« select * from __InstanceDeletionEvent », par exemple).

Obligatoire ?

true

Position ?

1

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

-Timeout <Int64>

Détermine le délai d'attente de Windows PowerShell jusqu'à ce que cette commande soit exécutée.

La valeur par défaut, 0 (zéro), indique qu'aucun délai d'attente n'est défini et elle fait attendre Windows PowerShell indéfiniment.

Obligatoire ?

false

Position ?

named

Valeur par défaut

0

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

None

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

Sorties

None

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

Remarques

Pour utiliser cette applet de commande sous Windows Vista ou une version ultérieure de Windows, démarrez Windows PowerShell avec l'option Exécuter en tant qu'administrateur.

Les événements, les abonnements aux événements et la file d'attente des é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>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted"

Description
-----------
Cette commande s'abonne aux événements générés par la classe Win32_ProcessStartTrace. Cette classe déclenche un événement à chaque démarrage d'un processus.

Exemple 2

C:\PS>register-wmiEvent -query "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'" -sourceIdentifier "WMIProcess" -messageData "Test 01" -timeout 500

Description
-----------
Cette commande utilise une requête pour s'abonner aux événements de création de l'instance Win32_process.

Exemple 3

C:\PS>$action = { get-history | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }

C:\PS> register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted" -action $action

Id    Name            State      HasMoreData   Location  Command
--    ----            -----      -----------   --------  -------
1     ProcessStarted  NotStarted False                   get-history | where {...

Description
-----------
Cet exemple montre comment utiliser une action pour répondre à un événement. Dans ce cas, lorsqu'un processus démarre, toute commande Start-Process présente dans la session active est écrite dans un fichier XML. 

Lorsque vous utilisez le paramètre Action, Register-WmiEvent retourne une tâche en arrière-plan qui représente l'action de l'événement. Vous pouvez utiliser les applets de commande Job, telles que Get-Job et Receive-Job, pour gérer la tâche de l'événement.

Pour plus d'informations, consultez about_Jobs.

Exemple 4

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "Start" -computername Server01 

C:\PS> get-event -sourceIdentifier "Start"

Description
-----------
Cet exemple inscrit des événements sur l'ordinateur distant Server01. 

WMI retourne les événements à l'ordinateur local et les stocke dans la file d'attente des événements dans la session active. Pour récupérer les événements, exécutez une commande Get-Event locale.

Voir aussi



Table des matières