Register-WmiEvent
Assina um evento de WMI (Instrumentação de Gerenciamento do Windows).
Sintaxe
Register-WmiEvent
[-Namespace <String>]
[-Credential <PSCredential>]
[-ComputerName <String>]
[-Class] <String>
[-Timeout <Int64>]
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Register-WmiEvent
[-Namespace <String>]
[-Credential <PSCredential>]
[-ComputerName <String>]
[-Query] <String>
[-Timeout <Int64>]
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Description
O Register-WmiEvent cmdlet assina eventos WMI (Instrumentação de Gerenciamento do Windows) no computador local ou em um computador remoto.
Quando o evento WMI assinado é gerado, ele é adicionado à fila de eventos de sua sessão local, mesmo se o evento ocorrer em um computador remoto. Para obter eventos na fila de eventos, use o Get-Event cmdlet.
Você pode usar os parâmetros de Register-WmiEvent para assinar eventos em computadores remotos e especificar os 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 for gerado.
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.
Os novos cmdlets do Common Information Model (CIM), introduzidos no Windows PowerShell 3.0, executam as mesmas tarefas que os cmdlets WMI. Os cmdlets CIM estão em conformidade com os padrões WS-Management (WSMan) e com o padrão CIM, que permite que os cmdlets usem as mesmas técnicas para gerenciar computadores que executam o sistema operacional Windows e aqueles que executam outros sistemas operacionais. Em vez de usar Register-WmiEvent, considere usar o cmdlet Register-CimIndicationEvent .
Exemplos
Exemplo 1: Assinar eventos gerados por uma classe
Esse comando assina os eventos gerados pela classe Win32_ProcessStartTrace . Esta classe dispara um evento sempre que um processo é iniciado.
Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "ProcessStarted"Exemplo 2: Inscrever-se em eventos de criação para um processo
Esse comando usa uma consulta para assinar eventos de criação de instância Win32_process.
$wmiParameters = @{
Query = "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'"
SourceIdentifier = "WMIProcess"
MessageData = "Test 01"
TimeOut = 500
}
Register-WmiEvent @wmiParametersExemplo 3: Usar uma ação para responder a um evento
Este exemplo mostra como usar uma ação para responder a um evento. Nesse caso, quando um processo é iniciado, todos os Start-Process comandos na sessão atual são gravados em um arquivo XML.
$action = { Get-History | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }
Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "ProcessStarted" -Action $action
Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
1 ProcessStarted NotStarted False get-history | where {...Quando você usa o parâmetro Action , Register-WmiEvent retorna um trabalho em segundo plano que representa a ação do evento. Você pode usar os cmdlets Job , como Get-Job e Receive-Job, para gerenciar o trabalho de evento.
Para obter mais informações, consulte about_Jobs.
Exemplo 4: Registrar-se para eventos em um computador remoto
Este exemplo registra eventos no computador remoto Server01.
Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "Start" -Computername Server01
Get-Event -SourceIdentifier "Start"WMI retorna os eventos ao computador local e os armazena na fila de eventos da sessão atual. Para recuperar os eventos, execute um comando local Get-Event .
Parâmetros
-Action
Especifica comandos que lidam com os eventos. Os comandos no parâmetro Action 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 de Action pode incluir as $Eventvariáveis , $EventSubscriber, $Sender, $EventArgs, e $Args automatic, que fornecem informações sobre o evento para o bloco de script Action . Para obter mais informações, confira about_Automatic_Variables.
Quando você especifica uma ação, Register-WmiEvent retorna um objeto de trabalho de evento que representa essa ação. Você pode usar os cmdlets que contêm o substantivo Job (os cmdlets Job ) para gerenciar o trabalho de evento.
| Tipo: | ScriptBlock |
| Cargo: | 101 |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Class
Especifica o evento que você está assinando. Insira a classe WMI que gera os eventos. Um parâmetro Class ou Query é necessário em cada comando.
| Tipo: | String |
| Cargo: | 0 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-ComputerName
Especifica o nome do computador no qual o comando é executado. O padrão é o computador local.
Digite o nome da NetBIOS, um endereço IP ou um nome de domínio totalmente qualificado do computador. Para especificar o computador local, digite o nome do computador, um ponto (.) ou localhost.
Esse parâmetro não depende da comunicação remota do Windows PowerShell. Você pode usar o parâmetro ComputerName mesmo que o computador não esteja configurado para executar comandos remotos.
| Tipo: | String |
| Aliases: | Cn |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Credential
Especifica uma conta de usuário que tem permissão para executar esta ação. O padrão é o usuário atual.
Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential , como um gerado pelo Get-Credential cmdlet. Se você digitar um nome de usuário, esse cmdlet solicitará uma senha.
| Tipo: | PSCredential |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Forward
Indica que esse 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.
| Tipo: | SwitchParameter |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-MaxTriggerCount
Especifica a contagem máxima de gatilhos.
| 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 aparece 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 |
-Namespace
Especifica o namespace da classe de WMI.
| Tipo: | String |
| Aliases: | NS |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Query
Especifica uma consulta em WQL (WMI Query Language) que identifica a classe de evento WMI, como: select * from __InstanceDeletionEvent.
| Tipo: | String |
| Cargo: | 0 |
| Valor padrão: | None |
| Obrigatório: | True |
| 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 Windows 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 esse cmdlet oculta a assinatura do evento. Utilize esse parâmetro quando a assinatura atual faz parte de um mecanismo de registro de evento mais complexo e não deve ser descoberto independentemente.
Para exibir ou cancelar uma assinatura criada usando o parâmetro SupportEvent , especifique 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 |
-Timeout
Especifica quanto tempo o Windows PowerShell aguarda para que esse comando seja concluído.
O valor padrão, 0 (zero), significa que não há nenhum tempo limite, e faz com que o Windows PowerShell aguarde indefinidamente.
| Tipo: | Int64 |
| Aliases: | TimeoutMSec |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
Entradas
None
Não é possível transferir objetos para esse cmdlet.
Saídas
None
Este cmdlet não gera saída.
Observações
Para usar esse cmdlet no Windows Vista ou em uma versão posterior do sistema operacional Windows, inicie o Windows PowerShell usando a opção Executar como administrador.
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.
