Register-EngineEvent
Assina eventos gerados pelo mecanismo do PowerShell e pelo New-Event cmdlet.
Syntax
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Description
O Register-EngineEvent cmdlet assina eventos gerados pelo mecanismo do PowerShell e pelo New-Event cmdlet. 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 New-Event cmdlet. Esses eventos são adicionados automaticamente à fila de eventos em sua sessão sem assinatura. No entanto, inscrever-se permite encaminhar eventos, especificar uma ação para responder aos eventos e cancelar a assinatura.
Quando o evento inscrito é gerado, ele é adicionado à fila de eventos em sua sessão. Para obter eventos na fila de eventos, use o Get-Event cmdlet.
Quando você assina um evento, um assinante de evento é adicionado à sua sessão. Para obter os assinantes do evento na sessão, use o Get-EventSubscriber cmdlet. Para cancelar a assinatura, use o Unregister-Event cmdlet, que exclui o assinante do evento da sessão.
Exemplos
Exemplo 1: registrar um evento do mecanismo do PowerShell em computadores remotos
Este exemplo se registra para 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 Invoke-Command cmdlet executa o Register-EngineEvent comando nas sessões remotas.
Register-EngineEvent usa o parâmetro SourceIdentifier para identificar o evento. O parâmetro Forward informa ao mecanismo para encaminhar os eventos da sessão remota para a sessão local.
Exemplo 2: execute uma ação especificada quando o evento Exiting ocorrer
Este exemplo mostra como executar Register-EngineEvent para executar uma ação específica quando o evento PowerShell.Exiting ocorrer.
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}O parâmetro SupportEvent é adicionado para ocultar a assinatura 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 do $Home usuário.
Exemplo 3: criar e assinar um evento definido pelo usuário
Este exemplo cria uma assinatura para eventos do MyEventSource de origem. Esta é uma fonte arbitrária que vamos usar para monitorar o progresso de um trabalho. Register-EngineEvent é usado para criar a assinatura. O bloco de script do 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 a ID do trabalho 18. Start-Job criou a ID do Trabalho 19. No exemplo nº 4, removemos a assinatura do evento e os trabalhos e, em seguida, inspecionamos o arquivo de log.
Exemplo 4: cancelar o registro de eventos e limpar trabalhos
Esta é uma continuação do Exemplo 3. Neste exemplo, aguardamos 10 segundos para permitir que vários eventos ocorram. Em seguida, cancelaremos 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 Unregister-Event cmdlet interrompe o trabalho associado à assinatura do evento (ID do trabalho 18). A ID do trabalho 19 ainda está em execução e criando novos eventos. Usamos os cmdlets job parando o trabalho e removendo os objetos de trabalho desnecessários. Get-Content exibe o conteúdo do arquivo de log.
Parâmetros
-Action
Especifica os comandos para manipular os eventos. Os comandos em Action 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 Action pode incluir as $Eventvariáveis automáticas , e , $EventArgs$Args$EventSubscriber$Senderque fornecem informações sobre o evento para o bloco de script de ação. Para obter mais informações, confira about_Automatic_Variables.
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.
| Type: | ScriptBlock |
| Position: | 101 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Forward
Indica que o cmdlet envia eventos para essa assinatura para a sessão no computador local. Utilize esse parâmetro ao registrar eventos em um computador remoto ou em uma sessão remota.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaxTriggerCount
Especifica o número máximo de vezes que a ação será executada para a assinatura do evento.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MessageData
Especifica os dados adicionais associados ao evento. O valor desse parâmetro é exibido na propriedade MessageData do objeto de evento.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 é necessá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.
O valor é específico para a origem do evento. Esse pode ser um valor arbitrário que você criou para usar com o New-Event cmdlet. O mecanismo do PowerShell dá suporte aos valores de EngineEventPowerShell.Exiting e PowerShell.OnIdle.
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SupportEvent
Indica que o cmdlet oculta a assinatura do evento. Adicione esse parâmetro quando a assinatura atual faz parte de um mecanismo de registro de evento mais complexo e não deve ser descoberta de forma independente.
Para exibir ou cancelar uma assinatura criada com o parâmetro SupportEvent, adicione o parâmetro Force aos cmdlets ou Unregister-Event aos Get-EventSubscriber cmdlets.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Entradas
None
Não é possível direcionar a entrada para Register-EngineEvent.
Saídas
None or 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
Nenhuma fonte de evento disponível nas plataformas Linux ou macOS.
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 inscrição do evento será cancelada.