Register-EngineEvent
Se suscribe a eventos generados por el motor de Windows PowerShell y el cmdlet New-Event.
Syntax
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Description
El cmdlet Register-EngineEvent se suscribe a eventos generados por el motor de Windows PowerShell y el cmdlet New-Event. Use el parámetro SourceIdentifier para especificar el evento.
Puede usar este cmdlet para suscribirse al evento y eventos del motor de salida generados por el cmdlet New-Event. Estos eventos se agregan automáticamente a la cola de eventos de su sesión sin necesidad de suscripción. Sin embargo, la suscripción le permite reenviar los eventos, especificar una acción para responder a los eventos y cancelar la suscripción.
Cuando se genera el evento suscrito, se agrega a la cola de eventos de su sesión. Para obtener los eventos de la cola de eventos, use el cmdlet Get-Event.
Cuando se suscribe a un evento, se agrega un suscriptor de eventos a su 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.
Ejemplos
Ejemplo 1: Registro de un evento de motor de PowerShell en equipos remotos
PS C:\> $S = New-PSSession -ComputerName "Server01, Server02"
PS C:\> Invoke-Command -Session $S { Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward }Este comando se registra para un evento de motor de Windows PowerShell en dos equipos remotos.
El primer comando crea una sesión administrada por el usuario (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 usa el parámetro SourceIdentifier para identificar el evento. El parámetro Forward se utiliza para reenviar los eventos de la sesión remota a la sesión local.
Ejemplo 2: Realizar una acción especificada cuando se produce el evento Exiting
PS C:\> Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}Este comando muestra cómo ejecutar Register-EngineEvent para realizar una acción específica cuando se produce el evento PowerShell.Exiting . El parámetro SupportEvent se agrega para ocultar la suscripción de eventos. Cuando Windows PowerShell sale, en este caso, el historial de comandos de la sesión de salida se exporta en formato XML a un nombre de archivo y ruta de acceso en el directorio $Home del usuario.
Parámetros
-Action
Especifica los comandos para controlar los eventos. Los comandos de 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 $Event, $EventSubscriber, $Sender, $EventArgs y $Args, que proporcionan información sobre el evento al bloque de script de Action. Para obtener más información, consulte about_Automatic_Variables (https://go.microsoft.com/fwlink/?LinkID=113212).
Cuando se especifica una acción, Register-EngineEvent devuelve un objeto de trabajo de evento que representa esa acción. Puede usar los cmdlets de trabajo para administrar el trabajo de evento.
| Type: | ScriptBlock |
| Position: | 101 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Forward
Indica que el cmdlet envía eventos para esta suscripción a la sesión en el equipo local. Utilice este parámetro cuando se registre en eventos de un equipo remoto o de una sesión remota.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaxTriggerCount
Especifica el número máximo de desencadenadores.
El valor del parámetro Action puede incluir las variables $Event, $EventSubscriber, $Sender, $EventArgs y $Args, que proporcionan información sobre el evento al bloque de script de Action. Para obtener más información, consulte about_Automatic_Variables (https://go.microsoft.com/fwlink/?LinkID=113212).
Cuando se especifica una acción, Register-EngineEvent devuelve un objeto de trabajo de evento que representa esa acción. Puede usar los cmdlets de trabajo para administrar el trabajo de evento.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MessageData
Especifica información adicional asociada al evento. El valor de este parámetro aparece en la propiedad MessageData del objeto de evento.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SourceIdentifier
Especifica el identificador de origen del evento al que se suscribe. 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.
Los valores de EngineEvent admitidos incluyen PowerShell.Exiting, PowerShell.OnIdle y PowerShell.OnScriptBlockInvoke.
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SupportEvent
Indica que el cmdlet oculta la suscripción de eventos. Agregue 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ó con el parámetro SupportEvent , agregue el parámetro Force a los cmdlets Get-EventSubscriber o Unregister-Event.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Entradas
None
No se pueden canalizar entradas a Register-EngineEvent.
Salidas
None or System.Management.Automation.PSEventJob
Si se utiliza el parámetro Action, Register-EngineEvent devuelve un objeto System.Management.Automation.PSEventJob. De lo contrario, este cmdlet no genera resultados de ningún tipo.
Notas
La cola de eventos, las suscripciones de eventos y los eventos solo existen en la sesión actual. Si la cierra, la cola de eventos se descartará y la suscripción al evento se cancelará.