Register-ObjectEvent
S’abonne aux événements générés par un objet Microsoft .NET Framework.
Syntaxe
Default (Par défaut)
Register-ObjectEvent
[-InputObject] <PSObject>
[-EventName] <String>
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Description
L’applet de commande Register-ObjectEvent s’abonne aux événements générés par des objets .NET sur l’ordinateur local ou sur un ordinateur distant.
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.
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 à entreprendre lorsqu’un événement abonné est déclenché et le paramètre Transférer 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é à 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.
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 recevoir des événements EventArrived. Un objet de requête spécifie que les événements sont des événements de création d’instance 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 d’événements. Au lieu de cela, 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 et $EventArgs variables automatiques qui sont remplies uniquement pour les actions d’événement.
La commande Register-ObjectEvent 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 aux événements d’objet sur des ordinateurs distants
Cet exemple montre comment s’abonner à des événements d’objet sur des ordinateurs distants. Cet exemple utilise la fonction Enable-ProcessCreationEvent définie dans le fichier de script ProcessCreationEvent.ps1. 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 }
Tout d'abord, nous créons PSSessions sur deux ordinateurs distants et les enregistrons dans la variable $S. Ensuite, le cmdlet Invoke-Command exécute le script ProcessCreationEvent.ps1 dans chacune des PSSessions dans $S. Cette action crée la fonction Enable-ProcessCreationEvent dans les sessions distantes.
Enfin, nous exécutons la fonction Enable-ProcessCreationEvent dans les sessions à distance.
La fonction inclut une commande Register-ObjectEvent 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 un Action dans une inscription d’événement. Tout d’abord, nous créons et activez un objet minuteur, puis définissez l’intervalle du minuteur sur 500 (millisecondes). La cmdlet Register-ObjectEvent enregistre l’événement Elapsed de l’objet timer. L’objet PSEventJob est enregistré dans la variable $Job et est également disponible dans la propriété Action de l’abonné à l’événement. Pour plus d’informations, veuillez consulter la section 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 commande Get-Random génère un nombre aléatoire compris entre 0 et 100 et l’enregistre dans la variable $Random.
$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
Le PSEventJob possède une propriété Module qui contient un module de script dynamique implémentant l’action. À l’aide de l’opérateur d’appel (&), nous appelons la commande dans le module pour afficher la valeur de la variable $Random.
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 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 de
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.
Propriétés du paramètre
| Type: | ScriptBlock |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | 101 |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | 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 possède des événements nommés EventArrived et Stopped. Pour rechercher le nom d’événement d’un événement, utilisez l’applet de commande Get-Member.
Propriétés du paramètre
| Type: | String |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | 1 |
| Obligatoire: | True |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-Forward
Indique que l’applet de commande envoie des événements pour cet abonnement vers une session distante. Utilisez ce paramètre lorsque vous inscrivez des événements sur un ordinateur distant ou dans une session à distance.
Propriétés du paramètre
| Type: | SwitchParameter |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-InputObject
Spécifie l’objet .NET qui génère les événements. Entrez une variable qui contient l’objet, ou tapez une commande ou une expression qui obtient l’objet.
Propriétés du paramètre
| Type: | PSObject |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | 0 |
| Obligatoire: | True |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-MaxTriggerCount
Spécifie le nombre maximal de fois où un événement peut être déclenché.
Propriétés du paramètre
| Type: | Int32 |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-MessageData
Spécifie toutes les données supplémentaires à associer à cet abonnement d’événements. La valeur de ce paramètre apparaît dans la propriété MessageData de tous les événements associés à cet abonnement.
Propriétés du paramètre
| Type: | PSObject |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | 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 attribue.
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.
Propriétés du paramètre
| Type: | String |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | 100 |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | 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 Get-EventSubscriber et Unregister-Event.
Propriétés du paramètre
| Type: | SwitchParameter |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
CommonParameters
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.
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
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 la session active, la file d’attente d’événements est ignorée et l’abonnement à l’événement est annulé.