Register-EngineEvent

Assina eventos que são gerados pelo mecanismo Windows PowerShell e pelo cmdlet New-Event.

Sintaxe

Register-EngineEvent [-SourceIdentifier] <string> [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]

Descrição

O cmdlet Register-EngineEvent assina eventos que são gerados pelo mecanismo Windows PowerShell e pelo cmdlet New-Event. Use o parâmetro SourceIdentifier para especificar o evento.

Você pode usar este cmdlet para assinar o evento de mecanismo “Exiting” e eventos gerados pelo cmdlet New-Event. Esses eventos são acrescentados automaticamente à fila de eventos por sua sessão sem assinar. Porém, a assinatura permite que você encaminhe os eventos, especifique uma ação para responder aos eventos e cancele a assinatura.

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.

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

-Forward

Envia eventos desta assinatura para a sessão no computador local. 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

-MessageData <psobject>

Especifica dados adicionais associados ao evento. O valor deste parâmetro aparece na propriedade MessageData do objeto de evento.

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-SourceIdentifier <string>

Especifica o identificador de origem do evento o qual você está assinando. O identificador de origem deve ser exclusivo na sessão atual. Esse parâmetro é obrigatório.

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

Necessário?	true
Posição?	101
Valor padrão
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 saída para Register-EngineEvent.
Saídas	Nenhum ou System.Management.Automation.PSEventJob Se você usar o parâmetro Action, Register-EngineEvent retornará um objeto System.Management.Automation.PSEventJob. Caso contrário, ele 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>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s { Register-EngineEvent -sourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -forward }

Descrição
-----------
Este comando registra um evento de mecanismo Windows PowerShell em dois computadores remotos. 

O primeiro comando cria uma PSSession em cada um dos computadores remotos.

O segundo comando usa o cmdlet Invoke-Command para executar um comando Register-EngineEvent nas sessões remotas. 

O comando Register-EngineEvent usa o parâmetro SourceIdentifier para identificar o evento. Usa o parâmetro Forward para encaminhar os eventos da sessão remota para a sessão local.

Exemplo 2

C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated -action { $processName | add-content processLog.txt } 

C:\PS> get-event

C:\PS> $results = $j | receive-job

C:\PS> unregister-event PowerShell.ProcessCreated

Descrição
-----------
Este comando mostra como usar os cmdlets Job para gerenciar o objeto de trabalho de evento que Register-EngineEvent retorna quando você usa o parâmetro Action.

Um trabalho de evento é gerenciado como qualquer outro trabalho do Windows PowerShell. Para obter mais informações, consulte about_jobs. Neste exemplo, o cmdlet Receive-Job é usado para obter os resultados do trabalho.

Para excluir o trabalho da sessão, use Remove-Job. Para cancelar sua assinatura de evento, use o cmdlet Unregister-Event. Para excluir os eventos da fila de eventos, use Remove-Event.

Consulte também

Conceitos

Register-ObjectEvent
Register-WmiEvent
Unregister-Event
Get-Event
New-Event
Remove-Event
Wait-Event
Get-Job
Receive-Job
Remove-Job
Wait-Job