Register-ObjectEvent

Referência

Módulo:: Microsoft.PowerShell.Utility

Assina os eventos gerados por um objeto do Microsoft .NET Framework.

Syntax

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

Description

O Register-ObjectEvent cmdlet assina eventos gerados por objetos .NET no computador local ou em um computador remoto.

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.

Você pode usar os parâmetros de para especificar valores de propriedade dos Register-ObjectEvent eventos que podem ajudá-lo a identificar o evento na fila. Você também pode usar o parâmetro Action para especificar ações a serem executadas quando um evento inscrito é gerado e o parâmetro Forward para enviar eventos remotos para a fila de eventos na sessão local.

Quando subscreve um evento, um subscritor do 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: Inscrever-se em eventos quando um novo processo é iniciado

Este exemplo assina eventos gerados quando um novo processo é iniciado.

O comando usa o objeto ManagementEventWatcher para obter eventos EventArrives . Um objeto de consulta especifica que os eventos são eventos de criação de instância para a classe Win32_Process .

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"

Exemplo 2: Especificar uma ação para responder a um evento

Quando você especifica uma ação, os eventos gerados não são adicionados à fila de eventos. Em vez disso, a ação responde ao evento. Neste exemplo, quando um evento de criação de instância é gerado indicando que um novo processo é iniciado, um novo evento ProcessCreated é gerado.

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
$newEventArgs = @{
    SourceIdentifier = 'PowerShell.ProcessCreated'
    Sender = $Sender
    EventArguments = $EventArgs.NewEvent.TargetInstance
}
$Action = { New-Event @newEventArgs }
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action

Id   Name               PSJobTypeName   State       HasMoreData   Location   Command
--   ----               -------------   -----       -----------   --------   -------
 5   3db2d67a-efff-...                 NotStarted   False                    New-Event @newEventArgs

A ação usa as variáveis automáticas que $EventArgs são preenchidas $Sender apenas para ações de evento.

O Register-ObjectEvent comando retorna um objeto de trabalho que representa a ação, que é executado como um trabalho em segundo plano. Você pode usar os cmdlets Job, como Get-Job e Receive-Job, para gerenciar o trabalho em segundo plano. Para obter mais informações, veja about_Jobs.

Exemplo 3: Inscrever-se em eventos de objeto em computadores remotos

Este exemplo mostra como se inscrever em eventos de objeto em computadores remotos. Este exemplo usa a Enable-ProcessCreationEvent função definida no ProcessCreationEvent.ps1 arquivo de script. Este script está disponível para todos os computadores no exemplo.

# ProcessCreationEvent.ps1
function  Enable-ProcessCreationEvent {
    $queryParameters = "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1),
        "TargetInstance isa 'Win32_Process'"
    $Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters

    $objectEventArgs = @{
        Input = New-Object System.Management.ManagementEventWatcher $Query
        EventName = 'EventArrived'
        SourceIdentifier = 'WMI.ProcessCreated'
        MessageData = 'Test'
        Forward = $True
    }
    Register-ObjectEvent @objectEventArgs
}

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
Invoke-Command -Session $S { Enable-ProcessCreationEvent }

O primeiro nós criamos PSSessions em dois computadores remotos e os salvamos na $S variável. Em seguida, o Invoke-Command cmdlet executa o ProcessCreationEvent.ps1 script em cada uma das PSSessions em $S. Esta ação cria a Enable-ProcessCreationEvent função nas sessões remotas. Finalmente, executamos a Enable-ProcessCreationEvent função nas sessões remotas.

A função inclui um Register-ObjectEvent comando que assina eventos de criação de instância no objeto Win32_Process por meio do objeto ManagementEventWatcher e seu evento EventArrive .

Exemplo 4: Usar o módulo dinâmico no objeto PSEventJob

Este exemplo mostra como usar o módulo dinâmico no objeto PSEventJob que é criado quando você inclui uma ação em um registro de evento. Primeiro, criamos e habilitamos um objeto de temporizador e, em seguida, definimos o intervalo do temporizador para 500 (milissegundos). O Register-ObjectEvent cmdlet registra o evento Elapsed do objeto timer. O objeto PSEventJob é salvo na $Job variável e também está disponível na propriedade Action do assinante do evento. Para obter mais informações, consulte Get-EventSubscriber.

