Register-ObjectEvent

Sintaxe

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

Description

O Register-ObjectEvent cmdlet assina eventos gerados por objetos .NET no computador local ou em um computador remoto.

Quando o evento inscrito é gerado, ele é adicionado à fila de eventos em sua sessão. Para obter eventos na fila de eventos, use o Get-Event cmdlet.

Você pode usar os parâmetros de Register-ObjectEvent para especificar valores de propriedade dos eventos que podem ajudá-lo a identificar o evento na fila. Você também pode usar o parâmetro Action para especificar ações a serem executadas quando um evento inscrito é gerado e o parâmetro Forward para enviar eventos remotos para a fila de eventos na sessão local.

Quando você se inscreve em um evento, um assinante de evento é adicionado à sua sessão. Para obter os assinantes do evento na sessão, use o Get-EventSubscriber cmdlet. Para cancelar a assinatura, use o Unregister-Event cmdlet, que exclui o assinante do evento da sessão.

Exemplos

Exemplo 1: Assinar eventos quando um novo processo for iniciado

Este exemplo assina eventos gerados quando um novo processo é iniciado.

O comando usa o objeto ManagementEventWatcher para obter eventos EventArrived . Um objeto de consulta especifica que os eventos são eventos de criação de instância para a classe 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"

Exemplo 2: Especificar uma ação para responder a um evento

Ao especificar uma ação, eventos que são criados não são adicionados à fila de eventos. Em vez disso, a ação responde ao evento. Neste exemplo, quando um evento de criação de instância é gerado indicando que um novo processo foi iniciado, um novo evento ProcessCreated é gerado.

$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

A ação usa as variáveis automáticas e $EventArgs que são preenchidas $Sender apenas para ações de evento.

O Register-ObjectEvent comando retorna um objeto de trabalho que representa a ação, que é executada como um trabalho em segundo plano. Você pode usar os cmdlets Job, como Get-Job e Receive-Job, para gerenciar o trabalho em segundo plano. Para obter mais informações, consulte about_Jobs.

Exemplo 3: Assinar eventos de objeto em computadores remotos

Este exemplo mostra como assinar eventos de objetos em computadores remotos. Este exemplo usa a Enable-ProcessCreationEvent função definida no ProcessCreationEvent.ps1 arquivo de script. Esse script está disponível para todos os computadores no exemplo.

# 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 }

O primeiro criamos PSSessions em dois computadores remotos e os salvamos na $S variável. Em seguida, o Invoke-Command cmdlet executa o ProcessCreationEvent.ps1 script em cada uma das PSSessions no $S. Essa ação cria a Enable-ProcessCreationEvent função nas sessões remotas. Por fim, executamos a Enable-ProcessCreationEvent função nas sessões remotas.

A função inclui um Register-ObjectEvent comando que assina eventos de criação de instância no objeto Win32_Process por meio do objeto ManagementEventWatcher e seu evento EventArrived .

Exemplo 4: Usar o módulo dinâmico no objeto PSEventJob

Este exemplo mostra como usar o módulo dinâmico no objeto PSEventJob que é criado quando você inclui uma ação em um registro de evento. Primeiro, criamos e habilitamos um objeto de temporizador e, em seguida, definimos o intervalo do temporizador para 500 (milissegundos). O Register-ObjectEvent cmdlet registra o evento Elapsed do objeto timer. O objeto PSEventJob é salvo na $Job variável e também está disponível na propriedade Action do assinante do evento. Para obter mais informações, consulte Get-EventSubscriber.

Sempre que o intervalo do temporizador expira, um evento é gerado e a ação é executada. Nesse caso, o Get-Random cmdlet gera um número aleatório entre 0 e 100 e o salva na $Random variável.

$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

O PSEventJob tem uma propriedade Module que contém um módulo de script dinâmico que implementa a ação. Usando o operador de chamada (&), invocamos o comando no módulo para exibir o $Random valor da variável.

Para obter mais informações sobre módulos, consulte about_Modules.

Parâmetros

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

None

Por padrão, esse cmdlet não retorna nenhuma saída.

PSEventJob

Quando você usa o parâmetro Action , esse cmdlet retorna um objeto PSEventJob .

Observações

Eventos, assinaturas de evento e a fila de eventos existem apenas na sessão atual. Se você fechar a sessão atual, a fila de eventos será descartada e a inscrição do evento será cancelada.

Links Relacionados

• Get-Event
• New-Event
• Register-EngineEvent
• Remove-Event
• Unregister-Event
• Wait-Event