Register-WmiEvent

Módulo:

Microsoft.PowerShell.Management

Se suscribe a un evento de Instrumental de administración de Windows (WMI).

Sintaxis

Register-WmiEvent
        [-Namespace <String>]
        [-Credential <PSCredential>]
        [-ComputerName <String>]
        [-Class] <String>
        [-Timeout <Int64>]
        [[-SourceIdentifier] <String>]
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

Register-WmiEvent
        [-Namespace <String>]
        [-Credential <PSCredential>]
        [-ComputerName <String>]
        [-Query] <String>
        [-Timeout <Int64>]
        [[-SourceIdentifier] <String>]
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

Description

El cmdlet Register-WmiEvent se suscribe a eventos de Instrumental de administración de Windows (WMI) en el equipo local o en un equipo remoto.

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

Puede usar los parámetros de Register-WmiEvent para suscribirse a eventos en equipos remotos y especificar los valores de propiedad de los eventos que pueden ayudarle a identificar el evento en la cola. También puede usar el parámetro Action para especificar las acciones que se deben realizar cuando se genera un evento suscrito.

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

Los nuevos cmdlets de Common Information Model (CIM), introducidos en Windows PowerShell 3.0, realizan las mismas tareas que los cmdlets de WMI. Los cmdlets CIM cumplen con los estándares WS-Management (WSMan) y con el estándar CIM, lo que permite a los cmdlets usar las mismas técnicas para administrar equipos que ejecutan el sistema operativo Windows y los que ejecutan otros sistemas operativos. En lugar de usar , considere la posibilidad de usar el cmdlet Register-CimIndicationEvent .

Ejemplos

Ejemplo 1: Suscribirse a eventos generados por una clase

PS C:\> Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "ProcessStarted"

Este comando se suscribe a los eventos generados por la clase Win32_ProcessStartTrace. Esta clase genera un evento cada vez que se inicia un proceso.

Ejemplo 2: Suscribirse a eventos de creación para un proceso

PS C:\> Register-WmiEvent -Query "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'" -SourceIdentifier "WMIProcess" -MessageData "Test 01" -TimeOut 500

Este comando usa una consulta para suscribirse a Win32_process eventos de creación de instancias.

Ejemplo 3: Usar una acción para responder a un evento

PS C:\> $action = { Get-History | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }
PS C:\> Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "ProcessStarted" -Action $action
Id    Name            State      HasMoreData   Location  Command
--    ----            -----      -----------   --------  -------
1     ProcessStarted  NotStarted False                   get-history | where {...

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

Cuando se usa el parámetro Action de , Register-WmiEvent devuelve un trabajo en segundo plano que representa la acción del evento. Puede usar los cmdlets job de , como Get-Job y Receive-Job, para administrar el trabajo de evento.

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

Ejemplo 4: Registro de eventos en un equipo remoto

PS C:\> Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "Start" -Computername Server01
PS C:\> Get-Event -SourceIdentifier "Start"

En este ejemplo se registra para eventos en el equipo remoto Server01.

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

Parámetros

-Action

Especifica los 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 de Action puede incluir las variables automáticas $Event, $EventSubscriber, $Sender, $EventArgs y $Args automáticas, que proporcionan información sobre el evento al bloque de script action de . Para obtener más información, consulte about_Automatic_Variables.

Al especificar una acción, Register-WmiEvent devuelve un objeto de trabajo de evento que representa esa acción. Puede usar los cmdlets que contienen el nombre de Job (los cmdlets job de ) para administrar el trabajo de evento.

Tipo:	ScriptBlock
Posición:	101
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-Class

Especifica el evento al que se va a suscribir. Escriba la clase WMI que genera los eventos. Se requiere un parámetro o Query en cada comando.

Tipo:	String
Posición:	0
Valor predeterminado:	None
Requerido:	True
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-ComputerName

Especifica el nombre del equipo en el que se ejecuta el comando. El valor predeterminado es el equipo local.

Escriba el nombre NetBIOS, una dirección IP o un nombre de dominio completo del equipo. Para especificar el equipo local, escriba el nombre del equipo, un punto (.) o localhost.

Este parámetro no se basa en la comunicación remota de Windows PowerShell. Puede usar el parámetro ComputerName incluso si el equipo no está configurado para ejecutar comandos remotos.

Tipo:	String
Alias:	Cn
Posición:	Named
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-Credential

Especifica una cuenta de usuario que tiene permiso para realizar esta acción. El valor predeterminado es el usuario actual.

Escriba un nombre de usuario, como User01 o Domain01\User01, o escriba un objeto de PSCredential, como uno generado por el cmdlet Get-Credential. Si escribe un nombre de usuario, este cmdlet le pedirá una contraseña.

Tipo:	PSCredential
Posición:	Named
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-Forward

Indica que este cmdlet envía eventos para esta suscripción a la sesión en el equipo local. Use este parámetro cuando se registren eventos en un equipo remoto o en una sesión remota.

Tipo:	SwitchParameter
Posición:	Named
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-MaxTriggerCount

Especifica el número máximo de desencadenadores.

Tipo:	Int32
Posición:	Named
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-MessageData

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.

Tipo:	PSObject
Posición:	Named
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-Namespace

Especifica el espacio de nombres de la clase WMI.

Tipo:	String
Alias:	NS
Posición:	Named
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-Query

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

Tipo:	String
Posición:	0
Valor predeterminado:	None
Requerido:	True
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-SourceIdentifier

Especifica un nombre que seleccione para la suscripción. El nombre que seleccione debe ser único en la sesión actual. El valor predeterminado es el GUID que asigna 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.

Tipo:	String
Posición:	100
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-SupportEvent

Indica que este cmdlet oculta la suscripción de eventos. Use este parámetro cuando la suscripción actual forme parte de un mecanismo de registro de eventos más complejo y no se debe detectar de forma independiente.

Para ver o cancelar una suscripción que se creó mediante el parámetro supportEvent de , especifique el parámetro Force de los cmdlets Get-EventSubscriber y Unregister-Event.

Tipo:	SwitchParameter
Posición:	Named
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

-Timeout

Especifica cuánto tiempo espera Windows PowerShell a que finalice este comando.

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

Tipo:	Int64
Alias:	TimeoutMSec
Posición:	Named
Valor predeterminado:	None
Requerido:	False
Aceptar entrada de canalización:	False
Aceptar caracteres comodín:	False

Entradas

None

No se pueden canalizar objetos a este cmdlet.

Salidas

None

Este cmdlet no genera ninguna salida.

Notas

• Para usar este cmdlet en Windows Vista o una versión posterior del sistema operativo Windows, inicie Windows PowerShell mediante 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 descarta la cola de eventos y se cancela la suscripción de eventos.