Realiza la suscripción a los eventos generados por un objeto de Microsoft .NET Framework.

Sintaxis

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

Descripción

El cmdlet Register-ObjectEvent realiza la suscripción a los eventos generados por los objetos de .NET Framework en el equipo local o en un equipo remoto.

Cuando se genera el evento objeto de la suscripción, dicho evento se agrega a la cola de eventos de la sesión. Para obtener eventos de la cola de eventos, utilice el cmdlet Get-Event.

Puede utilizar los parámetros de Register-ObjectEvent para especificar valores de propiedad de los eventos que pueden ayudar a identificar el evento en la cola. También puede utilizar el parámetro Action para especificar las acciones que deben realizarse cuando se genera un evento al que se ha suscrito así como el parámetro Forward para enviar los eventos remotos a la cola de eventos en la sesión local.

Al suscribirse a un evento, se agrega un suscriptor de eventos a la sesión. Para obtener los suscriptores de eventos de la sesión, utilice el cmdlet Get-EventSubscriber. Para cancelar la suscripción, utilice el cmdlet Unregister-Event, que elimina el suscriptor de eventos de la sesión.

Parámetros

-Action <scriptblock>

Especifica comandos para controlar los eventos. Los comandos del parámetro Action se ejecutan cuando se provoca un evento, en lugar de enviar el evento a la cola de eventos. Incluya los comandos entre llaves ({ }) para crear un bloque de script.

El valor del parámetro Action puede incluir las variables automáticas $Event, $EventSubscriber, $Sender, $SourceEventArgs y $SourceArgs, que proporcionan información acerca del evento al bloque de script Action. Para obtener más información, vea about_Automatic_Variables.

Cuando se especifica una acción, Register-ObjectEvent devuelve un objeto de trabajo de evento que representa esa acción. Puede usar los cmdlets Job para administrar el trabajo de evento.

¿Requerido?

false

¿Posición?

102

Valor predeterminado

None.

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-EventName <string>

Especifica el evento al que se está suscribiendo. Escriba el nombre del evento. Este parámetro es obligatorio.

El valor de este parámetro no es un nombre que seleccione para la suscripción de eventos. Es el nombre de un evento que el objeto de .NET Framework expone. Por ejemplo, la clase ManagementEventWatcher tiene los eventos denominados "EventArrived" y "Stopped". Para obtener el nombre de un evento, utilice el cmdlet Get-Member.

¿Requerido?

true

¿Posición?

2

Valor predeterminado

ninguno

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Forward

Envía los eventos de esta suscripción a una sesión remota. Use este parámetro si se registra para eventos en un equipo remoto o en una sesión remota.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

False

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-InputObject <psobject>

Especifica el objeto de .NET Framework que genera los eventos. Especifique la variable que contiene el objeto o escriba un comando o una expresión que lo obtenga. Este parámetro es obligatorio.

¿Requerido?

true

¿Posición?

1

Valor predeterminado

ninguno

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-MessageData <psobject>

Especifica los datos adicionales que se van a asociar a esta suscripción de eventos. El valor de este parámetro aparece en la propiedad MessageData de todos los eventos asociados a esta suscripción.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

ninguno

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-SourceIdentifier <string>

Especifica un nombre que se selecciona para la suscripción. El nombre que se seleccione debe ser único en la sesión actual. El valor predeterminado es el GUID asignado por Windows PowerShell.

El valor de este parámetro aparece en el valor de la propiedad SourceIdentifier del objeto de suscriptor y de todos los objetos de evento asociados a esta suscripción.

¿Requerido?

false

¿Posición?

101

Valor predeterminado

GUID

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-SupportEvent

Oculta la suscripción de eventos. Use este parámetro si la suscripción actual forma parte de un mecanismo de registro de eventos más complejo y no debe detectarse de manera independiente.

Para ver o cancelar una suscripción creada con el parámetro SupportEvent, use el parámetro Force de los cmdlets Get-EventSubscriber y Unregister-Event.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

False

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

<CommonParameters>

Este cmdlet admite los parámetros comunes: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer y -OutVariable. Para obtener más información, vea about_Commonparameters.

Entradas y salidas

El tipo de entrada es el tipo de los objetos que se pueden canalizar al cmdlet. El tipo devuelto es el tipo de los objetos que el cmdlet devuelve.

Entradas

Ninguno

No se pueden canalizar objetos a Register-ObjectEvent.

Salidas

Ninguno

Este cmdlet no genera resultados.

Notas

Los eventos, las suscripciones de eventos y la cola de eventos solo existen en la sesión actual. Si cierra la sesión actual, se descartará la cola de eventos y se cancelará la suscripción de eventos.

Ejemplo 1

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.






Ejemplo 2

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.






Ejemplo 3

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.






Ejemplo 4

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.






Vea también




Tabla de contenido