Crée un abonnement aux événements générés par le moteur Windows PowerShell et par l'applet de commande New-Event.
Syntaxe
Register-EngineEvent [-SourceIdentifier] <string> [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]
Description
L'applet de commande Register-EngineEvent crée un abonnement aux événements générés par le moteur Windows PowerShell et par l'applet de commande New-Event. Utilisez le paramètre SourceIdentifier pour spécifier l'événement.
Vous pouvez utiliser cette applet de commande pour créer un abonnement à l'événement de sortie du moteur et aux événements générés par l'applet de commande New-Event. Ces événements sont automatiquement ajoutés à votre file d'attente d'événements dans votre session sans abonnement. Cependant, le fait de s'abonner permet de transférer les événements, de spécifier une action pour répondre aux événements et d'annuler l'abonnement.
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.
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-EngineEvent 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 |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-Forward
Envoie les événements liés à 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 |
False |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-MessageData <psobject>
Spécifie des données supplémentaires associées à l'événement. La valeur de ce paramètre apparaît dans la propriété MessageData de l'objet événement.
|
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 l'identificateur source de l'événement auquel vous vous abonnez. L'identificateur source doit être unique dans la session active. Ce paramètre est obligatoire.
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 ? |
true |
|
Position ? |
101 |
|
Valeur par défaut |
|
|
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'entrée vers Register-EngineEvent. |
|
Sorties |
Aucun ou System.Management.Automation.PSEventJob Si vous utilisez le paramètre Action, Register-EngineEvent retourne un objet System.Management.Automation.PSEventJob. Sinon, elle 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>$s = new-pssession -computername Server01, Server02
C:\PS> invoke-command -session $s { Register-EngineEvent -sourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -forward }
Description
-----------
Cette commande s'inscrit à un événement de moteur Windows PowerShell sur deux ordinateurs distants.
La première commande crée une session PSSession sur chaque ordinateur distant.
La deuxième commande utilise l'applet de commande Invoke-Command pour exécuter la commande Register-EngineEvent dans les sessions à distance.
La commande Register-EngineEvent utilise le paramètre SourceIdentifier pour identifier l'événement. Elle utilise le paramètre Forward pour transférer les événements de la session à distance vers la session locale.
Exemple 2
C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated -action { $processName | add-content processLog.txt }
C:\PS> get-event
C:\PS> $results = $j | receive-job
C:\PS> unregister-event PowerShell.ProcessCreated
Description
-----------
Cette commande montre comment utiliser les applets de commande Job pour gérer l'objet de traitement d'événement retourné par Register-EngineEvent lorsque vous utilisez le paramètre Action.
Les tâches d'événements sont gérées comme les autres tâches de Windows PowerShell. Pour plus d'informations, consultez about_jobs. Dans cet exemple, l'applet de commande Receive-Job est utilisée pour obtenir les résultats de la tâche.
Pour supprimer la tâche de la session, utilisez Remove-Job. Pour annuler votre abonnement aux événements, utilisez l'applet de commande Unregister-Event. Pour supprimer les événements de la file d'attente d'événements, utilisez Remove-Event.
Voir aussi