Realiza la suscripción a los eventos generados por el motor de Windows PowerShell y el cmdlet New-Event.
Sintaxis
Register-EngineEvent [-SourceIdentifier] <string> [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]
Descripción
El cmdlet Register-EngineEvent realiza la suscripción a los eventos generados por el motor de Windows PowerShell y el cmdlet New-Event. Use el parámetro SourceIdentifier para especificar el evento.
Este cmdlet puede usarse para suscribirse al evento "Exiting" del motor y a los eventos generados por el cmdlet New-Event. Estos eventos se agregan automáticamente a la cola de eventos de la sesión sin que sea necesario suscribirse. Sin embargo, la suscripción permite reenviar los eventos, especificar una acción para responder a los eventos y cancelar la suscripción.
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.
Al suscribir para 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-EngineEvent 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 |
ninguno |
|
¿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 |
False |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-MessageData <psobject>
Especifica datos adicionales que están asociados al evento. El valor de este parámetro aparece en la propiedad MessageData del objeto de evento.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
ninguno |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-SourceIdentifier <string>
Especifica el identificador de origen del evento objeto de la suscripción. El identificador de origen debe ser único en la sesión actual. Este parámetro es obligatorio.
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? |
true |
|
¿Posición? |
101 |
|
Valor predeterminado |
|
|
¿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 entradas a Register-EngineEvent. |
|
Salidas |
Ninguno o System.Management.Automation.PSEventJob Si se usa el parámetro Action, Register-EngineEvent devuelve un objeto System.Management.Automation.PSEventJob. De lo contrario, 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>$s = new-pssession -computername Server01, Server02
C:\PS> invoke-command -session $s { Register-EngineEvent -sourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -forward }
Descripción
-----------
Este comando realiza el registro para un evento del motor de Windows PowerShell en dos equipos remotos.
El primer comando crea una PSSession en cada uno de los equipos remotos.
El segundo comando usa el cmdlet Invoke-Command para ejecutar el comando Register-EngineEvent en las sesiones remotas.
El comando Register-EngineEvent utiliza el parámetro SourceIdentifier para identificar el evento. Utiliza el parámetro Forward para reenviar los eventos de la sesión remota a la sesión local.
Ejemplo 2
C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated -action { $processName | add-content processLog.txt }
C:\PS> get-event
C:\PS> $results = $j | receive-job
C:\PS> unregister-event PowerShell.ProcessCreated
Descripción
-----------
Este comando muestra cómo utilizar los cmdlets Job para administrar el objeto de trabajo de evento que Register-EngineEvent devuelve cuando se usa el parámetro Action.
Un trabajo de evento se administra de la misma manera que cualquier otro trabajo de Windows PowerShell. Para obtener más información, vea about_jobs. En este ejemplo, se utiliza el cmdlet Receive-Job para obtener los resultados del trabajo.
Para eliminar el trabajo de la sesión, utilice Remove-Job. Para cancelar la suscripción de eventos, utilice el cmdlet Unregister-Event. Para eliminar los eventos de la cola de eventos, utilice Remove-Event.
Vea también