Register-ObjectEvent

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

El cmdlet Register-ObjectEvent 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 los eventos de la cola de eventos, use el cmdlet Get-Event.

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

En este ejemplo se suscribe a eventos generados cuando se inicia un nuevo proceso.

El comando usa el objeto managementEventWatcher de 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"

Al especificar una acción, los eventos que se generan 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 instancias 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 el $Sender y $EventArgs variables automáticas que se rellenan solo para las acciones de evento.

El comando Register-ObjectEvent 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).

En este ejemplo se muestra cómo suscribirse a eventos de objeto en equipos remotos. En este ejemplo se usa la función Enable-ProcessCreationEvent que se define en el archivo de script de ProcessCreationEvent.ps1. 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 variable $S. A continuación, el cmdlet Invoke-Command ejecuta el script de ProcessCreationEvent.ps1 en cada una de las PSSessions de $S. Esta acción crea la función Enable-ProcessCreationEvent en las sesiones remotas. Por último, ejecutamos la función Enable-ProcessCreationEvent en las sesiones remotas.

La función incluye un comando Register-ObjectEvent 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.

En este ejemplo se muestra cómo usar el módulo dinámico en el objeto PSEventJob que se crea al incluir un action de 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 cmdlet registra el evento transcurrido del objeto de temporizador. El objeto PSEventJob se guarda en la 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 cmdlet Get-Random genera un número aleatorio entre 0 y 100 y lo guarda en la variable $Random.

$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

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

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

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.

No se pueden canalizar objetos a este cmdlet.

De forma predeterminada, este cmdlet no devuelve ninguna salida.

Cuando se usa el parámetro Action, este cmdlet devuelve un objeto PSEventJob.

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.