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 aux événements et événements du moteur De sortie générés par l’applet New-Event
de commande. Ces événements sont automatiquement ajoutés à la 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 vous vous abonnez à un événement, un abonné est ajouté à votre session. Pour obtenir les abonnés aux événements dans la session, utilisez l’applet de Get-EventSubscriber
commande. Pour annuler l’abonnement, utilisez l’applet Unregister-Event
de commande, qui supprime l’abonné à l’événement de la session.
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.
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
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 de sortie est exporté un fichier XML dans le répertoire de $HOME
l’utilisateur.
Exemple 3 : Créer 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 enregistre 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 n° 4, nous supprimons l’abonnement aux événements et les travaux, puis inspectons le fichier journal.
Exemple 4 : Annuler l’inscription d’événements et propre travaux up
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 à l’événement (ID de travail 18). L’ID de travail 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 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 dans les accolades ({}
) pour créer un bloc de script.
La valeur du paramètre Action peut inclure les $Event
variables automatiques , , $EventArgs
$EventSubscriber
$Sender
et $Args
les variables automatiques, 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 de fois où l’action est exécutée pour l’abonnement à l’événement.
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 é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 abonné et de tous les objets d’événement 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 PSEngineEvent PowerShell.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 les objets vers cette applet de commande.
Sorties
None
Par défaut, cette applet de commande ne retourne aucune sortie.
Lorsque vous utilisez le paramètre Action , cette applet de commande retourne un objet PSEventJob .
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 cette session, la file d'attente d'événements est ignorée et l'abonnement aux événements est annulé.
Lors de l’abonnement à l’événement Exiting , les applets de commande qui peuvent être exécutées par le paramètre Action sont limitées aux applets de commande dans les modules Microsoft.PowerShell.Core et Microsoft.PowerShell.Utility . L’événement exiting est déclenché uniquement lorsque la session est terminée sous le contrôle de PowerShell. L’événement n’est pas déclenché lorsque l’application hôte ou la fenêtre de terminal est fermée.
Le moteur est considéré comme inactif s’il n’exécute pas de pipeline. L’événement OnIdle est déclenché lorsque PowerShell a été inactif pendant 300 millisecondes (ms).
Remarque
Lorsque PSReadLine est en cours d’utilisation, l’événement OnIdle est déclenché quand ReadKey()
il expire (aucune saisie en 300 ms). L’événement peut être signalé pendant que l’utilisateur est au milieu de la modification d’une ligne de commande, par exemple, l’utilisateur lit l’aide pour décider quel paramètre utiliser. À compter de PSReadLine 2.2.0-beta4, le comportement OnIdle a changé pour signaler l’événement uniquement s’il existe un ReadKey()
délai d’expiration et que la mémoire tampon d’édition actuelle est vide.