Register-EngineEvent

  • Referencia
Módulo:
Microsoft.PowerShell.Utility

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 $Eventvariables 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.

PSEventJob

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.