Register-ObjectEvent

Référence

Module:: Microsoft.PowerShell.Utility

S'abonne aux événements générés par un objet Microsoft .NET Framework.

Syntax

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

Description

L’applet Register-ObjectEvent de commande s’abonne aux événements générés par des objets .NET sur l’ordinateur local ou sur un ordinateur distant.

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 .

Vous pouvez utiliser les paramètres de Register-ObjectEvent pour spécifier les valeurs de propriété des événements qui peuvent vous aider à identifier l’événement dans la file d’attente. Vous pouvez également utiliser le paramètre Action pour spécifier les actions à effectuer lorsqu’un événement abonné est déclenché et le paramètre Forward pour envoyer des événements distants à la file d’attente d’événements dans la session locale.

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.

Exemples

Exemple 1 : S’abonner à des événements lorsqu’un nouveau processus démarre

Cet exemple s'abonne aux événements générés au démarrage d'un nouveau processus.

La commande utilise l’objet ManagementEventWatcher pour obtenir des événements EventArrived . Un objet de requête spécifie que les événements sont instance événements de création pour la classe Win32_Process.

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"

Exemple 2 : Spécifier une action pour répondre à un événement

Lorsque vous spécifiez une action, les événements déclenchés ne sont pas ajoutés à la file d'attente des événements. À la place, l'action répond à l'événement. Dans cet exemple, lorsqu’un événement de création instance est déclenché indiquant qu’un nouveau processus est démarré, un nouvel événement ProcessCreated est déclenché.

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
$newEventArgs = @{
    SourceIdentifier = 'PowerShell.ProcessCreated'
    Sender = $Sender
    EventArguments = $EventArgs.NewEvent.TargetInstance
}
$Action = { New-Event @newEventArgs }
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action

Id   Name               PSJobTypeName   State       HasMoreData   Location   Command
--   ----               -------------   -----       -----------   --------   -------
 5   3db2d67a-efff-...                 NotStarted   False                    New-Event @newEventArgs

L’action utilise les $Sender variables automatiques et $EventArgs qui sont remplies uniquement pour les actions d’événement.

La Register-ObjectEvent commande retourne un objet de travail qui représente l’action, qui s’exécute comme un travail en arrière-plan. Vous pouvez utiliser les applets de commande Job, telles que Get-Job et Receive-Job, pour gérer le travail en arrière-plan. Pour plus d’informations, consultez à propos des_tâches.

Exemple 3 : S’abonner à des événements d’objet sur des ordinateurs distants

Cet exemple montre comment s'abonner aux événements d'objet sur des ordinateurs distants. Cet exemple utilise la Enable-ProcessCreationEvent fonction définie dans le fichier de ProcessCreationEvent.ps1 script. Ce script est disponible pour tous les ordinateurs de l’exemple.

# ProcessCreationEvent.ps1
function  Enable-ProcessCreationEvent {
    $queryParameters = "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1),
        "TargetInstance isa 'Win32_Process'"
    $Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters

    $objectEventArgs = @{
        Input = New-Object System.Management.ManagementEventWatcher $Query
        EventName = 'EventArrived'
        SourceIdentifier = 'WMI.ProcessCreated'
        MessageData = 'Test'
        Forward = $True
    }
    Register-ObjectEvent @objectEventArgs
}

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
Invoke-Command -Session $S { Enable-ProcessCreationEvent }

Le premier, nous créons des sessions PSSession sur deux ordinateurs distants et les enregistrez dans la $S variable. Ensuite, l’applet Invoke-Command de commande exécute le ProcessCreationEvent.ps1 script dans chacune des sessions PSSession dans $S. Cette action crée la Enable-ProcessCreationEvent fonction dans les sessions distantes. Enfin, nous exécutons la Enable-ProcessCreationEvent fonction dans les sessions distantes.

La fonction inclut une Register-ObjectEvent commande qui s’abonne à instance événements de création sur l’objet Win32_Process via l’objet ManagementEventWatcher et son événement EventArrived.

Exemple 4 : Utiliser le module dynamique dans l’objet PSEventJob

Cet exemple montre comment utiliser le module dynamique dans l’objet PSEventJob créé lorsque vous incluez une action dans une inscription d’événement. Tout d’abord, nous créons et activez un objet minuteur, puis nous définissons l’intervalle du minuteur sur 500 (millisecondes). L’applet Register-ObjectEvent de commande inscrit l’événement Elapsed de l’objet minuteur. L’objet PSEventJob est enregistré dans la $Job variable et est également disponible dans la propriété Action de l’abonné à l’événement. Pour plus d’informations, consultez Get-EventSubscriber.

