Register-ObjectEvent

Referência

Módulo:: Microsoft.PowerShell.Utility

Assina os eventos que são gerados por um objeto do Microsoft .NET Framework.

Sintaxe

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 Register-ObjectEvent para especificar valores de propriedade dos 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 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.

Exemplos

Exemplo 1: Assinar eventos quando um novo processo for iniciado

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

O comando usa o objeto ManagementEventWatcher para obter eventos EventArrived . 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

Ao especificar uma ação, eventos que são criados 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 foi 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 e $EventArgs que 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 é executada 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, consulte about_Jobs.

Exemplo 3: Assinar eventos de objeto em computadores remotos

Este exemplo mostra como assinar eventos de objetos em computadores remotos. Este exemplo usa a Enable-ProcessCreationEvent função definida no ProcessCreationEvent.ps1 arquivo de script. Esse 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 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 no $S. Essa ação cria a Enable-ProcessCreationEvent função nas sessões remotas. Por fim, 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 EventArrived .

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 expira, 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 $Random valor da 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, , $EventArgs$Sender, e $Args automatic. Essas variáveis 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-ObjectEvent retorna um objeto de trabalho de evento que representa essa ação. É possível utilizar os cmdlets Job para gerenciar o trabalho de eventos.

Tipo:	ScriptBlock
Cargo:	101
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-EventName

Especifica o evento que você está assinando.

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 de um evento, use o Get-Member cmdlet.

Tipo:	String
Cargo:	1
Valor padrão:	None
Obrigatório:	True
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Forward

Indica que o cmdlet envia eventos para essa assinatura para uma sessão remota. Utilize esse parâmetro ao registrar eventos em um computador remoto ou em uma sessão remota.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-InputObject

Especifica o objeto .NET que gera os eventos. Digite uma variável que contém o objeto ou digite um comando ou uma expressão que obtém o objeto.

Tipo:	PSObject
Cargo:	0
Valor padrão:	None
Obrigatório:	True
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-MaxTriggerCount

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

Tipo:	Int32
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-MessageData

Especifica dados adicionais a serem associados essa assinatura do evento. O valor desse parâmetro é exibido na propriedade MessageData de todos os eventos associados a essa assinatura.

Tipo:	PSObject
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-SourceIdentifier

Especifica um nome para a assinatura selecionada. O nome que você selecionar 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 de assinante e de todos os objetos de evento associados a essa assinatura.

Tipo:	String
Cargo:	100
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	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 evento mais complexo e não deve 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 e Unregister-Event .

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

Entradas

None

Você não pode canalizar objetos para esse 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.

Compartilhar via

Register-ObjectEvent

Sintaxe

Description

Exemplos

Exemplo 1: Assinar eventos quando um novo processo for iniciado

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

Exemplo 3: Assinar 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

Observações

Recursos adicionais

Compartilhar via

Register-ObjectEvent

Sintaxe

Description

Exemplos

Exemplo 1: Assinar eventos quando um novo processo for iniciado

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

Exemplo 3: Assinar 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

Observações

Links Relacionados

Recursos adicionais