Register-ObjectEvent
订阅由 Microsoft .NET Framework 对象生成的事件。
语法
Register-ObjectEvent
[-InputObject] <PSObject>
[-EventName] <String>
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
说明
cmdlet Register-ObjectEvent
订阅由本地计算机或远程计算机上的 .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:订阅远程计算机上的对象事件
此示例演示如何订阅远程计算机上的对象事件。 此示例使用脚本 Enable-ProcessCreationEvent
文件中定义的 ProcessCreationEvent.ps1
函数。 此示例中的所有计算机都可以使用此脚本。
# 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 }
第一个是在两台远程计算机上创建 PSSession 并将其保存在 变量中 $S
。 接下来,Invoke-Command
cmdlet 在 中的每个 PSSession 中$S
运行ProcessCreationEvent.ps1
脚本。 此操作在 Enable-ProcessCreationEvent
远程会话中创建 函数。
最后,我们在远程会话中运行 Enable-ProcessCreationEvent
函数。
函数包含一个Register-ObjectEvent
命令,该命令通过 ManagementEventWatcher 对象及其 EventArrived 事件订阅 Win32_Process 对象上的实例创建事件。
示例 4:在 PSEventJob 对象中使用动态模块
此示例演示如何在 PSEventJob 对象中使用动态模块,该对象是在事件注册中包含 操作 时创建的。 首先,创建并启用计时器对象,然后将计时器的间隔设置为 500 (毫秒) 。 cmdlet Register-ObjectEvent
注册计时器对象的 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
自动变量。 这些变量向 操作 脚本块提供有关 事件的信息。 有关详细信息,请参阅 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 参数创建的订阅,请使用 和 Unregister-Event
cmdlet 的 Get-EventSubscriber
Force 参数。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
输入
None
不能通过管道将 对象传递给 Register-ObjectEvent
。
输出
None or System.Management.Automation.PSEventJob
使用 Action 参数时, Register-ObjectEvent
返回 System.Management.Automation.PSEventJob 对象。 否则,将不生成任何输出。
备注
事件、事件订阅和事件队列仅存在于当前会话中。 如果关闭当前会话,将丢弃事件队列并取消事件订阅。