Register-WmiEvent

Subscribes to a Windows Management Instrumentation (WMI) event. PowerShell reference

From the PowerShell reference 12 parameters

What it does

from the PowerShell reference, CC BY 4.0

Subscribes to a Windows Management Instrumentation (WMI) event. The Register-WmiEvent cmdlet subscribes to Windows Management Instrumentation (WMI) events on the local computer or on a remote computer. When the subscribed WMI event is raised, it is added to the event queue in your local session even if the event occurs on a remote computer. To get events in the event queue, use the Get-Event cmdlet. You can use the parameters of Register-WmiEvent to subscribe to events on remote computers and to specify the property values of the events that can help you identify the event in the queue. You can also use the Action parameter to specify actions to take when a subscribed event is raised. When you subscribe to an event, an event subscriber is added to your session. To get the event subscribers in the session, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which deletes the event subscriber from the session. New Common Information Model (CIM) cmdlets, introduced Windows PowerShell 3.0, perform the same tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) standards and with the CIM standard, which enables the cmdlets to use the same techniques to manage computers that run the Windows operating system and those that run other operating systems. Instead of using Register-WmiEvent, consider using the Register-CimIndicationEvent cmdlet.

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>]

Subscribe to events generated by a class

Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "ProcessStarted"Identify

Subscribe to creation events for a process

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

Identify

Use an action to respond to an event

$action = {
Get-History |
Where-Object { $_.CommandLine -like "Start-Process" } |
Export-CliXml "commandHistory.clixml"
}
Register-WmiEvent -Class Win32_ProcessStartTrace -SourceIdentifier ProcessStarted -Action $action

Identify

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

Identify

Its page in the reference: Register-WmiEvent.

Parameters

12 in the PowerShell reference

-ActionSpecifies commands that handle the events. The commands in the Action parameter run when an event is raised instead of sending the event to the event queue. Enclose the commands in braces ({}) to create a script block. The value of Action can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables. When you specify an action, Register-WmiEvent returns an event job object that represents that action. You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage the event job.

-ClassSpecifies the event to which you are subscribing. Enter the WMI class that generates the events. A Class or Query parameter is required in every command.

-ComputerNameSpecifies the name of the computer on which the command runs. The default is the local computer. This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.

-CredentialSpecifies a user account that has permission to perform this action. The default is the current user.

-ForwardIndicates that this cmdlet sends events for this subscription to the session on the local computer. Use this parameter when you are registering for events on a remote computer or in a remote session.

-MaxTriggerCountSpecifies the maximum trigger count.

-MessageDataSpecifies any additional data to be associated with this event subscription. The value of this parameter appears in the MessageData property of all events associated with this subscription.

-NamespaceSpecifies the namespace of the WMI class.

-QuerySpecifies a query in WMI Query Language (WQL) that identifies the WMI event class, such as: select * from __InstanceDeletionEvent.

-SourceIdentifierSpecifies a name that you select for the subscription. The name that you select must be unique in the current session. The default value is the GUID that Windows PowerShell assigns. The value of this parameter appears in the value of the SourceIdentifier property of the subscriber object and of all event objects associated with this subscription.

-SupportEventIndicates that this cmdlet hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and it should not be discovered independently. To view or cancel a subscription that was created by using the SupportEvent parameter, specify the Force parameter of the Get-EventSubscriber and Unregister-Event cmdlets.

-TimeoutSpecifies how long Windows PowerShell waits for this command to finish. The default value, 0 (zero), means that there is no time-out, and it causes Windows PowerShell to wait indefinitely.