订阅 Windows Management Instrumentation (WMI) 事件。

语法

Register-WmiEvent [-类] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-命名空间 <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Register-WmiEvent [-Query] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-命名空间 <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

说明

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

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

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

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

参数

-Action <scriptblock>

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

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

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

是否为必需?

false

位置?

102

默认值

The event is added to the event queue.

是否接受管道输入?

false

是否接受通配符?

false

-类 <string>

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

是否为必需?

true

位置?

1

默认值

是否接受管道输入?

false

是否接受通配符?

false

-ComputerName <string>

指定远程计算机。默认值为本地计算机。请输入 NetBIOS 名称、IP 地址或完全限定的域名。

是否为必需?

false

位置?

named

默认值

Local computer

是否接受管道输入?

false

是否接受通配符?

false

-Credential <PSCredential>

指定有权执行此操作的用户帐户。键入用户名,例如“User01”或“Domain01\User01”。或者,输入 PSCredential 对象,例如来自 Get-Credential cmdlet 的对象。如果键入用户名,则将提示您输入密码。

是否为必需?

false

位置?

named

默认值

The credentials of the current user

是否接受管道输入?

false

是否接受通配符?

false

-Forward

将此订阅的事件发送到本地计算机上的会话。如果要在远程计算机或远程会话中注册事件,可使用此参数。

是否为必需?

false

位置?

named

默认值

是否接受管道输入?

false

是否接受通配符?

false

-MessageData <psobject>

指定将与此事件订阅关联的任何额外数据。此参数的值出现在与此订阅关联的所有事件的 MessageData 属性中。

是否为必需?

false

位置?

named

默认值

None. The MessageData property is NULL.

是否接受管道输入?

false

是否接受通配符?

false

-命名空间 <string>

指定 WMI 类的命名空间。

是否为必需?

false

位置?

named

默认值

是否接受管道输入?

false

是否接受通配符?

false

-Query <string>

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

是否为必需?

true

位置?

1

默认值

是否接受管道输入?

false

是否接受通配符?

false

-SourceIdentifier <string>

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

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

是否为必需?

false

位置?

101

默认值

GUID

是否接受管道输入?

false

是否接受通配符?

false

-SupportEvent

隐藏事件订阅。在当前订阅是更复杂的事件注册机制的一部分并且不应单独发现时,可使用此参数。

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

是否为必需?

false

位置?

named

默认值

False

是否接受管道输入?

false

是否接受通配符?

false

-Timeout <Int64>

确定 Windows PowerShell 等待此命令完成的时间长度。

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

是否为必需?

false

位置?

named

默认值

0

是否接受管道输入?

false

是否接受通配符?

false

<CommonParameters>

此 cmdlet 支持通用参数:-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。有关详细信息,请参阅 about_Commonparameters.

输入和输出

输入类型是指可通过管道传递给 cmdlet 的对象的类型。返回类型是指 Cmdlet 所返回对象的类型。

输入

None

不能通过管道将对象传递给 Register-WmiEvent。

输出

None

此 cmdlet 将不产生任何输出。

说明

要在 Windows Vista 或 Windows 的更高版本中使用此 cmdlet,必须使用“以管理员身份运行”选项启动 Windows PowerShell。

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

示例 1

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted"

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






示例 2

C:\PS>register-wmiEvent -query "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'" -sourceIdentifier "WMIProcess" -messageData "Test 01" -timeout 500

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






示例 3

C:\PS>$action = { get-history | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }

C:\PS> register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted" -action $action

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

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

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

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






示例 4

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "Start" -computername Server01 

C:\PS> get-event -sourceIdentifier "Start"

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

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






另请参阅




目录