Register-WmiEvent

Artigo
10/30/2009

Assina a um evento WMI (Instrumentação de Gerenciamento do Windows).

Sintaxe

Register-WmiEvent [-Class] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Register-WmiEvent [-Query] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Descrição

O cmdlet Register-WmiEvent assina eventos WMI no computador local ou em um computador remoto.

Quando o evento WMI assinado é gerado, ele é adicionado à fila de eventos na sessão local, mesmo que o evento ocorra em um computador remoto. Para obter eventos na fila de eventos, use o cmdlet Get-Event.

Você pode usar os parâmetros de Register-WmiEvent para assinar eventos em computadores remotos e para especificar os valores de propriedades dos eventos que podem ajudar a identificar o evento na fila. Também é possível usar o parâmetro Action para especificar ações a serem tomadas quando um evento assinado é gerado.

Ao assinar um evento, um assinante de evento é adicionado à sessão. Para obter os assinantes 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.

Parâmetros

-Action <scriptblock>

Especifica comandos que manipulam os eventos. Os comandos no parâmetro Action são executados quando um evento é gerado, em vez de enviar o evento à fila de eventos. Coloque o comando entre chaves ( { } ) para criar um bloco de scripts.

O valor do parâmetro Action pode incluir as variáveis automáticas $Event, $EventSubscriber, $Sender, $SourceEventArgs e $SourceArgs, que fornecem informações sobre o evento para o bloco de script Action. Para obter mais informações, consulte about_Automatic_Variables.

Quando você especifica uma ação, Register-WmiEvent retorna um objeto de trabalho de evento que representa a ação. É possível usar os cmdlets que contêm o nome Job (os cmdlets Job) para gerenciar o trabalho do evento.

Necessário?	false
Posição?	102
Valor padrão	O evento é adicionado à fila de eventos.
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Class <string>

Especifica o evento que você está assinando. Insira a classe WMI que gera os eventos. Um parâmetro Class ou Query é obrigatório em cada comando.

Necessário?	true
Posição?	1
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ComputerName <string>

Especifica um computador remoto. O padrão é o computador local. Insira um nome NetBIOS, um endereço IP ou um nome de domínio totalmente qualificado.

Necessário?	false
Posição?	named
Valor padrão	Computador local
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Credential <PSCredential>

Especifica uma conta de usuário com permissão para executar essa ação. Digite um nome de usuário, como “User01” ou “Domain01\User01”. Ou insira um objeto PSCredential, como o retornado pelo cmdlet Get-Credential. Uma senha será solicitada após a digitação do nome do usuário.

Necessário?	false
Posição?	named
Valor padrão	As credenciais do usuário atual
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Forward

Envia eventos desta assinatura para a sessão no computador local. Use este parâmetro quando estiver registrando-se para eventos em um computador remoto ou em uma sessão remota.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-MessageData <psobject>

Especifica qualquer dado adicional a ser associado a esta inscrição de evento. O valor desse parâmetro aparece na propriedade MessageData de todos os eventos associados à assinatura.

Necessário?	false
Posição?	named
Valor padrão	Nenhum. A propriedade MessageData é NULL.
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Namespace <string>

Especifica o namespace da classe WMI.

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Query <string>

Especifica uma consulta na linguagem WQL que identifica a classe do evento WMI, como "select * de __InstanceDeletionEvent".

Necessário?	true
Posição?	1
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-SourceIdentifier <string>

Especifica um nome que você seleciona para a assinatura. O nome que você selecionar deverá 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 à assinatura.

Necessário?	false
Posição?	101
Valor padrão	GUID
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-SupportEvent

Oculta a assinatura do evento. Use este parâmetro quando a assinatura atual fizer parte de um mecanismo de Registro de eventos mais complexo e não precisar ser descoberta de forma independente.

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

Necessário?	false
Posição?	named
Valor padrão	False
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Timeout <Int64>

Determina quanto tempo o Windows PowerShell aguarda para que este comando seja concluído.

O valor padrão, 0 (zero), significa que não há tempo de espera e isso faz com que o Windows PowerShell aguarde indefinidamente.

Necessário?	false
Posição?	named
Valor padrão	0
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas

Nenhum

Não é possível enviar objetos por pipe para Register-WmiEvent.

Saídas

Nenhum

Este cmdlet não gera nenhuma saída.

Observações

Para usar este cmdlet no Windows Vista ou em uma versão mais recente do Windows, inicie o Windows PowerShell com a opção "Executar como administrador".

Eventos, assinaturas de eventos e a fila de eventos só existem na sessão atual. Se você fechar a sessão atual, a fila de eventos será descartada e a assinatura de evento será cancelada.

Exemplo 1

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted"

Descrição
-----------
Esse comando assina os eventos gerados pela classe Win32_ProcessStartTrace. Essa classe gera um evento sempre que um processo é iniciado.

Exemplo 2

C:\PS>register-wmiEvent -query "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'" -sourceIdentifier "WMIProcess" -messageData "Test 01" -timeout 500

Descrição
-----------
Esse comando usa uma consulta para assinar eventos de criação de instância Win32_process.

Exemplo 3

C:\PS>$action = { get-history | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }

C:\PS> register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted" -action $action

Id    Name            State      HasMoreData   Location  Command
--    ----            -----      -----------   --------  -------
1     ProcessStarted  NotStarted False                   get-history | where {...

Descrição
-----------
Este exemplo mostra como usar uma ação para responder a um evento. Nesse caso, quando um processo é iniciado, todos os comandos Start-Process na sessão atual são gravados em um arquivo XML. 

Quando você usa o parâmetro Action, Register-WmiEvent retorna um trabalho em segundo plano que representa a ação do evento. É possível usar os cmdlets Job, como Get-Job e Receive-Job, para gerenciar o trabalho do evento.

Para obter mais informações, consulte about_Jobs.

Exemplo 4

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "Start" -computername Server01 

C:\PS> get-event -sourceIdentifier "Start"

Descrição
-----------
Este exemplo registra eventos no computador remoto Server01. 

O WMI retorna os eventos para o computador local e os armazena na fila de eventos na sessão atual. Para recuperar os eventos, execute um comando Get-Event local.

Compartilhar via