Register-ObjectEvent

参考

模块:: Microsoft.PowerShell.Utility

订阅由 Microsoft .NET Framework 对象生成的事件。

语法

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

说明

Register-ObjectEvent cmdlet 订阅本地计算机或远程计算机上的 .NET 对象所生成的事件。

当引发已订阅的事件时，它将添加到你的会话中的事件队列。若要获取事件队列中的事件，请使用 Get-Event cmdlet。

可以使用 Register-ObjectEvent 的参数指定事件的属性值，它们可帮助你标识队列中的事件。你还可以使用 Action 参数指定当引发了订阅的事件时要执行的操作，并使用 Forward 参数将远程事件发送到本地会话中的事件队列中。

订阅事件时，会向会话中添加一个事件订阅服务器。若要获取会话中的事件订阅者，请使用 Get-EventSubscriber cmdlet。若要取消订阅，请使用 Unregister-Event cmdlet，该 cmdlet 将从会话中删除事件订阅者。

示例

示例 1：在新进程启动时订阅事件

此示例订阅新进程启动时生成的事件。

该命令使用 ManagementEventWatcher 对象获取 EventArrived 事件。一个查询对象指定这些事件是 Win32_Process 类的实例创建事件。

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"

示例 2：指定用于响应事件的操作

当你指定某项操作时，引发的事件不会添加到事件队列。相反，操作将响应该事件。在此示例中，当引发了指示新进程已启动的实例创建事件时，将引发一个新的 ProcessCreated 事件。

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
$newEventArgs = @{
    SourceIdentifier = 'PowerShell.ProcessCreated'
    Sender = $Sender
    EventArguments = $EventArgs.NewEvent.TargetInstance
}
$Action = { New-Event @newEventArgs }
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action

Id   Name               PSJobTypeName   State       HasMoreData   Location   Command
--   ----               -------------   -----       -----------   --------   -------
 5   3db2d67a-efff-...                 NotStarted   False                    New-Event @newEventArgs

该操作使用 $Sender 和 $EventArgs 自动变量，仅为事件操作填充这些变量。

Register-ObjectEvent 命令返回表示该操作的作业对象，该操作作为后台作业运行。可以使用作业 cmdlet（例如 Get-Job 和 Receive-Job）来管理后台作业。有关详细信息，请参阅 about_Jobs。

示例 3：订阅远程计算机上的对象事件

此示例演示如何订阅远程计算机上的对象事件。此示例使用 ProcessCreationEvent.ps1 脚本文件中定义的 Enable-ProcessCreationEvent 函数。此脚本可用于示例中的所有计算机。

# ProcessCreationEvent.ps1
function  Enable-ProcessCreationEvent {
    $queryParameters = "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1),
        "TargetInstance isa 'Win32_Process'"
    $Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters

    $objectEventArgs = @{
        Input = New-Object System.Management.ManagementEventWatcher $Query
        EventName = 'EventArrived'
        SourceIdentifier = 'WMI.ProcessCreated'
        MessageData = 'Test'
        Forward = $True
    }
    Register-ObjectEvent @objectEventArgs
}

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
Invoke-Command -Session $S { Enable-ProcessCreationEvent }

首先，我们在两台远程计算机上创建 PSSessions，并将其保存到 $S 变量中。接下来，Invoke-Command cmdlet 在 $S 的每个 PSSessions 中运行 ProcessCreationEvent.ps1 脚本。此操作在远程会话中创建 Enable-ProcessCreationEvent 函数。最后，我们在远程会话中运行 Enable-ProcessCreationEvent 函数。

该函数包括一个 Register-ObjectEvent 命令，此命令通过 ManagementEventWatcher 对象及其 EventArrived 事件订阅 Win32_Process 对象上的实例创建事件。

示例 4：使用 PSEventJob 对象中的动态模块

此示例展示了如何使用当在事件注册中包括 Action 时创建的 PSEventJob 对象中的动态模块。首先我们创建并启用一个计时器对象，然后将计时器的间隔设置为 500（毫秒）。 Register-ObjectEvent cmdlet 注册计时器对象的 Elapsed 事件。 PSEventJob 对象保存在 $Job 变量中，也可在事件订阅者的 Action 属性中使用。有关详细信息，请参阅 Get-EventSubscriber。

