Register-EngineEvent
Assina eventos gerados pelo mecanismo do Windows PowerShell e pelo cmdlet New-Event.
Sintaxe
Default (Default)
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Description
O cmdlet Register-EngineEvent assina eventos gerados pelo mecanismo do Windows PowerShell e pelo cmdlet New-Event. Use o parâmetro SourceIdentifier para especificar o evento.
Você pode usar esse cmdlet para assinar o evento do mecanismo de saída e os eventos gerados pelo cmdlet New-Event. Esses eventos são adicionados automaticamente à fila de eventos em sua sessão sem assinatura. No entanto, a assinatura permite encaminhar os eventos, especificar uma ação para responder aos eventos e cancelar a assinatura.
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.
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: registrar um evento de mecanismo do PowerShell em computadores remotos
PS C:\> $S = New-PSSession -ComputerName "Server01, Server02"
PS C:\> Invoke-Command -Session $S { Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward }
Esse comando registra um evento de mecanismo do Windows PowerShell em dois computadores remotos.
O primeiro comando cria uma PSSession (sessão gerenciada pelo usuário) em cada um dos computadores remotos.
O segundo comando usa o cmdlet Invoke-Command para executar o comando Register-EngineEvent nas sessões remotas.
O comando
Exemplo 2: executar uma ação especificada quando o evento Exiting ocorrer
PS C:\> Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}
Este comando mostra como executar Register-EngineEvent para executar uma ação específica quando o evento PowerShell.Exiting ocorrer. O parâmetro SupportEvent é adicionado para ocultar a subscrição ao evento. Quando o Windows PowerShell é encerrado, nesse caso, o histórico de comandos da sessão de saída é exportado no formato XML para um nome de arquivo e caminho no diretório $Home do usuário.
Parâmetros
-Action
Especifica comandos para lidar com os eventos. 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 de Ação
Quando você especifica uma ação, Register-EngineEvent 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 |
-Forward
Indica que o cmdlet envia eventos dessa assinatura para a sessão no computador local. 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 |
-MaxTriggerCount
Especifica a contagem máxima de gatilhos.
O valor do parâmetro de Ação
Quando você especifica uma ação, Register-EngineEvent 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: | 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 dados adicionais associados ao evento. O valor desse parâmetro aparece na propriedade MessageData do objeto de evento.
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 o identificador de origem do evento ao qual você está assinando. O identificador de origem deve ser exclusivo na sessão atual. Este parâmetro é obrigatório.
O valor desse parâmetro aparece no valor da propriedade SourceIdentifier do objeto assinante e de todos os objetos de evento associados a esta assinatura.
Os valores do EngineEvent com suporte incluem PowerShell.Exiting, PowerShell.OnIdle e PowerShell.OnScriptBlockInvoke.
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: | True |
| 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. Adicione esse parâmetro quando a assinatura atual fizer parte de um mecanismo de registro de evento mais complexo e ele não deve ser descoberto de forma independente.
Para exibir ou cancelar uma assinatura criada com o parâmetro SupportEvent, adicione o parâmetro Force aos cmdlets Get-EventSubscriber ou 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 a entrada para Register-EngineEvent.
Saídas
None or System.Management.Automation.PSEventJob
Se você usar o parâmetro
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.