Register-ObjectEvent

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，从会话中删除事件订阅者。

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

该命令使用 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"

指定操作时，不会将引发的事件添加到事件队列。 相反，该操作会响应事件。 在此示例中，当引发实例创建事件指示启动新进程时，将引发新的 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。

此示例演示如何订阅远程计算机上的对象事件。 此示例使用在 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 }

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

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

此示例演示如何在事件注册中包含 操作 时创建的 PSEventJob 对象中使用动态模块。 首先创建并启用计时器对象，然后将计时器的间隔设置为 500（毫秒）。 Register-ObjectEvent cmdlet 注册计时器对象的 已用 事件。 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。

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 有关详细信息，请参阅 about_CommonParameters。

不能用管道将对象传送到此 cmdlet。

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

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

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