powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Register-WmiEvent



NAME
Register-WmiEvent

SYNOPSIS
Subscribes to a Windows Management Instrumentation (WMI) event.

SYNTAX
Register-WmiEvent [-Class] [[-SourceIdentifier] ] [[-Action] ] [-ComputerName >] [-Credential ] [-Forward] [-MessageData ] [-Namespace ] [-SupportEvent] [-Timeou
t ] []

Register-WmiEvent [-Query] [[-SourceIdentifier] ] [[-Action] ] [-ComputerName >] [-Credential ] [-Forward] [-MessageData ] [-Namespace ] [-SupportEvent] [-Timeou
t ] []


DESCRIPTION
The Register-WmiEvent cmdlet subscribes to 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 occ
urs 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 prope
rty values of the events that can help you to identify the event in the queue. You can also use the Action paramete
r 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 s
ession, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which dele
tes the event subscriber from the session.


PARAMETERS
-Action
Specifies commands that handle the events. The commands in the Action parameter run when an event is raised ins
tead 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 $Sou
rceArgs automatic variables, which provide information about the event to the Action script block. For more inf
ormation, 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.

Required? false
Position? 102
Default value The event is added to the event queue.
Accept pipeline input? false
Accept wildcard characters? false

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

Required? true
Position? 1
Default value None
Accept pipeline input? false
Accept wildcard characters? false

-ComputerName
Specifies a remote computer. The default is the local computer. Enter a NetBIOS name, an IP address, or a fully
qualified domain name.

Required? false
Position? named
Default value Local computer
Accept pipeline input? false
Accept wildcard characters? false

-Credential
Specifies a user account that has permission to perform this action. Type a user name, such as "User01" or "Dom
ain01\User01". Or, enter a PSCredential object, such as one from the Get-Credential cmdlet. If you type a user
name, you will be prompted for a password.

Required? false
Position? named
Default value The credentials of the current user
Accept pipeline input? false
Accept wildcard characters? false

-Forward []
Sends events for this subscription to the session on the local computer. Use this parameter when you are regist
ering for events on a remote computer or in a remote session.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

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

Required? false
Position? named
Default value None. The MessageData property is NULL.
Accept pipeline input? false
Accept wildcard characters? false

-Namespace
Specifies the namespace of the WMI class.

Required? false
Position? named
Default value None
Accept pipeline input? false
Accept wildcard characters? false

-Query
Specifies a query in WMI Query Language (WQL) that identifies the WMI event class, such as "select * from __Ins
tanceDeletionEvent".

Required? true
Position? 1
Default value None
Accept pipeline input? false
Accept wildcard characters? false

-SourceIdentifier
Specifies a name that you select for the subscription. The name that you select must be unique in the current s
ession. 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.

Required? false
Position? 101
Default value GUID
Accept pipeline input? false
Accept wildcard characters? false

-SupportEvent []
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 with the SupportEvent parameter, use the Force parameter of t
he Get-EventSubscriber and Unregister-Event cmdlets.

Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false

-Timeout
Determines how long Windows PowerShell waits for this command to complete.

The default value, 0 (zero), means that there is no time-out, and it causes Windows PowerShell to wait indefini
tely.

Required? false
Position? named
Default value 0
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
None
You cannot pipe objects to Register-WmiEvent.


OUTPUTS
None
This cmdlet does not generate any output.


NOTES


To use this cmdlet in Windows Vista or a later version of Windows, start Windows PowerShell with the "Run as ad
ministrator" option.

Events, event subscriptions, and the event queue exist only in the current session. If you close the current se
ssion, the event queue is discarded and the event subscription is canceled.


-------------------------- EXAMPLE 1 --------------------------

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


Description
-----------
This command subscribes to the events generated by the Win32_ProcessStartTrace class. This class raises an event wh
enever a process starts.





-------------------------- EXAMPLE 2 --------------------------

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


Description
-----------
This command uses a query to subscribe to Win32_process instance creation events.





-------------------------- EXAMPLE 3 --------------------------

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

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

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


Description
-----------
This example shows how to use an action to respond to an event. In this case, when a process starts, any Start-Proc
ess commands in the current session are written to an XML file.

When you use the Action parameter, Register-WmiEvent returns a background job that represents the event action. You
can use the Job cmdlets, such as Get-Job and Receive-Job, to manage the event job.

For more information, see about_Jobs.





-------------------------- EXAMPLE 4 --------------------------

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

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


Description
-----------
This example registers for events on the Server01 remote computer.

WMI returns the events to the local computer and stores them in the event queue in the current session. To retrieve
the events, run a local Get-Event command.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=135245
Register-ObjectEvent
Register-EngineEvent
Unregister-Event
Get-Event
New-Event
Remove-Event
Wait-Event