每当计时器间隔过去时，就会引发一个事件并执行操作。在这种情况下，Get-Random cmdlet 生成一个介于 0 和 100 之间的随机数字，并将其保存在 $Random 变量中。

$Timer = New-Object Timers.Timer
$Timer.Interval = 500
$Timer.Enabled = $True
$objectEventArgs = @{
    InputObject = $Timer
    EventName = 'Elapsed'
    SourceIdentifier = 'Timer.Random'
    Action = {$Random = Get-Random -Min 0 -Max 100}
}
$Job = Register-ObjectEvent @objectEventArgs
$Job | Format-List -Property *
& $Job.module {$Random}
& $Job.module {$Random}

State         : Running
Module        : __DynamicModule_53113769-31f2-42dc-830b-8749325e28d6
StatusMessage :
HasMoreData   : True
Location      :
Command       : $Random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 47b5ec9f-bfe3-4605-860a-4674e5d44ca8
Id            : 7
Name          : Timer.Random
ChildJobs     : {}
PSBeginTime   : 6/27/2019 10:19:06 AM
PSEndTime     :
PSJobTypeName :
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}
60
47

PSEventJob 具有一个 Module 属性，此属性包含实现该操作的动态脚本模块。我们使用调用运算符 (&) 调用模块中的命令来显示 $Random 变量的值。

若要详细了解模块，请参阅 about_Modules。

参数

-Action

指定用于处理事件的命令。 Action 中的命令在引发事件时运行，而不是将事件发送到事件队列时运行。用大括号 ({ }) 括起命令以形成脚本块。

Action 参数的值可以包含 $Event、$EventSubscriber、$Sender、$EventArgs 和 $Args 自动变量。这些变量向 Action 脚本块提供有关事件的信息。有关详细信息，请参阅 about_Automatic_Variables。

如果你指定某个操作，则 Register-ObjectEvent 返回一个表示该操作的事件作业对象。你可以使用 Job cmdlet 来管理事件作业。

Type:	ScriptBlock
Position:	101
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-EventName

指定要订阅的事件。

此参数的值必须是 .NET 对象公开的事件的名称。例如，ManagementEventWatcher 类具有名为 EventArrived 和 Stopped 的事件。若要查找事件的名称，请使用 Get-Member cmdlet。

Type:	String
Position:	1
Default value:	None
Required:	True
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

-InputObject

指定生成事件的 .NET 对象。输入包含该对象的变量，或键入获取该对象的命令或表达式。

Type:	PSObject
Position:	0
Default value:	None
Required:	True
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

指定你为订阅选择的名称。你选择的名称必须在当前会话中唯一。默认值为 PowerShell 分配的 GUID。

此参数的值出现在订阅者对象以及与此订阅关联的所有事件对象的 SourceIdentifier 属性值中。

Type:	String
Position:	100
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SupportEvent

指示该 cmdlet 隐藏事件订阅。如果当前订阅是更复杂的事件注册机制的一部分并且不应当被单独发现，请使用此参数。

若要查看或取消使用 SupportEvent 参数创建的订阅，请使用 Get-EventSubscriber 和 Unregister-Event cmdlet 的 Force 参数。

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 对象。

备注

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

Register-ObjectEvent

语法

说明

示例

示例 1：在新进程启动时订阅事件

示例 2：指定用于响应事件的操作

示例 3：订阅远程计算机上的对象事件

示例 4：使用 PSEventJob 对象中的动态模块

参数

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

输入

输出

备注

反馈

其他资源

Register-ObjectEvent

语法

说明

示例

示例 1：在新进程启动时订阅事件

示例 2：指定用于响应事件的操作

示例 3：订阅远程计算机上的对象事件

示例 4：使用 PSEventJob 对象中的动态模块

参数

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

输入

输出

备注

相关链接

反馈

其他资源