订阅由 Windows PowerShell 引擎以及由 New-Event cmdlet 生成的事件。
语法
Register-EngineEvent [-SourceIdentifier] <string> [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]
说明
Register-EngineEvent cmdlet 订阅由 Windows PowerShell 引擎以及由 New-Event cmdlet 生成的事件。使用 SourceIdentifier 参数指定事件。
可以使用此 cmdlet 来订阅“Exiting”引擎事件以及由 New-Event cmdlet 生成的事件。这些事件将自动添加到会话中的事件队列,而无需订阅。但是,订阅允许您转发事件,指定操作来响应事件以及取消订阅。
当引发订阅的事件时,该事件将添加到会话中的事件队列。若要获取事件队列中的事件,请使用 Get-Event cmdlet。
订阅事件时,会向会话中添加一个事件订阅程序。若要获取会话中的事件订阅程序,请使用 Get-EventSubscriber cmdlet。若要取消订阅,请使用 Unregister-Event cmdlet,该 cmdlet 将从会话中删除事件订阅程序。
参数
-Action <scriptblock>
指定用于处理事件的命令。Action 中的命令在引发事件时运行,而不将事件发送到事件队列。用大括号 ({ }) 括起命令以形成脚本块。
Action 参数的值可以包含 $Event、$EventSubscriber、$Sender、$SourceEventArgs 和 $SourceArgs 自动变量,这些变量为 Action 脚本块提供有关事件的信息。有关详细信息,请参阅 about_Automatic_Variables。
指定操作时,Register-EngineEvent 会返回一个表示该操作的事件作业对象。可以使用 Job cmdlet 来管理事件作业。
是否为必需? |
false |
位置? |
102 |
默认值 |
无 |
是否接受管道输入? |
false |
是否接受通配符? |
false |
-Forward
将此订阅的事件发送到本地计算机上的会话。如果要在远程计算机或远程会话中注册事件,可使用此参数。
是否为必需? |
false |
位置? |
named |
默认值 |
False |
是否接受管道输入? |
false |
是否接受通配符? |
false |
-MessageData <psobject>
指定与事件关联的其他数据。此参数的值显示在事件对象的 MessageData 属性中。
是否为必需? |
false |
位置? |
named |
默认值 |
无 |
是否接受管道输入? |
false |
是否接受通配符? |
false |
-SourceIdentifier <string>
指定要订阅的事件的源标识符。该源标识符在当前会话中必须是唯一的。此参数是必需的。
此参数的值出现在订阅者对象以及与此订阅关联的所有事件对象的 SourceIdentifier 属性值中。
是否为必需? |
true |
位置? |
101 |
默认值 |
|
是否接受管道输入? |
false |
是否接受通配符? |
false |
-SupportEvent
隐藏事件订阅。在当前订阅是更复杂的事件注册机制的一部分并且不应单独发现时,可使用此参数。
若要查看或取消使用 SupportEvent 参数创建的订阅,请使用 Get-EventSubscriber 和 Unregister-Event cmdlet 的 Force 参数。
是否为必需? |
false |
位置? |
named |
默认值 |
False |
是否接受管道输入? |
false |
是否接受通配符? |
false |
<CommonParameters>
此 cmdlet 支持通用参数:-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。有关详细信息,请参阅 about_Commonparameters.
输入和输出
输入类型是指可通过管道传递给 cmdlet 的对象的类型。返回类型是指 Cmdlet 所返回对象的类型。
输入 |
None 不能通过管道将输入传递给 Register-EngineEvent。 |
输出 |
None 或 System.Management.Automation.PSEventJob 如果使用 Action 参数,则 Register-EngineEvent 返回 System.Management.Automation.PSEventJob 对象。否则,将不产生任何输出。 |
说明
事件、事件订阅和事件队列仅存在于当前会话中。如果关闭当前会话,将丢弃事件队列并取消事件订阅。
示例 1
C:\PS>$s = new-pssession -computername Server01, Server02 C:\PS> 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
C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated -action { $processName | add-content processLog.txt } C:\PS> get-event C:\PS> $results = $j | receive-job C:\PS> unregister-event PowerShell.ProcessCreated 说明 ----------- 此命令演示了如何使用 Job cmdlet 来管理当使用 Action 参数时 Register-EngineEvent 返回的事件作业对象。 可以像管理任何其他 Windows PowerShell 作业那样管理事件作业。有关详细信息,请参阅 about_jobs。在此示例中,使用 Receive-Job cmdlet 获取作业的结果。 若要从会话中删除作业,请使用 Remove-Job。若要取消事件订阅,请使用 Unregister-Event cmdlet。若要删除事件队列中的事件,请使用 Remove-Event。
另请参阅