Register-ObjectEvent

  • Referencia
Módulo:
Microsoft.PowerShell.Utility

Se suscribe a los eventos generados por un objeto de Microsoft .NET Framework.

Syntax

Register-ObjectEvent
        [-InputObject] <PSObject>
        [-EventName] <String>
        [[-SourceIdentifier] <String>]
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

Description

El Register-ObjectEvent cmdlet se suscribe a eventos generados por objetos .NET en el equipo local o en un equipo remoto.

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 .

Puede usar los parámetros de Register-ObjectEvent para especificar los valores de propiedad de los eventos que pueden ayudarle a identificar el evento en la cola. También puede usar el parámetro Action para especificar las acciones que se deben realizar cuando se genera un evento suscrito y el parámetro Forward para enviar eventos remotos a la cola de eventos en la sesión local.

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.

Ejemplos

Ejemplo 1: Suscribirse a eventos cuando se inicia un nuevo proceso

Este ejemplo se suscribe a los eventos generados cuando se inicia un nuevo proceso.

El comando usa el objeto ManagementEventWatcher para obtener eventos EventArrived . Un objeto de consulta especifica que los eventos son eventos de creación de instancias para la clase Win32_Process .

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"

Ejemplo 2: Especificar una acción para responder a un evento

Cuando se especifica una acción, los eventos generados no se agregan a la cola de eventos. En su lugar, la acción responde al evento. En este ejemplo, cuando se genera un evento de creación de instancia que indica que se inicia un nuevo proceso, se genera un nuevo evento ProcessCreated .

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
$newEventArgs = @{
    SourceIdentifier = 'PowerShell.ProcessCreated'
    Sender = $Sender
    EventArguments = $EventArgs.NewEvent.TargetInstance
}
$Action = { New-Event @newEventArgs }
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action

Id   Name               PSJobTypeName   State       HasMoreData   Location   Command
--   ----               -------------   -----       -----------   --------   -------
 5   3db2d67a-efff-...                 NotStarted   False                    New-Event @newEventArgs

La acción usa las $Sender variables automáticas y $EventArgs que se rellenan solo para las acciones de evento.

El Register-ObjectEvent comando devuelve un objeto de trabajo que representa la acción , que se ejecuta como un trabajo en segundo plano. Puede usar los cmdlets job, como Get-Job y Receive-Job, para administrar el trabajo en segundo plano. Para más información, consulte about_Jobs (Acerca de los trabajos).

Ejemplo 3: Suscribirse a eventos de objeto en equipos remotos

Este ejemplo muestra cómo suscribirse a eventos de objeto en equipos remotos. En este ejemplo se usa la Enable-ProcessCreationEvent función definida en el archivo de ProcessCreationEvent.ps1 script. Este script está disponible para todos los equipos del ejemplo.

# ProcessCreationEvent.ps1
function  Enable-ProcessCreationEvent {
    $queryParameters = "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1),
        "TargetInstance isa 'Win32_Process'"
    $Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters

    $objectEventArgs = @{
        Input = New-Object System.Management.ManagementEventWatcher $Query
        EventName = 'EventArrived'
        SourceIdentifier = 'WMI.ProcessCreated'
        MessageData = 'Test'
        Forward = $True
    }
    Register-ObjectEvent @objectEventArgs
}

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
Invoke-Command -Session $S { Enable-ProcessCreationEvent }

La primera que creamos PSSessions en dos equipos remotos y las guardamos en la $S variable . A continuación, el Invoke-Command cmdlet ejecuta el ProcessCreationEvent.ps1 script en cada una de las PSSessions de $S. Esta acción crea la Enable-ProcessCreationEvent función en las sesiones remotas. Por último, ejecutamos la Enable-ProcessCreationEvent función en las sesiones remotas.

La función incluye un Register-ObjectEvent comando que se suscribe a eventos de creación de instancias en el objeto Win32_Process a través del objeto ManagementEventWatcher y su evento EventArrived .

Ejemplo 4: Uso del módulo dinámico en el objeto PSEventJob

En este ejemplo se muestra cómo usar el módulo dinámico en el objeto PSEventJob que se crea al incluir una acción en un registro de eventos. Primero creamos y habilitamos un objeto de temporizador y, a continuación, establecemos el intervalo del temporizador en 500 (milisegundos). El Register-ObjectEvent cmdlet registra el evento Transcurrido del objeto de temporizador. El objeto PSEventJob se guarda en la $Job variable y también está disponible en la propiedad Action del suscriptor de eventos. Para obtener más información, vea Get-EventSubscriber.

Cada vez que transcurre el intervalo del temporizador, se genera un evento y se ejecuta la acción. En este caso, el Get-Random cmdlet genera un número aleatorio entre 0 y 100 y lo guarda en la $Random variable .

$Timer = New-Object Timers.Timer
$Timer.Interval = 500
$Timer.Enabled = $True
$objectEventArgs = @{
    InputObject = $Timer
    EventName = 'Elapsed'
    SourceIdentifier = 'Timer.Random'
    Action = {$Random = Get-Random -Min 0 -Max 100}
}
$Job = Register-ObjectEvent @objectEventArgs
$Job | Format-List -Property *
& $Job.module {$Random}
& $Job.module {$Random}

State         : Running
Module        : __DynamicModule_53113769-31f2-42dc-830b-8749325e28d6
StatusMessage :
HasMoreData   : True
Location      :
Command       : $Random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 47b5ec9f-bfe3-4605-860a-4674e5d44ca8
Id            : 7
Name          : Timer.Random
ChildJobs     : {}
PSBeginTime   : 6/27/2019 10:19:06 AM
PSEndTime     :
PSJobTypeName :
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}
60
47

PSEventJob tiene una propiedad Module que contiene un módulo de script dinámico que implementa la acción. Con el operador de llamada (&), se invoca el comando en el módulo para mostrar el valor de la $Random variable.

Para obtener más información sobre los módulos, consulte about_Modules.

Parámetros

-Action

Especifica los comandos para controlar el evento. 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, $EventArgsy $Args . Estas variables proporcionan información sobre el evento en el bloque De script de acción . Para obtener más información, vea about_Automatic_Variables.

Cuando se especifica una acción, Register-ObjectEvent 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

-EventName

Especifica el evento al que se suscribe.

El valor de este parámetro debe ser el nombre del evento que expone el objeto .NET. Por ejemplo, la clase ManagementEventWatcher tiene eventos denominados EventArrived y Stopped. Para buscar el nombre del evento de un evento, use el Get-Member cmdlet .

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Forward

Indica que el cmdlet envía eventos para esta suscripción a una sesión remota. 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

-InputObject

Especifica el objeto .NET que genera los eventos. Escriba una variable que contenga el objeto, o escriba un comando o una expresión que obtenga el objeto.

Type:PSObject
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-MaxTriggerCount

Especifica el número máximo de veces que se puede desencadenar un evento.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MessageData

Especifica los datos adicionales que se asociarán con esta suscripción de evento. El valor de este parámetro aparece en la propiedad MessageData de todos los eventos asociados a esta suscripción.

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SourceIdentifier

Especifica un nombre que usted selecciona para la suscripción. El nombre que seleccione debe ser único en la sesión actual. El valor predeterminado es el GUID que asigna PowerShell.

El valor de este parámetro aparece en el valor de la propiedad SourceIdentifier del objeto subscriber y todos los objetos de evento asociados a esta suscripción.

Type:String
Position:100
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SupportEvent

Indica que el cmdlet oculta la suscripción de eventos. Use 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 , use el parámetro Force de los Get-EventSubscriber cmdlets y 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á.