Register-EngineEvent
S’abonne aux événements générés par le moteur PowerShell et par l’applet de New-Event commande.
Syntax
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Description
L’applet Register-EngineEvent de commande s’abonne aux événements générés par le moteur PowerShell et l’applet de New-Event commande. Utilisez le paramètre SourceIdentifier pour spécifier l'événement.
Vous pouvez utiliser cette applet de commande pour vous abonner à l’événement du moteur de sortie et aux événements générés par l’applet de New-Event commande. Ces événements sont automatiquement ajoutés à la file d'attente d'événements de votre session sans abonnement. 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.
Quand l'événement auquel vous êtes 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 Get-Event commande .
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, ce qui supprime l'abonné aux événements de la session.
Exemples
Exemple 1 : Inscrire un événement de moteur PowerShell sur des ordinateurs distants
Cet exemple s’inscrit pour un événement de moteur PowerShell sur deux ordinateurs distants.
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}New-PSSession crée une session gérée par l’utilisateur (PSSession) sur chacun des ordinateurs distants. L’applet Invoke-Command de commande exécute la Register-EngineEvent commande dans les sessions à distance.
Register-EngineEvent utilise le paramètre SourceIdentifier pour identifier l’événement. Le paramètre Forward indique au moteur de transférer les événements de la session distante à la session locale.
Exemple 2 : Effectuer une action spécifiée lorsque l’événement Exiting se produit
Cet exemple montre comment exécuter Register-EngineEvent pour effectuer une action spécifique lorsque l’événement PowerShell.Exiting se produit.
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}Le paramètre SupportEvent est ajouté pour masquer l’abonnement aux événements. Lorsque PowerShell se ferme, dans ce cas, l’historique des commandes de la session sortante est exporté un fichier XML dans le répertoire de $Home l’utilisateur.
Exemple 3 : Create et s’abonner à un événement défini par l’utilisateur
Cet exemple crée un abonnement pour les événements à partir de la source MyEventSource. Il s’agit d’une source arbitraire que nous allons utiliser pour surveiller la progression d’un travail. Register-EngineEvent est utilisé pour créer l’abonnement. Le bloc de script du paramètre Action journalise les données d’événement dans un fichier texte.
Register-EngineEvent -SourceIdentifier MyEventSource -Action {
"Event: {0}" -f $event.messagedata | Out-File c:\temp\MyEvents.txt -Append
}
Start-Job -Name TestJob -ScriptBlock {
While ($True) {
Register-EngineEvent -SourceIdentifier MyEventSource -Forward
Start-Sleep -seconds 2
"Doing some work..."
New-Event -SourceIdentifier MyEventSource -Message ("{0} - Work done..." -f (Get-Date))
}
}
Start-Sleep -seconds 4
Get-EventSubscriber
Get-Job
SubscriptionId : 12
SourceObject :
EventName :
SourceIdentifier : MyEventSource
Action : System.Management.Automation.PSEventJob
HandlerDelegate :
SupportEvent : False
ForwardEvent : False
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Running True …
19 TestJob BackgroundJob Running True localhost …Register-EngineEvent id de travail créé 18. Start-Job id de travail créé 19. Dans l’exemple 4, nous supprimons l’abonnement aux événements et les travaux, puis inspectons le fichier journal.
Exemple 4 : Désinscrire des événements et propre des travaux
Il s’agit d’une continuation de l’exemple 3. Dans cet exemple, nous attendons 10 secondes pour laisser plusieurs événements se produire. Ensuite, nous annulons l’inscription de l’abonnement aux événements.
PS> Start-Sleep -seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Stopped False …
19 TestJob BackgroundJob Running True localhost …
PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM - Work done...
Event: 2/18/2020 2:36:21 PM - Work done...
Event: 2/18/2020 2:36:23 PM - Work done...
Event: 2/18/2020 2:36:25 PM - Work done...
Event: 2/18/2020 2:36:27 PM - Work done...
Event: 2/18/2020 2:36:29 PM - Work done...
Event: 2/18/2020 2:36:31 PM - Work done...L’applet Unregister-Event de commande arrête le travail associé à l’abonnement aux événements (ID de travail 18). Le travail ID 19 est toujours en cours d’exécution et crée de nouveaux événements. Nous utilisons les applets de commande Job pour arrêter le travail et supprimer les objets de travail inutiles. Get-Content affiche le contenu du fichier journal.
Paramètres
-Action
Spécifie les commandes qui gèrent les événements. Les commandes 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 $Eventvariables automatiques , $EventSubscriber, $EventArgs$Sender, et $Args 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 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.
| Type: | ScriptBlock |
| Position: | 101 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Forward
Indique que l’applet de commande envoie des é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.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaxTriggerCount
Spécifie le nombre maximal d’exécutions de l’action pour l’abonnement aux événements.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 d'événement.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 d'abonné et de tous les objets d'événements associés à cet abonnement.
La valeur est spécifique à la source de l’événement. Il peut s’agir d’une valeur arbitraire que vous avez créée pour l’utiliser avec l’applet de New-Event commande . Le moteur PowerShell prend en charge les valeurs EngineEventPowerShell.Exiting et PowerShell.OnIdle.
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 , ajoutez le paramètre Force aux Get-EventSubscriber applets de commande ou Unregister-Event .
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
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 , Register-EngineEvent retourne un objet System.Management.Automation.PSEventJob . Sinon, elle ne génère aucune sortie.
Notes
Aucune source d’événement disponible sur les plateformes Linux ou macOS.
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 cette session, la file d'attente d'événements est ignorée et l'abonnement aux événements est annulé.