Register-EngineEvent

Register-EngineEvent
    [-SourceIdentifier] <String>
    [[-Action] <ScriptBlock>]
    [-MessageData <PSObject>]
    [-SupportEvent]
    [-Forward]
    [-MaxTriggerCount <Int32>]
    [<CommonParameters>]

L’applet de commande Register-EngineEvent s’abonne aux événements générés par le moteur PowerShell et l’applet de commande New-Event. Utilisez le paramètre SourceIdentifier pour spécifier l’événement.

Vous pouvez utiliser ce cmdlet pour vous abonner aux événements du moteur OnIdle ou Exiting et aux événements générés par le cmdlet New-Event. 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é à un événement est ajouté à votre session. Pour obtenir les abonnés à l’événement dans la session, utilisez le cmdlet Get-EventSubscriber. Pour annuler l’abonnement, utilisez l’applet de commande Unregister-Event, qui supprime l’abonné à l’événement de la session.

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.

Cet exemple s'enregistre pour un événement du 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 de commande Invoke-Command exécute la commande Register-EngineEvent 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.

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 de sortie est exporté un fichier XML dans le répertoire $HOME de 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 pour le paramètre Action consigne 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..."
        $newEventSplat = @{
            SourceIdentifier = 'MyEventSource'
            MessageData      = ("{0} -  Work done..." -f (Get-Date))
        }
        New-Event @newEventSplat
    }
}
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 a créé l’ID de travail 18. Start-Job a créé l'identifiant de travail 19. Dans l’exemple n° 4, nous supprimons l’abonnement aux événements et les travaux, puis inspectons le fichier journal.

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 de commande Unregister-Event arrête le travail associé à l’abonnement à l’événement (ID de travail 18). Le Job ID 19 est toujours en cours d’exécution et crée de nouveaux événements. Nous utilisons les applets de commande Tâche pour arrêter la tâche et supprimer les objets de tâche inutiles. Get-Content affiche le contenu du fichier journal.

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.

Vous ne pouvez pas diriger les objets vers cette applet de commande.

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.

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é.

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 n’est déclenché que lorsque la session est fermé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 étant 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).