Register-ObjectEvent
Assina os eventos gerados por um objeto do Microsoft .NET Framework.
Sintaxe
Default (Predefinição)
Register-ObjectEvent
[-InputObject] <PSObject>
[-EventName] <String>
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Description
O cmdlet Register-ObjectEvent 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 cmdlet Get-Event.
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 subscreve um evento, um subscritor do evento é adicionado à sua sessão. Para obter os subscritores 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.
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
$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 $Sender e $EventArgs automáticas que são preenchidas apenas para ações de evento.
O comando Register-ObjectEvent 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, consulte sobre_empregos.
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 função Enable-ProcessCreationEvent definida no arquivo de script ProcessCreationEvent.ps1. 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 variável $S. Em seguida, o cmdlet Invoke-Command executar o script ProcessCreationEvent.ps1 em cada uma das PSSessions no $S. Esta ação cria a função Enable-ProcessCreationEvent nas sessões remotas.
Finalmente, executamos a função Enable-ProcessCreationEvent nas sessões remotas.
A função inclui um comando Register-ObjectEvent 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 do $Job 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 cmdlet Get-Random gera um número aleatório entre 0 e 100 e o salva na variável $Random.
$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 variável $Random.
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 variáveis automáticas $Event, $EventSubscriber, $Sender, $EventArgse $args. Essas variáveis fornecem informações sobre o evento para o bloco de script Action. Para obter mais informações, consulte sobre_Variáveis_Automáticas.
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 a tarefa de evento.
Propriedades dos parâmetros
| Tipo: | ScriptBlock |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 101 |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 do Get-Member.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 1 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | PSObject |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-MaxTriggerCount
Especifica o número máximo de vezes que um evento pode ser acionado.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | PSObject |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 subscriber e de todos os objetos de evento associados a essa assinatura.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 100 |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 criada com o parâmetro
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
CommonParameters
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.
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.
