Register-ObjectEvent

Register-ObjectEvent [-InputObject] <psobject> [-EventName] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]

C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" 

C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query 

C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived"

Descripción
-----------
En este ejemplo se realiza la suscripción a los eventos que se generan cuando se inicia un nuevo proceso. 

El comando utiliza el objeto ManagementEventWatcher para obtener los eventos EventArrived. Un objeto de consulta especifica que los eventos son eventos de creación de instancia de la clase Win32_Process.

C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" 

C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query 

C:\PS> $action = { New-Event "PowerShell.ProcessCreated" -Sender $sender -EventArguments $SourceEventArgs.NewEvent.TargetInstance } 

C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived" -action $action

Id    Name            State      HasMoreData     Location             Command
--    ----            -----      -----------     --------             -------
2     422cfe5a-65e... Running    True                                 New-Event "PowerShe...

Descripción
-----------
En este ejemplo se muestra cómo especificar una acción para responder a un evento. Cuando se especifica una acción, los eventos que se provocan no se agregan a la cola de eventos sino que la acción responde al evento. 

En este ejemplo, cuando se genera un evento de creación de instancia que indica que se inicia un nuevo proceso, se genera un nuevo evento ProcessCreated.

La acción usa las variables automáticas $Sender y $SourceEventArgs, que se rellenan únicamente para las acciones de evento. 

El comando Register-ObjectEvent devuelve un objeto de trabajo que representa la acción, que se ejecuta como un trabajo en segundo plano. Se pueden utilizar los cmdlets Job, como Get-Job y Receive-Job, para administrar el trabajo en segundo plano. 

Para obtener más información, vea about_Jobs.

C:\PS>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s -filepath ProcessCreationEvent.ps1

C:\PS> invoke-command -session $s { get-event }

# ProcessCreationEvent.ps1

function Enable-ProcessCreationEvent 
{ 
   $query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", ` 
       (New-Object TimeSpan 0,0,1), ` 
       "TargetInstance isa 'Win32_Process'" 
   $processWatcher = New-Object System.Management.ManagementEventWatcher $query 

   $identifier = "WMI.ProcessCreated" 
   Register-ObjectEvent -input $processWatcher -eventName "EventArrived" `
      -sourceIdentifier $identifier -messageData "Test" -forward 
   } 
} 

EnableProcessCreationEvent

Descripción
-----------
En este ejemplo se muestra cómo suscribirse a los eventos de objeto en equipos remotos.

El primer comando crea PSSessions en dos equipos remotos y las almacena en la variable $s.

El segundo comando usa el parámetro FilePath del cmdlet Invoke-Command para ejecutar el script ProcessCreationEvent.ps1 en cada una de las sesiones PSSession almacenadas en $s. 

El script incluye un comando Register-ObjectEvent que realiza la suscripción a los eventos de creación de instancia en el objeto Win32_Process a través del objeto ManagementEventWatcher y su evento EventArrived.

C:\PS>$timer  = New-Object Timers.Timer

C:\PS> $timer.Interval = 500

C:\PS> $job = Register-ObjectEvent -inputObject $timer -eventName Elapsed -sourceIdentifier Timer.Random -Action {$random = Get-Random -Min 0 -Max 100}

C:\PS> $job.gettype().fullname
System.Management.Automation.PSEventJob

C:\PS> $job | format-list -property *

State         : Running
Module        : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0
StatusMessage :
HasMoreData   : True
Location      :
Command       : $random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 88944290-133d-4b44-8752-f901bd8012e2
Id            : 1
Name          : Timer.Random
ChildJobs     : {}
...

C:\PS> $timer.Enabled = $true

C:\PS> & $job.module {$random}
60

C:\PS> & $job.module {$random}
47

Descripción
-----------
En este ejemplo, se muestra cómo utilizar el módulo dinámico en el objeto PSEventJob que se crea cuando se incluye una acción en el registro de eventos.

El primer comando utiliza el cmdlet New-Object para crear un objeto de temporizador. El segundo comando establece el intervalo del temporizador en 500 (milisegundos).

El tercer comando usa el cmdlet Register-ObjectEvent para registrar el evento Elapsed del objeto de temporizador. El comando incluye una acción que controla el evento. Una vez transcurrido el intervalo del temporizador, se provoca un evento y se ejecutan los comandos de la acción. En este caso, el cmdlet Get-Random genera un número aleatorio comprendido entre 0 y 100 y lo guarda en la variable $random.

Cuando se usa el parámetro Action en un comando Register-ObjectEvent, el comando devuelve un objeto PSEventJob que representa la acción. El comando guarda el objeto de trabajo en la variable $job.

El objeto PSEventJob devuelto por el cmdlet Register-ObjectEvent también está disponible en la propiedad Action del suscriptor de eventos. Para obtener más información, vea Get-EventSubscriber.

El cuarto comando muestra que la variable $job contiene un objeto PSEventJob. El quinto comando utiliza el cmdlet Format-List para mostrar en una lista todas las propiedades del objeto PSEventJob. 

El objeto PSEventJob tiene una propiedad Module que contiene un módulo de script dinámico que implementa la acción.

El sexto comando habilita el temporizador.

Los comandos restantes utilizan el operador de llamada (&) para invocar el comando del módulo y mostrar el valor de la variable $random. El operador de llamada se puede usar para invocar cualquier comando de un módulo, incluidos los comandos no exportados. En este caso, los comandos muestran el número aleatorio que se genera cuando se produce el evento Elapsed.

Para obtener más información sobre los módulos, vea about_Modules.