Register-WmiEvent
订阅 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) 来管理事件作业。
类型: | ScriptBlock |
Position: | 101 |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Class
指定要订阅的事件。 请输入用于生成这些事件的 WMI 类。 每个命令中都需要 Class 或 Query 参数。
类型: | String |
Position: | 0 |
默认值: | None |
必需: | True |
接受管道输入: | False |
接受通配符: | False |
-ComputerName
指定要在其上运行命令的计算机的名称。 默认为本地计算机。
键入计算机的 NetBIOS 名称、IP 地址或完全限定的域名。 若要指定本地计算机,请键入计算机名称、句点 (.
) 或 localhost。
此参数不依赖于 Windows PowerShell 远程处理。 即使计算机未配置为运行远程命令,也可以使用 ComputerName 参数。
类型: | String |
别名: | Cn |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Credential
指定有权执行此操作的用户帐户。 默认为当前用户。
键入用户名,如 User01 或 Domain01\User01,或输入 PSCredential 对象,例如由 Get-Credential
cmdlet 生成的对象。 键入用户名时,此 cmdlet 会提示输入密码。
类型: | PSCredential |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Forward
指示该 cmdlet 将此订阅的事件发送到本地计算机上的会话。 如果要在远程计算机或远程会话中注册事件,可使用此参数。
类型: | SwitchParameter |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-MaxTriggerCount
指定最大触发器计数。
类型: | Int32 |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-MessageData
指定将与此事件订阅关联的任何额外数据。 此参数的值出现在与此订阅关联的所有事件的 MessageData 属性中。
类型: | PSObject |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Namespace
指定 WMI 类的命名空间。
类型: | String |
别名: | NS |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Query
用标识 WMI 事件类的 WMI 查询语言 (WQL) 指定一个查询,如:select * from __InstanceDeletionEvent
。
类型: | String |
Position: | 0 |
默认值: | None |
必需: | True |
接受管道输入: | False |
接受通配符: | False |
-SourceIdentifier
指定你为订阅选择的名称。 你选择的名称必须在当前会话中唯一。 默认值为 Windows PowerShell 指定的 GUID。
此参数的值出现在订阅者对象以及与此订阅关联的所有事件对象的 SourceIdentifier 属性值中。
类型: | String |
Position: | 100 |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-SupportEvent
指示该 cmdlet 隐藏事件订阅。 在当前订阅是更复杂的事件注册机制的一部分并且不应单独发现时,可使用此参数。
若要查看或取消使用 SupportEvent 参数创建的订阅,请指定 Get-EventSubscriber
和 Unregister-Event
cmdlet 的 Force 参数。
类型: | SwitchParameter |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Timeout
指定 Windows PowerShell 等待此命令完成的时长。
默认值为 0(零),表示没有超时,这将导致 Windows PowerShell 无限期地等待。
类型: | Int64 |
别名: | TimeoutMSec |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
输入
None
不能通过管道将对象传递给此 cmdlet。
输出
None
此 cmdlet 将不生成任何输出。
备注
若要在 Windows Vista 或更高版本的 Windows 操作系统中使用此 cmdlet,请使用“以管理员身份运行”选项启动 Windows PowerShell。
事件、事件订阅和事件队列仅存在于当前会话中。 如果关闭当前会话,将丢弃事件队列并取消事件订阅。