powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Register-EngineEvent



NAME
Register-EngineEvent

SYNOPSIS
Subscribes to events that are generated by the Windows PowerShell engine and by the New-Event cmdlet.

SYNTAX
Register-EngineEvent [-SourceIdentifier] [[-Action] ] [-Forward] [-MessageData ] [-
SupportEvent] []


DESCRIPTION
The Register-EngineEvent cmdlet subscribes to events that are generated by the Windows PowerShell engine and the Ne
w-Event cmdlet. Use the SourceIdentifier parameter to specify the event.

You can use this cmdlet to subscribe to the "Exiting" engine event and events generated by the New-Event cmdlet. Th
ese events are automatically added to your event queue in your session without subscribing. However, subscribing le
ts you forward the events, specify an action to respond to the events, and cancel the subscription.

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

When you subscribe to a event, an event subcriber is added to your session. To get the event subscribers in the ses
sion, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which delete
s the event subscriber from the session.


PARAMETERS
-Action
Specifies commands to handle the events. The commands in the Action run when an event is raised, instead of sen
ding 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-EngineEvent returns an event job object that represents that action. You c
an use the Job cmdlets to manage the event job.

Required? false
Position? 102
Default value None
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 False
Accept pipeline input? false
Accept wildcard characters? false

-MessageData
Specifies additional data associated with the event. The value of this parameter appears in the MessageData pro
perty of the event object.

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

-SourceIdentifier
Specifies the source identifier of the event to which you are subscribing. The source identifier must be unique
in the current session. This parameter is required.

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? true
Position? 101
Default value
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


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 input to Register-EngineEvent.


OUTPUTS
None or System.Management.Automation.PSEventJob
If you use the Action parameter, Register-EngineEvent returns a System.Management.Automation.PSEventJob object.
Otherwise, it does not generate any output.


NOTES


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>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s { Register-EngineEvent -sourceIdentifier ([System.Management.Automation.PsEngineE
vent]::Exiting) -forward }


Description
-----------
This command registers for a Windows PowerShell engine event on two remote computers.

The first command creates a PSSession on each of the remote computers.

The second command uses the Invoke-Command cmdlet to run the Register-EngineEvent command in the remote sessions.

The Register-EngineEvent command uses the SourceIdentifier parameter to identify the event. It uses the Forward par
ameter to forward the events from the remote session to the local session.





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

C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated -action { $processName | add-content pr
ocessLog.txt }

C:\PS> get-event

C:\PS> $results = $j | receive-job

C:\PS> unregister-event PowerShell.ProcessCreated


Description
-----------
This command shows how to use the Job cmdlets to manage the event job object that Register-EngineEvent returns when
you use the Action parameter.

An event job is managed just like any other Windows PowerShell job. For more information, see about_jobs. In this e
xample, the Receive-Job cmdlet is used to get the results of the job.

To delete the job from the session, use Remove-Job. To cancel your event subscription, use the Unregister-Event cmd
let. To delete the events in the event queue, use Remove-Event.






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