PowerShell Logo Small

Register-EngineEvent



This is the built-in help made by Microsoft for the command 'Register-EngineEvent', in PowerShell version 4 - as retrieved from Windows version 'Microsoft Windows 8.1 Enterprise' 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 events that are generated by the Windows PowerShell engine and by the New-Event cmdlet.

SYNTAX


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



Search powershellhelp.space

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 qu
eue 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.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=294001
Get-Event
Get-Job
New-Event
Receive-Job
Register-ObjectEvent
Register-WmiEvent
Remove-Event
Remove-Job
Unregister-Event
Wait-Event
Wait-Job

REMARKS

<

Examples


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

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 sessio
n to the local session.








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

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



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 exam
ple, 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 R
emove-Event.