Chaque fois que l’intervalle du minuteur s’écoule, un événement est déclenché et l’action est exécutée. Dans ce cas, l’applet de Get-Random commande génère un nombre aléatoire compris entre 0 et 100 et l’enregistre dans la $Random variable.

$Timer = New-Object Timers.Timer
$Timer.Interval = 500
$Timer.Enabled = $True
$objectEventArgs = @{
    InputObject = $Timer
    EventName = 'Elapsed'
    SourceIdentifier = 'Timer.Random'
    Action = {$Random = Get-Random -Min 0 -Max 100}
}
$Job = Register-ObjectEvent @objectEventArgs
$Job | Format-List -Property *
& $Job.module {$Random}
& $Job.module {$Random}

State         : Running
Module        : __DynamicModule_53113769-31f2-42dc-830b-8749325e28d6
StatusMessage :
HasMoreData   : True
Location      :
Command       : $Random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 47b5ec9f-bfe3-4605-860a-4674e5d44ca8
Id            : 7
Name          : Timer.Random
ChildJobs     : {}
PSBeginTime   : 6/27/2019 10:19:06 AM
PSEndTime     :
PSJobTypeName :
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}
60
47

PsEventJob a une propriété Module qui contient un module de script dynamique qui implémente l’action. À l’aide de l’opérateur d’appel (&), nous invoquons la commande dans le module pour afficher la valeur de la $Random variable.

Pour plus d’informations sur les modules, consultez about_Modules.

Paramètres

-Action

Spécifie les commandes pour gérer l’événement. 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 . Ces variables 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-ObjectEvent 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

-EventName

Spécifie l'événement auquel vous vous abonnez.

La valeur de ce paramètre doit être le nom de l’événement exposé par l’objet .NET. Par exemple, la classe ManagementEventWatcher a des événements nommés EventArrived et Stopped. Pour rechercher le nom d’événement d’un événement, utilisez l’applet de Get-Member commande.

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Forward

Indique que l’applet de commande envoie des événements pour cet abonnement à une session distante. 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

-InputObject

Spécifie l’objet .NET qui génère les événements. Entrez une variable contenant l'objet, ou tapez une commande ou une expression qui l'obtient.

Type:	PSObject
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxTriggerCount

Spécifie le nombre maximal de fois qu’un événement peut être déclenché.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MessageData

Spécifie toutes les données supplémentaires à associer à cet abonnement aux événements. La valeur de ce paramètre apparaît dans la propriété MessageData de tous les événements associés à cet abonnement.

Type:	PSObject
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SourceIdentifier

Spécifie un nom que vous sélectionnez pour l'abonnement. Le nom que vous sélectionnez doit être unique dans la session active. La valeur par défaut est le GUID attribué par PowerShell.

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énements associés à cet abonnement.

Type:	String
Position:	100
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SupportEvent

Indique que l’applet de commande masque l’abonnement aux événements. Utilisez ce paramètre lorsque l’abonnement actuel fait partie d’un mécanisme d’inscription d’événements plus complexe et ne doit pas être découvert indépendamment.

Pour afficher ou annuler un abonnement créé avec le paramètre SupportEvent , utilisez le paramètre Force des applets de Get-EventSubscriber commande et 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é.

Partager via

Register-ObjectEvent

Syntax

Description

Exemples

Exemple 1 : S’abonner à des événements lorsqu’un nouveau processus démarre

Exemple 2 : Spécifier une action pour répondre à un événement

Exemple 3 : S’abonner à des événements d’objet sur des ordinateurs distants

Exemple 4 : Utiliser le module dynamique dans l’objet PSEventJob

Paramètres

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Entrées

Sorties

Notes

Ressources supplémentaires

Partager via

Register-ObjectEvent

Syntax

Description

Exemples

Exemple 1 : S’abonner à des événements lorsqu’un nouveau processus démarre

Exemple 2 : Spécifier une action pour répondre à un événement

Exemple 3 : S’abonner à des événements d’objet sur des ordinateurs distants

Exemple 4 : Utiliser le module dynamique dans l’objet PSEventJob

Paramètres

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Entrées

Sorties

Notes

Liens associés

Ressources supplémentaires