Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Register-EngineEvent

Updated: October 17, 2013

Applies To: Windows PowerShell 4.0

Register-EngineEvent

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

Syntax

Parameter Set: Default
Register-EngineEvent [-SourceIdentifier] <String> [[-Action] <ScriptBlock> ] [-Forward] [-MessageData <PSObject> ] [-SupportEvent] [ <CommonParameters>]




Detailed Description

The Register-EngineEvent cmdlet subscribes to events that are generated by the Windows PowerShell engine and the New-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. These events are automatically added to your event queue in your session without subscribing. However, subscribing lets 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 queue, 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 session, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which deletes the event subscriber from the session.

Parameters

-Action<ScriptBlock>

Specifies 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, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).

When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.


Aliases

none

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 registering for events on a remote computer or in a remote session.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-MessageData<PSObject>

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


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-SourceIdentifier<String>

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.


Aliases

none

Required?

true

Position?

101

Default Value

none

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 the Get-EventSubscriber and Unregister-Event cmdlets.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • None

    You cannot pipe input to Register-EngineEvent.


Outputs

The output type is the type of the objects that the cmdlet emits.

  • 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 session, the event queue is discarded and the event subscription is canceled.

Examples

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

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

The first command creates a user-managed session ("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 parameter to forward the events from the remote session to the local session.


PS C:\> $s = New-PSSession -ComputerName Server01, Server02PS C:\>Invoke-Command -Session $s { Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward }

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

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 (http://go.microsoft.com/fwlink/?LinkID=113251). In this example, 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 cmdlet. To delete the events in the event queue, use Remove-Event.


PS C:\> $j = Register-EngineEvent -SourceIdentifier PowerShell.ProcessCreated -action { $ProcessName | Add-Content ProcessLog.txt }PS C:\>Get-EventPS C:\>$results = $j | Receive-JobPS C:\>Unregister-Event PowerShell.ProcessCreated

Related topics


Get-Event

Get-Job

New-Event

Receive-Job

Register-ObjectEvent

Register-WmiEvent

Remove-Event

Remove-Job

Unregister-Event

Wait-Event

Wait-Job



Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.