Assina os eventos que são gerados por um objeto Microsoft .NET Framework.

Sintaxe

Register-ObjectEvent [-InputObject] <psobject> [-EventName] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]

Descrição

O cmdlet Register-ObjectEvent assina eventos que são gerados por objetos .NET Framework no computador local ou em um computador remoto.

Quando o evento assinado é aumentado, é adicionado à fila de eventos da 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 propriedades dos eventos que podem ajudar a identificar o evento na fila. Você também pode usar o parâmetro Action para especificar ações a serem tomadas quando um evento assinado é aumentado e parâmetro Forward para enviar eventos remotos para a fila de eventos da sessão local.

Ao assinar um evento, um assinante de evento é adicionado à 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.

Parâmetros

-Action <scriptblock>

Especifica comandos que manipulam os eventos. Os comandos da ação são executados quando um evento é gerado, em vez de enviar o evento à fila de eventos. Coloque o comando entre chaves ( { } ) para criar um bloco de scripts.

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

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

Necessário?

false

Posição?

102

Valor padrão

None.

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-EventName <string>

Especifica o evento que você está assinando. Insira o nome do evento. Esse parâmetro é obrigatório.

O valor deste parâmetro não é um nome que você seleciona para a assinatura de evento. É o nome de um evento que o objeto .NET Framework expõe. Por exemplo, a classe ManagementEventWatcher tem eventos chamados "EventArrived" e "Stopped". Para localizar o nome de um evento, use o cmdlet Get-Member.

Necessário?

true

Posição?

2

Valor padrão

nenhum

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Forward

Envia eventos desta assinatura para uma sessão remota. Use este parâmetro quando estiver registrando-se para eventos em um computador remoto ou em uma sessão remota.

Necessário?

false

Posição?

named

Valor padrão

False

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-InputObject <psobject>

Especifica o objeto .NET Framework que gera os eventos. Insira uma variável que contenha o objeto, ou digite um comando ou uma expressão que obtenha o objeto. Esse parâmetro é obrigatório.

Necessário?

true

Posição?

1

Valor padrão

nenhum

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-MessageData <psobject>

Especifica qualquer dado adicional a ser associado a esta inscrição de evento. O valor desse parâmetro aparece na propriedade MessageData de todos os eventos associados à assinatura.

Necessário?

false

Posição?

named

Valor padrão

nenhum

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-SourceIdentifier <string>

Especifica um nome que você seleciona para a assinatura. O nome que você selecionar deverá ser exclusivo na sessão atual. O valor padrão é o GUID que o Windows PowerShell atribui.

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

Necessário?

false

Posição?

101

Valor padrão

GUID

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-SupportEvent

Oculta a assinatura do evento. Use este parâmetro quando a assinatura atual fizer parte de um mecanismo de registro de eventos mais complexo e não precisar ser descoberta 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.

Necessário?

false

Posição?

named

Valor padrão

False

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas

None

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

Saídas

None

Este cmdlet não gera nenhuma saída.

Observações

Eventos, assinaturas de eventos e a fila de eventos só existem na sessão atual. Se você fechar a sessão atual, a fila de eventos será descartada e a assinatura de evento será cancelada.

Exemplo 1

C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" 

C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query 

C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived"

Descrição
-----------
Este exemplo assina eventos gerados quando um novos processo inicia. 

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.






Exemplo 2

C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" 

C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query 

C:\PS> $action = { New-Event "PowerShell.ProcessCreated" -Sender $sender -EventArguments $SourceEventArgs.NewEvent.TargetInstance } 

C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived" -action $action

Id    Name            State      HasMoreData     Location             Command
--    ----            -----      -----------     --------             -------
2     422cfe5a-65e... Running    True                                 New-Event "PowerShe...

Descrição
-----------
Este exemplo mostra como especificar uma ação para responder a um evento. Quando você especificar uma ação, não serão acrescentados à fila de eventos os eventos gerados. Em vez disso, a ação responde ao evento. 

