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 |
The event is added to the event queue. |
|
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 |
Local computer |
|
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 |
The credentials of the current user |
|
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 |
None. The MessageData property is 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 |
None Não é possível enviar objetos por pipe para Register-WmiEvent. |
|
Saídas |
None 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.
See Also