Register-ObjectEvent

Référence

Module:: Microsoft.PowerShell.Utility

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

Syntaxe

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 spécifier les valeurs de Register-ObjectEvent 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 des actions à entreprendre 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 Get-EventSubscriber commande. Pour annuler l’abonnement, utilisez l’applet Unregister-Event de commande, qui supprime l’abonné à l’événement de la session.

Exemples

Exemple 1 : S’abonner aux événements au démarrage d’un nouveau processus

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 les événements EventArrived . Un objet de requête spécifie que les événements sont des événements de création d’instances 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 d’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 qui $EventArgs sont renseignées 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 en tant que 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 ProcessCreationEvent.ps1 fichier de 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 }

Nous créons d’abord 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 chacun des PSSessions 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 à distance.

La fonction inclut une Register-ObjectEvent commande qui s’abonne aux événements de création d’instance 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 Get-Random de 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 appelons 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 à gérer l’événement. 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 entre accolades ( { } ) pour créer un bloc de script.

La valeur du paramètre Action peut inclure les variables automatiques , , $EventArgs$EventSubscriber$Senderet $Args les $Eventvariables automatiques. 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
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 de l’événement d’un événement, utilisez l’applet Get-Member de commande.

Type:	String
Position:	1
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-Forward

Indique que l’applet de commande envoie des événements pour cet abonnement à une session à distance. Utilisez ce paramètre lorsque vous vous inscrivez aux événements sur un ordinateur distant ou dans une session à distance.

Type:	SwitchParameter
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-MaxTriggerCount

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

Type:	Int32
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 que PowerShell affecte.

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.

Type:	String
Position:	100
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 commande et Unregister-Event des Get-EventSubscriber applets de commande.

Type:	SwitchParameter
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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é.

Partager via

Register-ObjectEvent

Syntaxe

Description

Exemples

Exemple 1 : S’abonner aux événements au démarrage d’un nouveau processus

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

Syntaxe

Description

Exemples

Exemple 1 : S’abonner aux événements au démarrage d’un nouveau processus

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