Neste exemplo, quando um evento de criação de instância é aumentado indicando que um novo processo foi iniciado, um novo evento ProcessCreated é aumentado.

A ação usa as variáveis automáticas $Sender e $SourceEventArgs, que só são populadas para ações de evento. 

O comando Register-ObjectEvent retorna um objeto de trabalho que representa a ação, executada como trabalho em segundo plano. É possível 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

C:\PS>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s -filepath ProcessCreationEvent.ps1

C:\PS> invoke-command -session $s { get-event }

# ProcessCreationEvent.ps1

function Enable-ProcessCreationEvent 
{ 
   $query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", ` 
       (New-Object TimeSpan 0,0,1), ` 
       "TargetInstance isa 'Win32_Process'" 
   $processWatcher = New-Object System.Management.ManagementEventWatcher $query 

   $identifier = "WMI.ProcessCreated" 
   Register-ObjectEvent -input $processWatcher -eventName "EventArrived" `
      -sourceIdentifier $identifier -messageData "Test" -forward 
   } 
} 

EnableProcessCreationEvent

Descrição
-----------
Este exemplo mostra como assinar eventos de objeto em computadores remotos.

O primeiro comando cria PSSessions em dois computadores remotos e as salva na variável $s.

O segundo comando usa o parâmetro FilePath do cmdlet Invoke-Command para executar o script ProcessCreationEvent.ps1 em cada PSSession em $s. 

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






Exemplo 4

C:\PS>$timer  = New-Object Timers.Timer

C:\PS> $timer.Interval = 500

C:\PS> $job = Register-ObjectEvent -inputObject $timer -eventName Elapsed -sourceIdentifier Timer.Random -Action {$random = Get-Random -Min 0 -Max 100}

C:\PS> $job.gettype().fullname
System.Management.Automation.PSEventJob

C:\PS> $job | format-list -property *

State         : Running
Module        : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0
StatusMessage :
HasMoreData   : True
Location      :
Command       : $random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 88944290-133d-4b44-8752-f901bd8012e2
Id            : 1
Name          : Timer.Random
ChildJobs     : {}
...

C:\PS> $timer.Enabled = $true

C:\PS> & $job.module {$random}
60

C:\PS> & $job.module {$random}
47

Descrição
-----------
Esse exemplo mostra como usar o módulo dinâmico no objeto PSEventJob criado quando você inclui uma ação em um registro de eventos.

O primeiro comando usa o cmdlet New-Object para criar um objeto do timer. O segundo comando define o intervalo do timer para 500 (milissegundos).

O terceiro comando usa o cmdlet Register-ObjectEvent para registrar o evento Elapsed do objeto de timer. O comando inclui uma ação que trata o evento. Sempre que decorre um intervalo do timer, um evento é gerado e os comandos da ação são executados. Nesse caso, o cmdlet Get-Random gera um número aleatório entre 0 e 100 e o salva na variável $random.

Quando você usar um parâmetro Action em um comando Register-ObjectEvent, o comando retornará um objeto PSEventJob que representa a ação. O comando salva o objeto de trabalho na variável $job.

O objeto PSEventJob que o cmdlet Register-ObjectEvent retorna também está disponível na propriedade Action do assinante do evento. Para obter mais informações, consulte Get-EventSubscriber.

O quarto comando mostra que a variável $job contém um objeto PSEventJob. O quinto comando usa o cmdlet Format-List para exibir todas as propriedades do objeto PSEventJob em uma lista. 

O PSEventJob tem uma propriedade Module que contém um módulo de script dinâmico que implementa a ação.

O sexto comando habilita o timer.

Os comandos restantes usam o operador de chamada (&) para invocar o comando no módulo e exibir o valor da variável $random. Você pode usar o operador de chamada para invocar qualquer comando em um módulo, inclusive comandos que não são exportados. Nesse caso, os comandos mostram o número aleatório que está sendo gerado quando o evento Elapsed ocorre.

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






See Also




Sumário