Realiza la suscripción a un evento de Instrumental de administración de Windows (WMI).

Sintaxis

Register-WmiEvent [-Class] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Register-WmiEvent [-Query] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Descripción

El cmdlet Register-WmiEvent suscribe para eventos de WMI en el equipo local o en un equipo remoto.

Cuando se genera el evento de WMI suscrito, se agrega a la cola de eventos en la sesión local, aunque el evento se produzca en un equipo remoto. Para obtener eventos de la cola de eventos, utilice el cmdlet Get-Event.

Puede utilizar los parámetros de Register-WmiEvent para la suscripción a eventos en equipos remotos y para especificar los 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 se han de llevar a cabo cuando se provoca un evento suscrito.

Cuando se realiza la suscripción a un evento, se agrega un suscriptor de eventos a la sesión. Para obtener los suscriptores de eventos en 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 que controlan los eventos. Los comandos del parámetro Action se ejecutan cuando se genera 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-WmiEvent devuelve un objeto de trabajo de evento que representa esa acción. Puede utilizar los cmdlets que contienen el sustantivo Job (cmdlets Job) para administrar el trabajo de evento.

¿Requerido?

false

¿Posición?

102

Valor predeterminado

The event is added to the event queue.

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Class <string>

Especifica el evento al que se está suscribiendo. Escriba la clase de WMI que genera los eventos. Se requiere un parámetro Class o Query en cada comando.

¿Requerido?

true

¿Posición?

1

Valor predeterminado

ninguno

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-ComputerName <string>

Especifica un equipo remoto. El valor predeterminado es el equipo local. Escriba un nombre NetBIOS, una dirección IP o un nombre de dominio completo.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

Local computer

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Credential <PSCredential>

Especifica una cuenta de usuario con permiso para realizar esta acción. Escriba un nombre de usuario, como "Usuario01" o "Dominio01\Usuario01". O bien, escriba un objeto PSCredential, como el devuelto por el cmdlet Get-Credential. Si escribe un nombre de usuario se le pedirá una contraseña.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

The credentials of the current user

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Forward

Envía los eventos de esta suscripción a la sesión en el equipo local. 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

¿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

None. The MessageData property is NULL.

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Namespace <string>

Especifica el espacio de nombres de la clase de WMI.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

ninguno

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Query <string>

Especifica una consulta en lenguaje de consulta de WMI (WQL) que identifica la clase de eventos de WMI, como "select * from __InstanceDeletionEvent".

¿Requerido?

true

¿Posición?

1

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

-Timeout <Int64>

Determina el tiempo que Windows PowerShell espera para que este comando se complete.

El valor predeterminado, 0 (cero), significa que no hay tiempo de espera, y hace que Windows PowerShell espere de forma indefinida.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

0

¿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-WmiEvent.

Salidas

Ninguno

Este cmdlet no genera resultados.

Notas

Para usar este cmdlet en Windows Vista o en una versión posterior de Windows, inicie Windows PowerShell con la opción "Ejecutar como administrador".

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>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted"

Descripción
-----------
Este comando suscribe para los eventos generados por la clase Win32_ProcessStartTrace. Esta clase provoca un evento cada vez que se inicia un proceso.






Ejemplo 2

C:\PS>register-wmiEvent -query "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'" -sourceIdentifier "WMIProcess" -messageData "Test 01" -timeout 500

Descripción
-----------
Este comando utiliza una consulta para la suscripción a eventos de creación de instancia de Win32_process.






Ejemplo 3

C:\PS>$action = { get-history | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }

C:\PS> register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted" -action $action

Id    Name            State      HasMoreData   Location  Command
--    ----            -----      -----------   --------  -------
1     ProcessStarted  NotStarted False                   get-history | where {...

Descripción
-----------
En este ejemplo se muestra cómo se utiliza una acción para responder a un evento. En este caso, cuando se inicia un proceso, los comandos Start-Process en la sesión actual se escriben en un archivo XML. 

Cuando se utiliza el parámetro Action, Register-WmiEvent devuelve un trabajo en segundo plano que representa la acción de evento. Se pueden utilizar los cmdlets Job, como Get-Job y Receive-Job, para administrar el trabajo de evento.

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






Ejemplo 4

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "Start" -computername Server01 

C:\PS> get-event -sourceIdentifier "Start"

Descripción
-----------
En este ejemplo se registran eventos en el equipo remoto Server01. 

WMI devuelve los eventos al equipo local y los almacena en la cola de eventos en la sesión actual. Para recuperar los eventos, ejecute un comando Get-Event local.






Vea también




Tabla de contenido