Register-EngineEvent
Se suscribe a eventos generados por el motor de PowerShell y por el cmdlet New-Event.
Sintaxis
Default (Es el valor predeterminado).
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 PowerShell y el cmdlet New-Event. Use el parámetro SourceIdentifier para especificar el evento.
Puede usar este cmdlet para suscribirse a los eventos del motor OnIdle o Exiting, así como 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 suscribirse. 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 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.
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.
Ejemplos
Ejemplo 1: Registro de un evento de motor de PowerShell en equipos remotos
En este ejemplo se registra un evento de motor de PowerShell en dos equipos remotos.
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PSEngineEvent]::Exiting) -Forward
}
New-PSSession crea una sesión administrada por el usuario (PSSession) en cada uno de los equipos remotos. El cmdlet Invoke-Command ejecuta el comando Register-EngineEvent en las sesiones remotas.
Register-EngineEvent usa el parámetro SourceIdentifier para identificar el evento. El parámetro Forward indica al motor que reenvíe 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
En este ejemplo se muestra cómo ejecutar Register-EngineEvent para realizar una acción específica cuando se produce el evento PowerShell.Exiting.
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $HOME\history.clixml
}
El parámetro SupportEvent se agrega para ocultar la suscripción de eventos. Cuando se cierra PowerShell, en este caso, el historial de comandos de la sesión que se cierra se exporta a un archivo XML en el directorio $HOME del usuario.
Ejemplo 3: Creación y suscripción a un evento definido por el usuario
En este ejemplo se crea una suscripción para eventos del origen MyEventSource. Se trata de un origen arbitrario que vamos a usar para supervisar el progreso de un trabajo.
Register-EngineEvent se usa para crear la suscripción. El bloque de script del parámetro de acción registra los datos del evento en un archivo de texto.
Register-EngineEvent -SourceIdentifier MyEventSource -Action {
"Event: {0}" -f $Event.MessageData | Out-File C:\temp\MyEvents.txt -Append
}
Start-Job -Name TestJob -ScriptBlock {
while ($true) {
Register-EngineEvent -SourceIdentifier MyEventSource -Forward
Start-Sleep -Seconds 2
"Doing some work..."
$newEventSplat = @{
SourceIdentifier = 'MyEventSource'
MessageData = ("{0} - Work done..." -f (Get-Date))
}
New-Event @newEventSplat
}
}
Start-Sleep -Seconds 4
Get-EventSubscriber
Get-Job
SubscriptionId : 12
SourceObject :
EventName :
SourceIdentifier : MyEventSource
Action : System.Management.Automation.PSEventJob
HandlerDelegate :
SupportEvent : False
ForwardEvent : False
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Running True …
19 TestJob BackgroundJob Running True localhost …
Register-EngineEvent creó el Id. de trabajo 18.
Start-Job creó ID de trabajo 19. En el ejemplo 4, se quita la suscripción de eventos y los trabajos y, a continuación, se inspecciona el archivo de registro.
Ejemplo 4: Desregistrar eventos y limpiar tareas
Esta es una continuación del ejemplo 3. En este ejemplo esperamos 10 segundos para permitir que se produzcan varios eventos. A continuación, anulamos el registro de la suscripción de eventos.
PS> Start-Sleep -Seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Stopped False …
19 TestJob BackgroundJob Running True localhost …
PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM - Work done...
Event: 2/18/2020 2:36:21 PM - Work done...
Event: 2/18/2020 2:36:23 PM - Work done...
Event: 2/18/2020 2:36:25 PM - Work done...
Event: 2/18/2020 2:36:27 PM - Work done...
Event: 2/18/2020 2:36:29 PM - Work done...
Event: 2/18/2020 2:36:31 PM - Work done...
El cmdlet Unregister-Event detiene el trabajo asociado a la suscripción de eventos (id. de trabajo 18). El ID de trabajo 19 sigue en ejecución y creando nuevos eventos. Para detener el trabajo y eliminar los objetos de trabajo innecesarios, usamos los cmdlets Job.
Get-Content muestra el contenido del archivo de registro.
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 Acción de
Al especificar 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.
Propiedades del parámetro
| Tipo: | ScriptBlock |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | 101 |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-Forward
Indica que el cmdlet envía eventos de esta suscripción a la sesión en este equipo local. Use este parámetro cuando se registren eventos en un equipo remoto o en una sesión remota.
Propiedades del parámetro
| Tipo: | SwitchParameter |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-MaxTriggerCount
Especifica el número máximo de veces que se ejecuta la acción para la suscripción de eventos.
Propiedades del parámetro
| Tipo: | Int32 |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-MessageData
Este parámetro forma parte de la clase base para todos los cmdlets de Event. El Register-EngineEvent no usa este parámetro. Los datos pasados a este parámetro se omiten.
Propiedades del parámetro
| Tipo: | PSObject |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-SourceIdentifier
Especifica el identificador de origen del evento al que se está suscribiendo. 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.
El valor es específico del origen del evento. Puede ser un valor arbitrario que creó para usarlo con el cmdlet New-Event. El motor de PowerShell admite los valores PSEngineEvent, PowerShell.Exiting, y PowerShell.OnIdle.
Propiedades del parámetro
| Tipo: | String |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | 100 |
| Mandatory: | True |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | 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.
Propiedades del parámetro
| Tipo: | SwitchParameter |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
CommonParameters
Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.
Entradas
None
No se pueden canalizar objetos a este cmdlet.
Salidas
None
De forma predeterminada, este cmdlet no devuelve ninguna salida.
PSEventJob
Cuando se usa el parámetro
Notas
Los eventos, las suscripciones de eventos y la cola de eventos solo existen en la sesión actual. Si se cierra la sesión actual, se descarta la fila de eventos y se cancela la suscripción al evento.
Al suscribirse al evento Exiting, los cmdlets que puede ejecutar el parámetro Action se limitan a los cmdlets de los módulos Microsoft.PowerShell.Core y Microsoft.PowerShell.Utility. El evento Exiting solo se activa cuando se sale de la sesión bajo el control de PowerShell. El evento no se desencadena cuando se cierra la aplicación host o la ventana de terminal.
El motor se considera inactivo si no ejecuta una canalización. El evento OnIdle se desencadena cuando PowerShell está inactivo durante 300 milisegundos (ms).
Nota:
Cuando PSReadLine está en uso, el evento OnIdle se desencadena cuando ReadKey() agota el tiempo de espera (sin escribir en 300 ms). El evento podría indicarse mientras el usuario está en medio de la edición de una línea de comandos, por ejemplo, el usuario está leyendo ayuda para decidir qué parámetro usar. A partir de PSReadLine 2.2.0-beta4, el comportamiento de OnIdle cambió para indicar el evento solo si hay un tiempo de espera de ReadKey() y el búfer de edición actual está vacío.
