Compartilhar via

Register-ObjectEvent

Módulo:
Microsoft.PowerShell.Utility Module

Assina os eventos gerados por um objeto do Microsoft .NET Framework.

Sintaxe

Default (Default) 

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

Description

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

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

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 assinado é acionado e o parâmetro Encaminhar para enviar eventos remotos para a fila de eventos na sessão local.

Quando você assina um evento, um assinante de evento é adicionado à sua sessão. Para obter os assinantes do evento na sessão, use o cmdlet Get-EventSubscriber. Para cancelar a assinatura, use o cmdlet Unregister-Event, 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

Quando você especifica uma ação, os eventos gerados 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 é 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 $Sender e $EventArgs automáticas que são preenchidas apenas para ações de evento.

O comando Register-ObjectEvent 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 objeto em computadores remotos. Este exemplo usa a função Enable-ProcessCreationEvent definida no arquivo de script ProcessCreationEvent.ps1. 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 }

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

A função inclui um 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 um de Ação em um registro de evento. Primeiro, criamos e habilitamos um objeto de temporizador e definimos o intervalo do temporizador como 500 (milissegundos). O cmdlet registra o evento decorrido do objeto timer. O objeto PSEventJob é salvo na variável $Job 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 de temporizador decorrido, um evento é acionado e a ação é executada. Nesse caso, o cmdlet Get-Random gera um número aleatório entre 0 e 100 e o salva na variável $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

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 valor da variável $Random.

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

Parâmetros

-Action

Especifica os comandos para lidar com o evento. Os comandos no Action são executados quando um evento é acionado, em vez de enviar o evento para a fila de eventos. Coloque os comandos em chaves ( { } ) para criar um bloco de script.

O valor do parâmetro Action pode incluir as variáveis automáticas $Event, $EventSubscriber, $Sender, $EventArgse $Args. Essas variáveis fornecem informações sobre o evento para o bloco de script Action. Para obter mais informações, confira about_Automatic_Variables.

Quando você especifica uma ação, Register-ObjectEvent retorna um objeto de trabalho de evento que representa essa ação. É possível utilizar os cmdlets Job para gerenciar o trabalho de eventos.

Propriedades do parâmetro

Tipo:ScriptBlock
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:101
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-EventName

Especifica o evento ao qual você está assinando.

O valor desse parâmetro deve ser o nome do evento que o objeto .NET expõe. Por exemplo, a classe ManagementEventWatcher tem eventos chamados EventArrived e Stopped. Para localizar o nome do evento de um evento, use o cmdlet Get-Member.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:1
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Forward

Indica que o cmdlet envia eventos para essa assinatura para uma sessão remota. Use esse parâmetro quando você estiver se registrando para eventos em um computador remoto ou em uma sessão remota.

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-InputObject

Especifica o objeto .NET que gera os eventos. Insira uma variável que contenha o objeto ou digite um comando ou expressão que obtém o objeto.

Propriedades do parâmetro

Tipo:PSObject
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-MaxTriggerCount

Especifica o número máximo de vezes que um evento pode ser disparado.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-MessageData

Especifica quaisquer dados adicionais a serem associados a essa assinatura de evento. O valor desse parâmetro aparece na propriedade MessageData de todos os eventos associados a essa assinatura.

Propriedades do parâmetro

Tipo:PSObject
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-SourceIdentifier

Especifica um nome selecionado para a assinatura. O nome selecionado deve ser exclusivo na sessão atual. O valor padrão é o GUID que o PowerShell atribui.

O valor desse parâmetro aparece no valor da propriedade SourceIdentifier do objeto assinante e todos os objetos de evento associados a essa assinatura.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:100
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-SupportEvent

Indica que o cmdlet oculta a inscrição do evento. Use esse parâmetro quando a assinatura atual fizer parte de um mecanismo de registro de evento mais complexo e não deve ser descoberto de forma independente.

Para exibir ou cancelar uma assinatura criada com o parâmetro SupportEvent, use o parâmetro Force dos cmdlets Get-EventSubscriber e Unregister-Event.

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

None

Não é possível redirecionar objetos para Register-ObjectEvent.

Saídas

None or System.Management.Automation.PSEventJob

Quando você usa o parâmetro Action, retorna um objeto System.Management.Automation.PSEventJob. Caso contrário, ele não gerará nenhuma saída.

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 assinatura do evento será cancelada.