Register-EngineEvent

  • Référence
Module:
Microsoft.PowerShell.Utility

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 $Eventvariables automatiques , , $EventArgs$EventSubscriber$Senderet $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.

PSEventJob

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.