Register-WmiEvent

Referência

Módulo:: Microsoft.PowerShell.Management

Inscreve-se em um evento WMI (Instrumentação de Gerenciamento do Windows).

Syntax

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 inscrito é gerado, ele é adicionado à fila de eventos em sua sessão local, mesmo que o evento ocorra 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 se inscrever em eventos em computadores remotos e para 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 é gerado.

Quando subscreve um evento, um subscritor do 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 CIM (Common Information Model), 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-WmiEvento , considere usar o cmdlet Register-CimIndicationEvent .

Exemplos

Exemplo 1: Inscrever-se em eventos gerados por uma classe

Este comando subscreve os eventos gerados pela classe Win32_ProcessStartTrace . Esta classe gera 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

Este comando usa uma consulta para se inscrever em Win32_process eventos de criação de instância.

$wmiParameters = @{
  Query = "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'"
  SourceIdentifier = "WMIProcess"
  MessageData = "Test 01"
  TimeOut = 500
}
Register-WmiEvent @wmiParameters

Exemplo 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, veja about_Jobs.

Exemplo 4: Registar-se para eventos num computador remoto

Este exemplo registra eventos no computador remoto Server01.

Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "Start" -Computername Server01
Get-Event -SourceIdentifier "Start"

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 local Get-Event .

Parâmetros

-Action

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 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 automáticas, 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 essa ação. Você pode usar os cmdlets que contêm o substantivo Job (os cmdlets Job ) para gerenciar o trabalho de evento.

Type:	ScriptBlock
Position:	101
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Class

Especifica o evento ao qual você está se inscrevendo. Insira a classe WMI que gera os eventos. Um parâmetro Class ou Query é necessário em cada comando.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ComputerName

Especifica o nome do computador no qual o comando é executado. A predefinição é o computador local.

Digite o nome 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.

Type:	String
Aliases:	Cn
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Credential

Especifica uma conta de usuário que tem permissão para executar essa ação. A predefinição é o utilizador atual.

Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential , como um Get-Credential gerado pelo cmdlet. Se você digitar um nome de usuário, esse cmdlet solicitará uma senha.

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Forward

Indica que esse cmdlet envia eventos para esta assinatura para a sessão no computador local. Use esse parâmetro quando estiver se registrando para eventos em um computador remoto ou em uma sessão remota.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxTriggerCount

Especifica a contagem máxima de gatilhos.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	PSObject
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Namespace

Especifica o namespace da classe WMI.

Type:	String
Aliases:	NS
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Query

Especifica uma consulta na WQL (WMI Query Language) que identifica a classe de evento WMI, como: select * from __InstanceDeletionEvent.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	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 Windows PowerShell atribui.

O valor desse parâmetro aparece no valor da propriedade SourceIdentifier do objeto assinante e de todos os objetos de evento associados a essa assinatura.

Type:	String
Position:	100
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SupportEvent

Indica que esse 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 for descoberta independentemente.

Para exibir ou cancelar uma assinatura que foi criada usando o parâmetro SupportEvent , especifique o parâmetro Force dos Get-EventSubscriber cmdlets e Unregister-Event .

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Timeout

Especifica quanto tempo o Windows PowerShell aguarda a conclusão desse comando.

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

Type:	Int64
Aliases:	TimeoutMSec
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas