Register-EngineEvent

  • 参考
模块:
Microsoft.PowerShell.Utility

订阅由 PowerShell 引擎和 New-Event cmdlet 生成的事件。

语法

Register-EngineEvent
        [-SourceIdentifier] <String>
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

说明

Register-EngineEvent cmdlet 订阅由 PowerShell 引擎和 New-Event cmdlet 生成的事件。 使用 SourceIdentifier 参数来指定事件。

可以使用此 cmdlet 订阅 OnIdle 或 Exiting 引擎事件和由 New-Event cmdlet 生成的事件。 这些事件将自动添加到你的会话中的事件队列，而无需订阅。 但是，订阅可以转发事件、指定操作来响应事件，以及取消订阅。

订阅事件时，会向会话中添加一个事件订阅服务器。 若要获取会话中的事件订阅者，请使用 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)。Invoke-Command cmdlet 在远程会话中运行 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 退出时，退出会话中的命令历史记录将被导出到一个 XML 文件，该文件将被置于用户的 $HOME 目录中。

示例 3：创建和订阅用户定义的事件

此示例创建针对 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...

Unregister-Event cmdlet 将停止与事件订阅关联的作业（作业 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 属性值中。

该值特定于事件的来源。 这可以是你创建以用于 New-Event cmdlet 的任意值。 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

不能通过管道将对象传递给此 cmdlet。

输出

None

默认情况下，此 cmdlet 不返回任何输出。

PSEventJob

使用 Action 参数时，此 cmdlet 返回一个 PSEventJob 对象。

备注

事件、事件订阅和事件队列仅存在于当前会话中。 如果关闭当前会话，将丢弃事件队列并取消事件订阅。

订阅 Exiting 事件时，Action 参数可执行的 cmdlet 仅限于 Microsoft.PowerShell.Core 和 Microsoft.PowerShell.Utility 模块中的 cmdlet。 仅当会话在 PowerShell 的控制下退出会话时，才会触发 Exiting 事件。 当主机应用程序或终端窗口关闭时，不会触发该事件。

如果引擎未运行管道，则被视为处于空闲状态。 当 PowerShell 空闲达到 300 毫秒 (ms) 时，将触发 OnIdle 事件。

注意

当正在使用 PSReadLine 时，OnIdle 事件会在 ReadKey() 超时（300 毫秒内无键入）时触发。 当用户正进行命令行编辑时，该事件可能会发出信号，例如，用户正在阅读帮助来确定要使用的参数。 从 PSReadLine 2.2.0-beta4 开始，OnIdle 行为更改为仅当存在 ReadKey() 超时且当前编辑缓冲区为空时，事件才会发出信号。