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 |
None Não é possível canalizar saída para Register-EngineEvent. |
|
Saídas |
None 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.
See Also