Windows PowerShell command on Get-command 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] [-MaxTriggerCount ]

[-MessageData ] [-SupportEvent] []

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 subscriber 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

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

-Forward []

Indicates that the cmdlet 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. Required? false Position? named Default value False Accept pipeline input? False Accept wildcard characters? false

-MaxTriggerCount

Specifies the max trigger count.

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. Required? false Position? named Default value None 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 property 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. Supported EngineEvent values include PowerShell.Exiting, PowerShell.OnIdle, and PowerShell.OnScriptBlockInvoke. Required? true Position? 100 Default value None Accept pipeline input? False Accept wildcard characters? false

-SupportEvent []

Indicates that the cmdlet hides the event subscription. Add 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, add the Force parameter to

the Get-EventSubscriber or 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, PipelineVariable, and OutVariable. For more information, see about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

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

session, the event queue is discarded and the event subscription is canceled.

Example 1: Register a PowerShell engine event on remote computers

PS C:\>$S = New-PSSession -ComputerName "Server01, Server02"

PS C:\>Invoke-Command -Session $S { Register-EngineEvent -SourceIdentifier

([System.Management.Automation.PsEngineEvent]::Exiting) -Forward }

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.

Example 2: Take a specified action when the Exiting event occurs

PS C:\>Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {

Get-History | Export-Clixml $Home\history.clixml

}

This command shows how to run Register-EngineEvent to take a specific action when the PowerShell.Exiting event

occurs. The SupportEvent parameter is added to hide the event subscription. When Windows PowerShell exits, in this case, the command history from the exiting session is exported in XML format to a file name and path in the user's

$Home directory.