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