Register-ObjectEvent PowerShell Get-Help Output

This is the built-in help made by Microsoft for the command 'Register-ObjectEvent', in PowerShell version 2 - as retrieved from Windows version 'Microsoft® Windows Vista™ Ultimate ' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Subscribes to the events that are generated by a Microsoft .NET Framework object.

SYNTAX

Register-ObjectEvent [-InputObject] <psobject> [-EventName] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-Forward] [-Messag
eData <psobject>] [-SupportEvent] [<CommonParameters>]

Search powershellhelp.space

DESCRIPTION

The Register-ObjectEvent cmdlet subscribes to events that are generated by .NET Framework objects on the local computer or on a remote computer.

When the subscribed event is raised, it is added to the event queue in your session. To get events in the event queue, use the Get-Event cmdlet.

You can use the parameters of Register-ObjectEvent to specify property values of the events that can help you to identify the event in the queue.
You can also use the Action parameter to specify actions to take when a subscribed event is raised and the Forward parameter to send remote even
ts to the event queue in the local session.

When you subscribe to an event, an event subcriber is added to your session. To get the event subscribers in the session, use the Get-EventSubscr
iber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which deletes the event subscriber from the session.

RELATED LINKS

REMARKS

Examples

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

C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Proc
ess'"

C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query

C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived"

Description
-----------
This example subscribes to events generated when a new process starts.

The command uses the ManagementEventWatcher object to get EventArrived events. A query object specifies that the events are instance creation eve
nts for the Win32_Process class.

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

C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Proc
ess'"

C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query

C:\PS> $action = { New-Event "PowerShell.ProcessCreated" -Sender $sender -EventArguments $SourceEventArgs.NewEvent.TargetInstance }

C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventArrived" -action $action

Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
2 422cfe5a-65e... Running True New-Event "PowerShe...

Description
-----------
This example shows how to specify an action to respond to an event. When you specify an action, events that are raised are not added to the event
queue. Instead, the action responds to the event.

In this example, when an instance creation event is raised indicating that a new process is started, a new ProcessCreated event is raised.

The action uses the $Sender and $SourceEventArgs automatic variables which are populated only for event actions.

The Register-ObjectEvent command returns a job object that represents the action, which runs as a background job. You can use the Job cmdlets, su
ch as Get-Job and Receive-Job, to manage the background job.

For more information, see about_Jobs.

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

C:\PS>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s -filepath ProcessCreationEvent.ps1

C:\PS> invoke-command -session $s { get-event }

# ProcessCreationEvent.ps1

function Enable-ProcessCreationEvent
{
$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", `
(New-Object TimeSpan 0,0,1), `
"TargetInstance isa 'Win32_Process'"
$processWatcher = New-Object System.Management.ManagementEventWatcher $query

$identifier = "WMI.ProcessCreated"
Register-ObjectEvent -input $processWatcher -eventName "EventArrived" `
-sourceIdentifier $identifier -messageData "Test" -forward
}
}

EnableProcessCreationEvent

Description
-----------
This example shows how to subscribe to object events on remote computers.

The first command creates PSSessions on two remote computers and saves them in the $s variable.

The second command uses the FilePath parameter of the Invoke-Command cmdlet to run the ProcessCreationEvent.ps1 script in the each of the PSSessi
ons in $s.

The script includes a Register-ObjectEvent command that subscribes to instance creation events on the Win32_Process object through the Management
EventWatcher object and its EventArrived event.

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

C:\PS>$timer = New-Object Timers.Timer

C:\PS> $timer.Interval = 500

C:\PS> $job = Register-ObjectEvent -inputObject $timer -eventName Elapsed -sourceIdentifier Timer.Random -Action {$random = Get-Random -Min 0 -Ma
x 100}

C:\PS> $job.gettype().fullname
System.Management.Automation.PSEventJob

C:\PS> $job | format-list -property *

State : Running
Module : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0
StatusMessage :
HasMoreData : True
Location :
Command : $random = Get-Random -Min 0 -Max 100
JobStateInfo : Running
Finished : System.Threading.ManualResetEvent
InstanceId : 88944290-133d-4b44-8752-f901bd8012e2
Id : 1
Name : Timer.Random
ChildJobs : {}
...

C:\PS> $timer.Enabled = $true

C:\PS> & $job.module {$random}
60

C:\PS> & $job.module {$random}
47

Description
-----------
This example shows how to use the dynamic module in the PSEventJob object that is created when you include an Action in a event registration.

The first command uses the New-Object cmdlet to create a timer object. The second command sets the interval of the timer to 500 (milliseconds).

The third command uses the Register-ObjectEvent cmdlet to register the Elapsed event of the timer object. The command includes an action that han
dles the event. Whenever the timer interval elapses, an event is raised and the commands in the action run. In this case, the Get-Random cmdlet g
enerates a random number between 0 and 100 and saves it in the $random variable.

When you use an Action parameter in a Register-ObjectEvent command, the command returns a PSEventJob object that represents the action. The comma
nd saves the job object in the $job variable.

The PSEventJob object that the Register-ObjectEvent cmdlet returns is also available in the Action property of the event subscriber. For more inf
ormation, see Get-EventSubscriber.

The fourth command shows that the $job variable contains a PSEventJob object. The fifth command uses the Format-List cmdlet to display all of the
properties of the PSEventJob object in a list.

The PSEventJob has a Module property that contains a dynamic script module that implements the action.

The sixth command enables the timer.

The remaining commands use the call operator (&) to invoke the command in the module and display the value of the $random variable. You can use t
he call operator to invoke any command in a module, including commands that are not exported. In this case, the commands show the random number t
hat is being generated when the Elapsed event occurs.

For more information about modules, see about_Modules.