Register-WmiEvent

参考

模块:: Microsoft.PowerShell.Management

订阅 Windows Management Instrumentation (WMI) 事件。

语法

Register-WmiEvent
        [-Namespace <String>]
        [-Credential <PSCredential>]
        [-ComputerName <String>]
        [-Class] <String>
        [-Timeout <Int64>]
        [[-SourceIdentifier] <String>]
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

Register-WmiEvent
        [-Namespace <String>]
        [-Credential <PSCredential>]
        [-ComputerName <String>]
        [-Query] <String>
        [-Timeout <Int64>]
        [[-SourceIdentifier] <String>]
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

说明

Register-WmiEvent cmdlet 订阅本地计算机或远程计算机上的 Windows Management Instrumentation (WMI) 事件。

当引发订阅的 WMI 事件时，会将该事件添加到本地会话的事件队列中，即使该事件是在远程计算机上发生的也是如此。若要获取事件队列中的事件，请使用 Get-Event cmdlet。

可以使用 Register-WmiEvent 的参数订阅远程计算机上的事件，并可指定这些事件的属性值，这有助于在队列中标识这些事件。此外，你还可以使用 Action 参数指定引发订阅的事件时要执行的操作。

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

Windows PowerShell 3.0 中引入的新通用信息模型 (CIM) cmdlet 可执行与 WMI cmdlet 相同的任务。 CIM cmdlet 符合 WS-Management (WSMan) 标准和 CIM 标准，从而使得这些 cmdlet 可以使用相同的技术来管理运行 Windows 操作系统的计算机以及运行其他操作系统的计算机。请不要使用 Register-WmiEvent，而是考虑使用 Register-CimIndicationEvent cmdlet。

示例

示例 1：订阅类生成的事件

此命令订阅由 Win32_ProcessStartTrace 类生成的事件。只要进程启动，此类就会引发一个事件。

Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "ProcessStarted"

示例 2：订阅进程的创建事件

此命令使用一个查询订阅 Win32_process 实例创建事件。

$wmiParameters = @{
  Query = "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'"
  SourceIdentifier = "WMIProcess"
  MessageData = "Test 01"
  TimeOut = 500
}
Register-WmiEvent @wmiParameters

示例 3：使用用于响应事件的操作

此示例说明如何使用操作来响应事件。在本例中，当进程启动时，当前会话中的任何 Start-Process 命令都会写入一个 XML 文件中。

$action = { Get-History | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }
Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "ProcessStarted" -Action $action

Id    Name            State      HasMoreData   Location  Command
--    ----            -----      -----------   --------  -------
1     ProcessStarted  NotStarted False                   get-history | where {...

使用 Action 参数时，Register-WmiEvent 会返回一个表示事件操作的后台作业。可以使用 Job cmdlet（例如 Get-Job 和 Receive-Job）来管理事件作业。

有关详细信息，请参阅 about_Jobs。

示例 4：在远程计算机上注册事件

此示例注册远程计算机 Server01 上的事件。

Register-WmiEvent -Class 'Win32_ProcessStartTrace' -SourceIdentifier "Start" -Computername Server01
Get-Event -SourceIdentifier "Start"

WMI 将这些事件返回到本地计算机并将其存储在当前会话的事件队列中。若要检索这些事件，请运行本地 Get-Event 命令。

参数

-Action

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

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

指定操作时，Register-WmiEvent 会返回一个表示该操作的事件作业对象。可以使用包含 Job 名词的 cmdlet (Job cmdlet) 来管理事件作业。

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

-Class

指定要订阅的事件。请输入用于生成这些事件的 WMI 类。每个命令中都需要 Class 或 Query 参数。

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

-ComputerName

指定要在其上运行命令的计算机的名称。默认为本地计算机。

键入计算机的 NetBIOS 名称、IP 地址或完全限定的域名。若要指定本地计算机，请键入计算机名称、句点 (.) 或 localhost。

此参数不依赖于 Windows PowerShell 远程处理。即使计算机未配置为运行远程命令，也可以使用 ComputerName 参数。

Type:	String
Aliases:	Cn
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Credential

指定有权执行此操作的用户帐户。默认为当前用户。

键入用户名，如 User01 或 Domain01\User01，或输入 PSCredential 对象，例如由 Get-Credential cmdlet 生成的对象。键入用户名时，此 cmdlet 会提示输入密码。

Type:	PSCredential
Position:	Named
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

-Namespace

指定 WMI 类的命名空间。

Type:	String
Aliases:	NS
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Query

用标识 WMI 事件类的 WMI 查询语言 (WQL) 指定一个查询，如：select * from __InstanceDeletionEvent。

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

-SourceIdentifier

指定你为订阅选择的名称。你选择的名称必须在当前会话中唯一。默认值为 Windows 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

-Timeout

指定 Windows PowerShell 等待此命令完成的时长。

默认值为 0（零），表示没有超时，这将导致 Windows PowerShell 无限期地等待。

Type:	Int64
Aliases:	TimeoutMSec
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

输入

None

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

输出