Register-EngineEvent
Assina eventos gerados pelo mecanismo do PowerShell e pelo cmdlet New-Event.
Sintaxe
Default (Predefinição)
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Description
O cmdlet Register-EngineEvent assina eventos gerados pelo mecanismo do PowerShell e pelo cmdlet New-Event. Use o parâmetro SourceIdentifier para especificar o evento.
Você pode usar este cmdlet para se inscrever nos eventos OnIdle ou Encerramento do mecanismo e nos eventos gerados pelo cmdlet New-Event. Esses eventos são adicionados automaticamente à fila de eventos em sua sessão sem se inscrever. No entanto, a subscrição permite-lhe reencaminhar os eventos, especificar uma ação para responder aos eventos e cancelar a subscrição.
Quando subscreve um evento, um subscritor do evento é adicionado à sua sessão. Para obter os subscritores 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.
Quando o evento inscrito é gerado, ele é adicionado à fila de eventos em sua sessão. Para obter eventos na fila de eventos, use o cmdlet Get-Event.
Exemplos
Exemplo 1: Registrar um evento do mecanismo do PowerShell em computadores remotos
Este exemplo registra um evento do mecanismo do PowerShell em dois computadores remotos.
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}
New-PSSession cria uma sessão gerenciada pelo usuário (PSSession) em cada um dos computadores remotos. O cmdlet Invoke-Command executa o comando Register-EngineEvent nas sessões remotas.
Register-EngineEvent usa o parâmetro SourceIdentifier para identificar o evento. O parâmetro Forward instrui o sistema a reenviar os eventos da sessão remota para a sessão local.
Exemplo 2: Quando ocorrer o evento Exiting, execute uma ação especificada
Este exemplo mostra como executar Register-EngineEvent para realizar uma ação específica quando o evento PowerShell.Exiting é acionado.
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $HOME\history.clixml
}
O parâmetro SupportEvent é adicionado para ocultar a subscrição do evento. Quando o PowerShell é encerrado, nesse caso, o histórico de comandos da sessão de saída é exportado um arquivo XML no diretório $HOME do usuário.
Exemplo 3: Criar e subscrever um evento definido pelo utilizador
Este exemplo cria uma assinatura para eventos da fonte MyEventSource. Esta é uma fonte arbitrária que vamos utilizar para monitorizar o progresso de um trabalho.
Register-EngineEvent é usado para criar a assinatura. O bloco de script para o parâmetro Action registra os dados do evento em um arquivo de texto.
Register-EngineEvent -SourceIdentifier MyEventSource -Action {
"Event: {0}" -f $event.messagedata | Out-File c:\temp\MyEvents.txt -Append
}
Start-Job -Name TestJob -ScriptBlock {
While ($True) {
Register-EngineEvent -SourceIdentifier MyEventSource -Forward
Start-Sleep -seconds 2
"Doing some work..."
New-Event -SourceIdentifier MyEventSource -Message ("{0} - Work done..." -f (Get-Date))
}
}
Start-Sleep -seconds 4
Get-EventSubscriber
Get-Job
SubscriptionId : 12
SourceObject :
EventName :
SourceIdentifier : MyEventSource
Action : System.Management.Automation.PSEventJob
HandlerDelegate :
SupportEvent : False
ForwardEvent : False
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Running True …
19 TestJob BackgroundJob Running True localhost …
Register-EngineEvent criou o Job Id 18.
Start-Job criou o Job Id 19. No Exemplo #4, removemos a assinatura do evento e os trabalhos e, em seguida, inspecionamos o arquivo de log.
Exemplo 4: Desregistrar eventos e limpar processos
Esta é uma continuação do Exemplo 3. Neste exemplo, esperamos 10 segundos para permitir que vários eventos ocorram. Em seguida, cancelamos o registro da assinatura do evento.
PS> Start-Sleep -seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Stopped False …
19 TestJob BackgroundJob Running True localhost …
PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM - Work done...
Event: 2/18/2020 2:36:21 PM - Work done...
Event: 2/18/2020 2:36:23 PM - Work done...
Event: 2/18/2020 2:36:25 PM - Work done...
Event: 2/18/2020 2:36:27 PM - Work done...
Event: 2/18/2020 2:36:29 PM - Work done...
Event: 2/18/2020 2:36:31 PM - Work done...
O cmdlet Unregister-Event interrompe a tarefa associada à assinatura do evento (Job Id 18). O Job Id 19 ainda está em execução e criando novos eventos. Usamos os cmdlets Job para interromper o trabalho e remover os objetos de tarefa desnecessários.
Get-Content exibe o conteúdo do arquivo de log.
Parâmetros
-Action
Especifica comandos para manipular os eventos. Os comandos na Ação são executados quando um evento é gerado, em vez de enviar o evento para a fila de eventos. Coloque os comandos entre chaves ({}) para criar um bloco de script.
O valor do parâmetro
Quando você especifica uma ação, Register-EngineEvent retorna um objeto de trabalho de evento que representa essa ação. Você pode usar os cmdlets Job para gerenciar a tarefa de evento.
Propriedades dos parâmetros
| Tipo: | ScriptBlock |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 101 |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Forward
Indica que o cmdlet envia eventos desta assinatura para a sessão no computador local. Use esse parâmetro quando estiver se registrando para eventos em um computador remoto ou em uma sessão remota.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-MaxTriggerCount
Especifica o número máximo de vezes que a ação é executada para a assinatura do evento.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-MessageData
Especifica dados adicionais associados ao evento. O valor desse parâmetro aparece na propriedade MessageData do objeto de evento.
Propriedades dos parâmetros
| Tipo: | PSObject |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-SourceIdentifier
Especifica o identificador de origem do evento ao qual você está se inscrevendo. 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 do assinante e de todos os objetos de evento associados a essa assinatura.
O valor é específico para a origem do evento. Esse pode ser um valor arbitrário criado para usar com o cmdlet New-Event. O mecanismo do PowerShell suporta os valores PSEngineEventPowerShell.Exiting e PowerShell.OnIdle.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 100 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-SupportEvent
Indica que o cmdlet oculta a assinatura do evento. Adicione esse parâmetro quando a assinatura atual fizer parte de um mecanismo de registro de eventos mais complexo e não for descoberta independentemente.
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 dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 canalizar objetos para este cmdlet.
Saídas
None
Por padrão, esse cmdlet não retorna nenhuma saída.
PSEventJob
Quando você usa o parâmetro Action, esse cmdlet retorna um objeto PSEventJob.
Notas
Eventos, assinaturas de eventos e a fila de eventos existem somente na sessão atual. Se você fechar a sessão atual, a fila de eventos será descartada e a assinatura do evento será cancelada.
Ao subscrever o evento Exiting, os cmdlets que podem ser executados através do parâmetro Action estão limitados aos cmdlets dos módulos Microsoft.PowerShell.Core e Microsoft.PowerShell.Utility. O evento Exiting só é acionado quando a sessão é encerrada sob o controle do PowerShell. O evento não é acionado quando o aplicativo host ou a janela do terminal é fechada.
O motor é considerado sem atividade se não estiver a executar um pipeline. O evento OnIdle é acionado quando o PowerShell está inativo durante 300 milissegundos (ms).
Observação
Quando o PSReadLine está em uso, o evento OnIdle é acionado quando ReadKey() expira (300ms sem digitar). O evento pode ser sinalizado enquanto o usuário está no meio da edição de uma linha de comando, por exemplo, o usuário está lendo ajuda para decidir qual parâmetro usar. A partir do PSReadLine 2.2.0-beta4, comportamento do OnIdle foi alterado para sinalizar o evento somente se houver um tempo limite de ReadKey() e o buffer de edição atual estiver vazio.