CmdID / PowerShell / Cmdlets / Register
Register-EngineEvent
Subscribes to events that are generated by the PowerShell engine and by the New-Event cmdlet. PowerShell reference
From the PowerShell reference 6 parameters
What it does
Subscribes to events that are generated by the PowerShell engine and by the New-Event cmdlet. The Register-EngineEvent cmdlet subscribes to events that are generated by the PowerShell engine and the New-Event cmdlet. Use the SourceIdentifier parameter to specify the event. You can use this cmdlet to subscribe to the OnIdle or Exiting engine events and events generated by the New-Event cmdlet. These events are automatically added to the 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 you subscribe to an 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. 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.
Register-EngineEvent [-SourceIdentifier] <String> [[-Action] <ScriptBlock>] [-MessageData <PSObject>] [-SupportEvent] [-Forward] [-MaxTriggerCount <Int32>] [<CommonParameters>]Register a PowerShell engine event on remote computers
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PSEngineEvent]::Exiting) -Forward
}IdentifyTake a specified action when the Exiting event occurs
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $HOME\history.clixml
}IdentifyCreate and subscribe to a user-defined event
Register-EngineEvent -SourceIdentifier MyEventSource -Action {
"Event: {0}" -f $Event.MessageData | Out-File C:\temp\MyEvents.txt -Append
}
Start-Job -Name TestJob -ScriptBlock {
while ($true) {
Register-EngineEvent -SourceIdentifier MyEventSource -Forward
Start-Sleep -Seconds 2
"Doing some work..."
$newEventSplat = @{
SourceIdentifier = 'MyEventSource'
MessageData = ("{0} - Work done..." -f (Get-Date))
}
New-Event @newEventSplat
}
}
Start-Sleep -Seconds 4
Get-EventSubscriber
Get-JobIdentifyUnregister events and clean up jobs
PS> Start-Sleep -Seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Stopped False …
19 TestJob BackgroundJob Running True localhost …
PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM - Work done...
Event: 2/18/2020 2:36:21 PM - Work done...
Event: 2/18/2020 2:36:23 PM - Work done...
Event: 2/18/2020 2:36:25 PM - Work done...
Event: 2/18/2020 2:36:27 PM - Work done...
Event: 2/18/2020 2:36:29 PM - Work done...
Event: 2/18/2020 2:36:31 PM - Work done...IdentifyIts page in the reference: Register-EngineEvent.
Parameters
-ActionSpecifies 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 scriptblock.
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 scriptblock. For more information, see
about_Automatic_Variables.
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.-ForwardIndicates 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.-MaxTriggerCountSpecifies the maximum number of times that the action is executed for the event subscription.-MessageDataThis parameter is part of the base class for all Event cmdlets. The Register-EngineEvent doesn't use this parameter. Any data passed to this parameter is ignored.-SourceIdentifierSpecifies 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.
The value is specific to the source of the event. This can be an arbitrary value you created to use with the New-Event cmdlet. The PowerShell engine supports the PSEngineEvent values PowerShell.Exiting and PowerShell.OnIdle.-SupportEventIndicates 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.