Register-EngineEvent

Register-EngineEvent
    [-SourceIdentifier] <String>
    [[-Action] <ScriptBlock>]
    [-MessageData <PSObject>]
    [-SupportEvent]
    [-Forward]
    [-MaxTriggerCount <Int32>]
    [<CommonParameters>]

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 esse cmdlet para assinar os eventos do mecanismo OnIdle ou Exiting e 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 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.

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.

Este exemplo registra um evento de 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 PSSession (sessão gerenciada pelo usuário) 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 Encaminhar indica ao mecanismo que deve encaminhar os eventos da sessão remota para a sessão local.

Este exemplo mostra como executar Register-EngineEvent para tomar uma ação específica quando o evento PowerShell.Exiting ocorre.

Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
    Get-History | Export-Clixml $HOME\history.clixml
}

O parâmetro SupportEvent é adicionado para ocultar a subscrição ao 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.

Este exemplo cria uma assinatura para eventos da origem MyEventSource. 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..."
        $newEventSplat = @{
            SourceIdentifier = 'MyEventSource'
            MessageData      = ("{0} -  Work done..." -f (Get-Date))
        }
        New-Event @newEventSplat
    }
}
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 de trabalho 18. Start-Job criou ID de Trabalho 19. No exemplo nº 4, removemos a assinatura do evento e os trabalhos e inspecionamos o arquivo de log.

Esta é uma continuação do Exemplo 3. Neste exemplo, aguardamos 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 à subscrição do evento (ID do trabalho 18). A ID do trabalho 19 ainda está em execução e criando novos eventos. Usamos os cmdlets Job para parar o trabalho e remover os objetos de trabalho desnecessários. Get-Content exibe o conteúdo do arquivo de log.

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.

Não é possível transferir objetos para esse cmdlet.

Por padrão, esse cmdlet não retorna nenhuma saída.

Quando você usa o parâmetro Action, esse cmdlet retorna um objeto PSEventJob .

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.

Ao assinar o evento Exiting, os cmdlets que podem ser executados pelo parâmetro Action são limitados aos cmdlets nos 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 é fechado.

O mecanismo será considerado ocioso se não estiver executando um pipeline. O evento OnIdle é acionado quando o PowerShell está ocioso por 300 milissegundos (ms).