Register-EngineEvent
S’abonne aux événements générés par le moteur Windows PowerShell et par l’applet de commande New-Event.
Syntaxe
Default (Par défaut)
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Description
L’applet de commande Register-EngineEvent
Vous pouvez utiliser cette applet de commande pour vous abonner à l’événement et aux événements du moteur de sortie 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 s’abonner. Toutefois, l’abonnement vous 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 abonné est déclenché, il est ajouté à la file d’attente d’événements dans votre session. Pour obtenir des événements dans la file d’attente d’événements, utilisez l’applet de commande Get-Event.
Lorsque vous vous abonnez à un événement, un abonné à un événement est ajouté à votre session. Pour obtenir les abonnés aux événements 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é à l’événement de la session.
Exemples
Exemple 1 : Inscrire un événement de moteur PowerShell sur des ordinateurs distants
PS C:\> $S = New-PSSession -ComputerName "Server01, Server02"
PS C:\> Invoke-Command -Session $S { Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward }
Cette commande s’inscrit pour un événement de moteur Windows PowerShell sur deux ordinateurs distants.
La première commande crée une session gérée par l’utilisateur (PSSession) sur chacun des ordinateurs distants.
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. Il utilise le paramètre Forward pour transférer les événements de la session distante vers la session locale.
Exemple 2 : effectuer une action spécifiée lorsque l’événement Exiting se produit
PS C:\> Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}
Cette commande montre comment exécuter Register-EngineEvent pour effectuer une action spécifique lorsque l’événement PowerShell.Exiting se produit. Le paramètre SupportEvent est ajouté pour masquer l’abonnement aux événements. Lorsque Windows PowerShell se ferme, dans ce cas, l’historique des commandes de la session de sortie est exporté au format XML vers un nom de fichier et un chemin d’accès dans le répertoire $Home de l’utilisateur.
Paramètres
-Action
Spécifie les commandes pour gérer les événements. Les commandes de l’action s’exécutent lorsqu’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 de
Lorsque vous spécifiez une action, Register-EngineEvent retourne un objet de travail d’événement qui représente cette action. Vous pouvez utiliser les applets de commande Job pour gérer la tâche de l'événement.
Propriétés du paramètre
| Type: | ScriptBlock |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | 101 |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-Forward
Indique que le cmdlet envoie des événements pour cet abonnement à la session sur l’ordinateur local. Utilisez ce paramètre lorsque vous inscrivez des événements sur un ordinateur distant ou dans une session à distance.
Propriétés du paramètre
| Type: | SwitchParameter |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-MaxTriggerCount
Spécifie le nombre maximal de déclencheurs.
La valeur du paramètre Action de
Lorsque vous spécifiez une action, Register-EngineEvent retourne un objet de travail d’événement qui représente cette action. Vous pouvez utiliser les applets de commande Job pour gérer la tâche de l'événement.
Propriétés du paramètre
| Type: | Int32 |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-MessageData
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.
Propriétés du paramètre
| Type: | PSObject |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-SourceIdentifier
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 d’événement associés à cet abonnement.
Les valeurs EngineEvent prises en charge incluent PowerShell.Exiting, PowerShell.OnIdle et PowerShell.OnScriptBlockInvoke.
Propriétés du paramètre
| Type: | String |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | 100 |
| Obligatoire: | True |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-SupportEvent
Indique que l’applet de commande masque l’abonnement aux événements. Ajoutez ce paramètre lorsque l’abonnement actuel fait partie d’un mécanisme d’inscription d’événements plus complexe et qu’il ne doit pas être découvert indépendamment.
Pour afficher ou annuler un abonnement créé avec le paramètre SupportEvent
Propriétés du paramètre
| Type: | SwitchParameter |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
CommonParameters
Cette applet de commande prend en charge les paramètres courants : -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction et -WarningVariable. Pour plus d’informations, consultez about_CommonParameters.
Entrées
None
Vous ne pouvez pas diriger l’entrée vers Register-EngineEvent.
Sorties
None or System.Management.Automation.PSEventJob
Si vous utilisez le paramètre Action de
Notes
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 d’événements est ignorée et l’abonnement à l’événement est annulé.