Register-WmiEvent

Subscribe to a WMI event.

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

Key:
   -Action scriptblock
Commands to handle the events. The commands in the Action 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 the Action parameter can include the $Event, $EventSubscriber, $Sender, $SourceEventArgs, and $SourceArgs automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables. Register-ObjectEvent will return an event job object that represents the action. -Class string 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. -ComputerName string Specify a remote computer. Enter a NetBIOS name, an IP address, or a fully qualified domain name. The default is the local computer. -Credential PSCredential A user account that has permission to perform this action. Type a user name, such as "User23" or "Domain64\User21". Or, enter a PSCredential object, such as one from Get-Credential. If you type a user name, you will be prompted for a password. -Forward Send events for this subscription to the session on the local computer. Use this parameter when registering for events on a remote computer or in a remote session. -InputObject psobject
The .NET Framework object that generates the events. Enter a variable that contains the object, or type a command or expression that gets the object. This parameter is required. -MessageData psobject Additional data associated with the event. The value of this parameter appears in the MessageData property of the event object. -Namespace string The namespace of the WMI class. -Query string A query in WMI Query Language (WQL) that identifies the WMI event class, such as "select * from __InstanceDeletionEvent". -SourceIdentifier string
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 PowerShell assigns. The value of this parameter appears in the SourceIdentifier property of the subscriber object and of all event objects associated with this subscription. -SupportEvent Hide 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 with -SupportEvent, use the -Force parameter of Get-EventSubscriber and Unregister-Event. -Timeout Int64 How long PowerShell should wait for this command to complete. The default value, 0 (zero), means no time-out/wait indefinitely. CommonParameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable, -OutBuffer -OutVariable.

Register-WmiEvent subscribes to WMI events on the local computer or on a remote computer.

When the subscribed 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 Get-Event. Subscribing allows you to forward the events and/or specify an action to respond to the events.

To cancel a subscription, use Unregister-Event

Examples

Subscribe to the events generated by the Win32_ProcessStartTrace class. This class raises an event whenever a process starts:

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

Use an action to respond to an event - when a process starts, any Start-Process commands in the current session are written to an XML file:

PS C:\> $action = { get-history | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }
PS C:\> register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted" -action $action

Register for events on the Server64, then run a local Get-Event to retrieve the events:

PS C:\> register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "Start" -computername Server64
PS C:\> get-event -sourceIdentifier "Start"

“A beauty is a woman you notice; a charmer is one who notices you” ~ Adlai E. Stevenson

Related:

Register-EngineEvent - Subscribe to PowerShell events
Register-ObjectEvent - Subscribe to .NET events
Get-Event - Get events in the event queue


© Copyright SS64.com 1999-2014
Some rights reserved