Sempre que o intervalo do temporizador decorre, um evento é gerado e a ação é executada. Nesse caso, o Get-Random cmdlet gera um número aleatório entre 0 e 100 e o salva na $Random variável.

$Timer = New-Object Timers.Timer
$Timer.Interval = 500
$Timer.Enabled = $True
$objectEventArgs = @{
    InputObject = $Timer
    EventName = 'Elapsed'
    SourceIdentifier = 'Timer.Random'
    Action = {$Random = Get-Random -Min 0 -Max 100}
}
$Job = Register-ObjectEvent @objectEventArgs
$Job | Format-List -Property *
& $Job.module {$Random}
& $Job.module {$Random}

State         : Running
Module        : __DynamicModule_53113769-31f2-42dc-830b-8749325e28d6
StatusMessage :
HasMoreData   : True
Location      :
Command       : $Random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 47b5ec9f-bfe3-4605-860a-4674e5d44ca8
Id            : 7
Name          : Timer.Random
ChildJobs     : {}
PSBeginTime   : 6/27/2019 10:19:06 AM
PSEndTime     :
PSJobTypeName :
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}
60
47

O PSEventJob tem uma propriedade Module que contém um módulo de script dinâmico que implementa a ação. Usando o operador de chamada (&), invocamos o comando no módulo para exibir o valor da $Random variável.

Para obter mais informações sobre módulos, consulte about_Modules.

Parâmetros

-Action

Especifica os comandos para manipular o evento. 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 Action pode incluir as $Eventvariáveis , $EventSubscriber, $Sender, $EventArgse $Args automáticas. Essas variáveis fornecem informações sobre o evento para o bloco de script de ação . Para obter mais informações, consulte about_Automatic_Variables.

Quando você especifica uma ação, Register-ObjectEvent retorna um objeto de trabalho de evento que representa essa ação. Você pode usar os cmdlets Job para gerenciar o trabalho de evento.

Type:	ScriptBlock
Position:	101
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-EventName

Especifica o evento ao qual você está se inscrevendo.

O valor desse parâmetro deve ser o nome do evento que o objeto .NET expõe. Por exemplo, a classe ManagementEventWatcher tem eventos chamados EventArrived e Stopped. Para localizar o nome do evento de um evento, use o Get-Member cmdlet.

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Forward

Indica que o cmdlet envia eventos para esta assinatura para uma sessão remota. Use esse parâmetro quando estiver se registrando para 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

-InputObject

Especifica o objeto .NET que gera os eventos. Insira uma variável que contenha o objeto ou digite um comando ou expressão que obtenha o objeto.

Type:	PSObject
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxTriggerCount

Especifica o número máximo de vezes que um evento pode ser acionado.

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

-MessageData

Especifica quaisquer dados adicionais a serem associados a esta assinatura de evento. O valor desse parâmetro aparece na propriedade MessageData de todos os eventos associados a esta assinatura.

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

-SourceIdentifier

Especifica um nome selecionado para a assinatura. O nome selecionado deve ser exclusivo na sessão atual. O valor padrão é o GUID que o PowerShell atribui.

O valor desse parâmetro aparece no valor da propriedade SourceIdentifier do objeto do assinante e em todos os objetos de evento associados a essa assinatura.

Type:	String
Position:	100
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SupportEvent

Indica que o cmdlet oculta a assinatura do evento. Use esse parâmetro quando a assinatura atual fizer parte de um mecanismo de registro de eventos mais complexo e não puder ser descoberta independentemente.

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

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

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.

Share via

Register-ObjectEvent

Syntax

Description

Exemplos

Exemplo 1: Inscrever-se em eventos quando um novo processo é iniciado

Exemplo 2: Especificar uma ação para responder a um evento

Exemplo 3: Inscrever-se em eventos de objeto em computadores remotos

Exemplo 4: Usar o módulo dinâmico no objeto PSEventJob

Parâmetros

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Entradas

Saídas

Notas

Comentários

Recursos adicionais

Share via

Register-ObjectEvent

Syntax

Description

Exemplos

Exemplo 1: Inscrever-se em eventos quando um novo processo é iniciado

Exemplo 2: Especificar uma ação para responder a um evento

Exemplo 3: Inscrever-se em eventos de objeto em computadores remotos

Exemplo 4: Usar o módulo dinâmico no objeto PSEventJob

Parâmetros

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Entradas

Saídas

Notas

Ligações Relacionadas

Comentários

Recursos adicionais