Register-EngineEvent
Se suscribe a eventos generados por el motor de PowerShell y por el New-Event
cmdlet .
Syntax
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Description
El Register-EngineEvent
cmdlet se suscribe a eventos generados por el motor de PowerShell y el New-Event
cmdlet . Use el parámetro SourceIdentifier para especificar el evento.
Puede usar este cmdlet para suscribirse a los eventos y eventos del motor OnIdle o Exiting generados por el New-Event
cmdlet . 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 su sesión. Para obtener los suscriptores de eventos en la sesión, use el Get-EventSubscriber
cmdlet . Para cancelar la suscripción, use el Unregister-Event
cmdlet , 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 eventos en la cola de eventos, use el Get-Event
cmdlet .
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 Invoke-Command
cmdlet ejecuta el Register-EngineEvent
comando 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 de salida se exporta un archivo XML en el directorio del $HOME
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 desde el 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 Action 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..."
New-Event -SourceIdentifier MyEventSource -Message ("{0} - Work done..." -f (Get-Date))
}
}
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ó el 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: Anular el registro de eventos y limpiar trabajos
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 Unregister-Event
cmdlet detiene el trabajo asociado a la suscripción de eventos (id. de trabajo 18). El id. de trabajo 19 todavía se está ejecutando y creando nuevos eventos. Usamos los cmdlets job para detener el trabajo y quitar los objetos de trabajo innecesarios. Get-Content
muestra el contenido del archivo de registro.
Parámetros
-Action
Especifica los comandos para controlar los eventos. Los comandos de la acción 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 $Event
variables automáticas , $EventSubscriber
, $Sender
, $EventArgs
, y $Args
, que proporcionan información sobre el evento al bloque actionscript. 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 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 veces que se ejecuta la acción para la suscripción de eventos.
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 subscriber 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 New-Event
cmdlet . El motor de PowerShell admite los valores de PSEngineEvent PowerShell.Exiting y PowerShell.OnIdle.
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 Get-EventSubscriber
cmdlets 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 objetos a este cmdlet.
Salidas
None
De forma predeterminada, este cmdlet no devuelve ninguna salida.
Cuando se usa el parámetro Action , este cmdlet devuelve un objeto PSEventJob .
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á.
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 desencadena 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 ha estado inactivo durante 300 milisegundos (ms).
Nota:
Cuando PSReadLine está en uso, el evento OnIdle se desencadena cuando ReadKey()
se 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 ReadKey()
tiempo de espera y el búfer de edición actual está vacío.