Register-EngineEvent
订阅由 Windows PowerShell 引擎和 New-Event cmdlet 生成的事件。
语法
Default (默认值)
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
说明
Register-EngineEvent cmdlet 订阅由 Windows PowerShell 引擎和 New-Event cmdlet 生成的事件。 使用 SourceIdentifier 参数指定事件。
可以使用此 cmdlet 订阅 New-Event cmdlet 生成的退出引擎事件和事件。 这些事件会自动添加到会话中的事件队列，而无需订阅。 但是，订阅允许转发事件、指定响应事件的操作以及取消订阅。
当引发已订阅的事件时，它将添加到你的会话中的事件队列。 若要获取事件队列中的事件，请使用 Get-Event cmdlet。
当您订阅一个事件时，一个事件订阅者将被添加到您的当前会话中。 若要在会话中获取事件订阅者，请使用 Get-EventSubscriber cmdlet。 若要取消订阅，请使用 Unregister-Event cmdlet，从会话中删除事件订阅服务器。
示例
示例 1：在远程计算机上注册 PowerShell 引擎事件
PS C:\> $S = New-PSSession -ComputerName "Server01, Server02"
PS C:\> Invoke-Command -Session $S { Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward }
此命令在两台远程计算机上注册 Windows PowerShell 引擎事件。
第一个命令在每个远程计算机上创建用户管理的会话（PSSession）。
第二个命令使用 Invoke-Command cmdlet 在远程会话中运行 Register-EngineEvent 命令。
Register-EngineEvent 命令使用 SourceIdentifier 参数来标识事件。 它使用 Forward 参数将事件从远程会话转发到本地会话。
示例 2：发生退出事件时执行指定的操作
PS C:\> Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}
此命令演示如何运行 Register-EngineEvent，以在发生 PowerShell.Exiting 事件时执行特定操作。 添加了 SupportEvent 参数以隐藏事件订阅。 当 Windows PowerShell 退出时，在这种情况下，退出会话中的命令历史记录以 XML 格式导出到用户的$Home目录中的文件名和路径。
参数
-Action
指定用于处理事件的命令。 Action 中的命令在引发事件时运行，而不是将事件发送到事件队列。 将命令括在大括号 （{ }） 中以创建脚本块。
Action 参数的值可以包括$Event、$EventSubscriber、$Sender、$EventArgs和$Args自动变量，这些变量向操作脚本块提供有关事件的信息。 有关详细信息，请参阅about_Automatic_Variables（https://go.microsoft.com/fwlink/?LinkID=113212）。
指定操作时，Register-EngineEvent 返回表示该操作的事件作业对象。 你可以使用 Job cmdlet 来管理事件作业。
参数属性
| 类型: | ScriptBlock |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | 101 |
| 必需: | False |
| 来自管道的值: | False |
| 来自管道的值（按属性名称）: | False |
| 来自剩余参数的值: | False |
-Forward
指示该 cmdlet 将此订阅的事件发送到本地计算机上的会话。 在远程计算机或远程会话中注册事件时，请使用此参数。
参数属性
| 类型: | SwitchParameter |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | Named |
| 必需: | False |
| 来自管道的值: | False |
| 来自管道的值（按属性名称）: | False |
| 来自剩余参数的值: | False |
-MaxTriggerCount
指定最大触发器计数。
Action 参数的值可以包括$Event、$EventSubscriber、$Sender、$EventArgs和$Args自动变量，这些变量向操作脚本块提供有关事件的信息。 有关详细信息，请参阅about_Automatic_Variables（https://go.microsoft.com/fwlink/?LinkID=113212）。
指定操作时，Register-EngineEvent 返回表示该操作的事件作业对象。 你可以使用 Job cmdlet 来管理事件作业。
参数属性
| 类型: | Int32 |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | Named |
| 必需: | False |
| 来自管道的值: | False |
| 来自管道的值（按属性名称）: | False |
| 来自剩余参数的值: | False |
-MessageData
指定与事件关联的其他数据。 此参数的值显示在事件对象的 MessageData 属性中。
参数属性
| 类型: | PSObject |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | Named |
| 必需: | False |
| 来自管道的值: | False |
| 来自管道的值（按属性名称）: | False |
| 来自剩余参数的值: | False |
-SourceIdentifier
指定要订阅的事件的源标识符。 源标识符在当前会话中必须是唯一的。 此参数是必需的。
此参数的值显示在订阅服务器对象的 SourceIdentifier 属性和与此订阅关联的所有事件对象的值中。
支持的 EngineEvent 值包括 PowerShell.Exiting、PowerShell.OnIdle 和 PowerShell.OnScriptBlockInvoke。
参数属性
| 类型: | String |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | 100 |
| 必需: | True |
| 来自管道的值: | False |
| 来自管道的值（按属性名称）: | False |
| 来自剩余参数的值: | False |
-SupportEvent
指示该 cmdlet 隐藏事件订阅。 当当前订阅是更复杂的事件注册机制的一部分并且不应独立发现时添加此参数。
若要查看或取消使用 SupportEvent 参数创建的订阅，请将 Force 参数添加到 Get-EventSubscriber 或 Unregister-Event cmdlet。
参数属性
| 类型: | SwitchParameter |
| 默认值: | None |
| 支持通配符: | False |
| 不显示: | False |
参数集
(All)
| Position: | Named |
| 必需: | False |
| 来自管道的值: | False |
| 来自管道的值（按属性名称）: | False |
| 来自剩余参数的值: | False |
CommonParameters
此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 有关详细信息，请参阅 about_CommonParameters。
输入
None
不能通过管道将输入传递给 Register-EngineEvent。
输出
None or System.Management.Automation.PSEventJob
如果使用 Action 参数，Register-EngineEvent 将返回 System.Management.Automation.PSEventJob 对象。 否则，它不会生成任何输出。
备注
事件、事件订阅和事件队列仅存在于当前会话中。 如果关闭当前会话，事件队列将被丢弃，事件订阅也将被取消。