订阅由 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-EventSubscriberUnregister-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。






另请参阅




目录