Compartilhar via

Register-EngineEvent

  • Referência
Módulo:
Microsoft.PowerShell.Utility

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 os eventos e eventos do mecanismo OnIdle ou Exiting 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 você se inscreve em 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.

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 .

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: executar 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 sai, 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: Create e assinar um evento definido pelo usuário

Este exemplo cria uma assinatura para eventos do MyEventSource de origem. Essa é 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 A ID do Trabalho 19 foi criada. 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 limpo trabalhos

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 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 pararem o trabalho e removermos 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 em chaves ({}) para criar um bloco de script.

O valor do parâmetro Action pode incluir as $Eventvariáveis automáticas , $EventSubscriber, $Sender, $EventArgse $Args , que fornecem informações sobre o evento para o bloco 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 é 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 PSEngineEventPowerShell.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 fizer parte de um mecanismo de registro de eventos mais complexo e ela não for descoberta independentemente.

Para exibir ou cancelar uma assinatura que foi criada com o parâmetro SupportEvent , adicione o parâmetro Force aos Get-EventSubscriber cmdlets ou Unregister-Event .

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

Você não pode 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 .

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 inscrição 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).

Observação

Quando PSReadLine está em uso, o evento OnIdle é acionado quando ReadKey() o tempo limite atinge o tempo limite (sem digitar em 300 ms). 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, o comportamento de OnIdle foi alterado para sinalizar o evento somente se houver um ReadKey() tempo limite e o buffer de edição atual estiver vazio.