Register-ObjectEvent
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 |
Nenhum. |
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 |
Nenhum Não é possível canalizar objetos para Register-ObjectEvent. |
Saídas |
Nenhum 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.
Consulte também
Conceitos
Register-EngineEvent
Register-WmiEvent
Unregister-Event
Get-Event
New-Event
Remove-Event
Wait-Event