Register-EngineEvent
订阅由 PowerShell 引擎和 New-Event cmdlet 生成的事件。
语法
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] 说明
cmdlet Register-EngineEvent 订阅由 PowerShell 引擎和 New-Event cmdlet 生成的事件。 使用 SourceIdentifier 参数来指定事件。
可以使用此 cmdlet 订阅 cmdlet 生成的 New-Event OnIdle 或退出引擎事件和事件。 这些事件会自动添加到会话中的事件队列，而无需订阅。 但是，订阅可以转发事件、指定操作来响应事件，以及取消订阅。
订阅事件时，事件订阅服务器将添加到会话。 若要获取会话中的事件订阅程序，请使用 Get-EventSubscriber cmdlet。 若要取消订阅，请使用 Unregister-Event cmdlet，该 cmdlet 将从会话中删除事件订阅程序。
当引发已订阅的事件时，它将添加到你的会话中的事件队列。 若要获取事件队列中的事件，请使用 Get-Event cmdlet。
示例
示例 1：在远程计算机上注册 PowerShell 引擎事件
此示例在两台远程计算机上注册 PowerShell 引擎事件。
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}New-PSSession 在每台远程计算机上 (PSSession) 创建用户管理的会话。cmdlet Invoke-Command 在远程会话中运行 Register-EngineEvent 命令。
Register-EngineEvent 使用 SourceIdentifier 参数来标识事件。 Forward 参数告知引擎将事件从远程会话转发到本地会话。
示例 2：Exiting 事件发生时执行指定的操作
此示例演示如何在发生 PowerShell.Exiting 事件时运行 Register-EngineEvent 以执行特定操作。
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}添加 SupportEvent 参数以隐藏事件订阅。 当 PowerShell 退出时，在本例中，退出会话的命令历史记录将导出用户目录中的 $Home XML 文件。
示例 3：Create并订阅用户定义的事件
此示例为源 MyEventSource 中的事件创建订阅。 这是一个任意源，我们将使用它来监视作业的进度。 Register-EngineEvent 用于创建订阅。 Action 参数的脚本块将事件数据记录到文本文件中。
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..."
New-Event -SourceIdentifier MyEventSource -Message ("{0} - Work done..." -f (Get-Date))
}
}
Start-Sleep -seconds 4
Get-EventSubscriber
Get-Job
SubscriptionId : 12
SourceObject :
EventName :
SourceIdentifier : MyEventSource
Action : System.Management.Automation.PSEventJob
HandlerDelegate :
SupportEvent : False
ForwardEvent : False
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Running True …
19 TestJob BackgroundJob Running True localhost …Register-EngineEvent 已创建的作业 ID 18。 Start-Job 已创建的作业 ID 19。 在示例 #4 中，我们删除事件订阅和作业，然后检查日志文件。
示例 4：注销事件并清理作业
这是示例 3 的延续。 在此示例中，我们等待 10 秒，以便发生多个事件。 然后，取消注册事件订阅。
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...cmdlet Unregister-Event 停止与事件订阅关联的作业， (作业 ID 18) 。 作业 ID 19 仍在运行并创建新事件。 我们使用 作业 cmdlet 停止作业并删除不需要的作业对象。 Get-Content 显示日志文件的内容。
参数
-Action
指定用于处理事件的命令。 Action 中的命令在引发事件时运行，而不是将该事件发送到事件队列。 将命令括在大括号 ({}) 以创建脚本块。
Action 参数的值可以包括 $Event、、$EventSubscriber$Sender、 $EventArgs和 $Args 自动变量，它们向 Action 脚本块提供有关事件的信息。 有关详细信息，请参阅 about_Automatic_Variables。
指定操作时， Register-EngineEvent 返回表示该操作的事件作业对象。 你可以使用 Job cmdlet 来管理事件作业。
| Type: | ScriptBlock |
| Position: | 101 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Forward
指示该 cmdlet 将此订阅的事件发送到本地计算机上的会话。 如果要在远程计算机或远程会话中注册事件，可使用此参数。
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaxTriggerCount
指定为事件订阅执行操作的最大次数。
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MessageData
指定与事件关联的其他数据。 此参数的值显示在事件对象的 MessageData 属性中。
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SourceIdentifier
指定要订阅的事件的源标识符。 源标识符必须在当前会话中唯一。 此参数是必需的。
此参数的值显示在订阅服务器对象以及与此订阅关联的所有事件对象的 SourceIdentifier 属性值中。
值特定于事件的源。 这可以是创建的用于 cmdlet 的 New-Event 任意值。 PowerShell 引擎支持 PSEngineEvent 值 PowerShell.Exiting 和 PowerShell.OnIdle。
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SupportEvent
指示该 cmdlet 隐藏事件订阅。 在当前订阅是更复杂的事件注册机制的一部分并且不应单独发现它时，添加此参数。
若要查看或取消使用 SupportEvent 参数创建的订阅，请将 Force 参数添加到 Get-EventSubscriber 或 Unregister-Event cmdlet。
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
输入
None
不能通过管道将输入传递给 Register-EngineEvent。
输出
None or System.Management.Automation.PSEventJob
如果使用 Action 参数， Register-EngineEvent 则返回 System.Management.Automation.PSEventJob 对象。 否则，将不生成任何输出。
备注
事件、事件订阅和事件队列仅存在于当前会话中。 如果关闭当前会话，将丢弃事件队列并取消事件订阅。
订阅 Exiting 事件时，可由 Action 参数执行的 cmdlet 仅限于 Microsoft.PowerShell.Core 和 Microsoft.PowerShell.Utility 模块中的 cmdlet。 仅当会话在 PowerShell 控制下退出时，才会触发退出事件。 当主机应用程序或终端窗口关闭时，不会触发 事件。
如果引擎未运行管道，则会将其视为空闲状态。 当 PowerShell 已空闲 300 毫秒 (ms) 时，将触发 OnIdle 事件。
注意
使用 PSReadLine 时，当超时 (未键入 300 毫秒) 时ReadKey()，将触发 OnIdle 事件。 当用户正在编辑命令行时，可以发出事件信号，例如，用户正在阅读帮助以确定要使用的参数。 从 PSReadLine 2.2.0-beta4 开始， OnIdle 行为已更改为仅当存在 ReadKey() 超时且当前编辑缓冲区为空时发出事件信号。