Partager via

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 OnIdle ou Exiting 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 dans 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.

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

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 inscrit 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 distantes. 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 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..."
        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 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. Enfermez les commandes dans des accolades ({}) pour créer un bloc de script.

La valeur du paramètre Action peut inclure les $Eventvariables automatiques , $EventSubscriber, $Sender, $EventArgset $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 de fois où l’action est exécutée 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 à utiliser avec l’applet de New-Event commande. Le moteur PowerShell prend en charge les valeurs PSEngineEventPowerShell.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 applets de Get-EventSubscriber 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 d’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 quitté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).

Notes

Lorsque PSReadLine est en cours d’utilisation, l’événement OnIdle est déclenché lorsque le ReadKey() délai d’expiration (aucune saisie dans 300 ms). L’événement peut être signalé lorsque l’utilisateur se trouve au milieu de la modification d’une ligne de commande, par exemple, l’utilisateur lit l’aide pour décider du paramètre à utiliser. À compter de PSReadLine 2.2.0-beta4, le comportement d’OnIdle a changé pour signaler l’événement uniquement s’il existe un délai d’expiration ReadKey() et que la mémoire tampon d’édition actuelle est vide.