Register-WmiEvent

發行項
10/30/2009

訂閱 Windows Management Instrumentation (WMI) 事件。

語法

Register-WmiEvent [-Class] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

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

描述

引發訂閱的 WMI 事件時，事件會加入至本機工作階段的事件佇列中，即使事件發生於遠端電腦也是如此。若要取得事件佇列中的事件，請使用 Get-Event Cmdlet。

您可以使用 Register-WmiEvent 的參數訂閱遠端電腦上的事件，並且指定事件的屬性值，以幫助您識別佇列中的事件。也可以使用 Action 參數指定引發訂閱的事件時所要採取的動作。

當您訂閱事件時，事件訂閱者會加入至您的工作階段。若要取得工作階段中的事件訂閱者，請使用 Get-EventSubscriber Cmdlet。若要取消訂閱，請使用 Unregister-Event Cmdlet，它會從工作階段刪除事件訂閱者。

參數

-Action <scriptblock>

指定處理事件的命令。當引發事件時會執行 Action 參數中的命令，而非將事件傳送到事件佇列。請以大括號 ( { } ) 括住命令以建立指令碼區塊。

Action 參數的值可以包含 $Event、$EventSubscriber、$Sender、$SourceEventArgs 和 $SourceArgs 自動變數，這些自動變數為 Action 指令碼區塊提供事件的相關資訊。如需詳細資訊，請參閱 about_Automatic_Variables。

當您指定動作時，Register-WmiEvent 會傳回代表該動作的事件工作物件。您可以使用包含 Job 名詞的 Cmdlet (Job Cmdlet) 管理事件工作。

必要?	false
位置?	102
預設值	事件已新增至事件佇列。
接受管線輸入?	false
接受萬用字元?	false

-Class <string>

指定所要訂閱的事件。輸入產生事件的 WMI 類別。每一個命令都需要 Class 或 Query 參數。

必要?	true
位置?	1
預設值	無
接受管線輸入?	false
接受萬用字元?	false

-ComputerName <string>

指定遠端電腦。預設為本機電腦。輸入 NetBIOS 名稱、IP 位址或是完整的網域名稱。

必要?	false
位置?	named
預設值	本機電腦
接受管線輸入?	false
接受萬用字元?	false

-Credential <PSCredential>

指定具有執行此動作之權限的使用者帳戶。請輸入使用者名稱，例如 "User01" 或 "Domain01\User01"。或者輸入 PSCredential 物件，例如 Get-Credential Cmdlet 所傳回的物件。如果輸入使用者名稱，則系統會提示您提供密碼。

必要?	false
位置?	named
預設值	目前的使用者憑證
接受管線輸入?	false
接受萬用字元?	false

-Forward

將這個訂閱的事件傳送到本機電腦的工作階段。當您在遠端電腦上或透過遠端工作階段註冊事件時，請使用此參數。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-MessageData <psobject>

指定要與這個事件訂閱產生關聯的任何其他資料。此參數的值會出現在所有與這個訂閱關聯之事件的 MessageData 屬性中。

必要?	false
位置?	named
預設值	無。MessageData 屬性為 NULL。
接受管線輸入?	false
接受萬用字元?	false

-Namespace <string>

指定 WMI 類別的命名空間。

必要?	false
位置?	named
預設值	無
接受管線輸入?	false
接受萬用字元?	false

-Query <string>

以 WMI 查詢語言 (WQL) 指定識別 WMI 事件類別的查詢，例如 "select * from __InstanceDeletionEvent"。

必要?	true
位置?	1
預設值	無
接受管線輸入?	false
接受萬用字元?	false

-SourceIdentifier <string>

指定您為訂閱所選取的名稱。您所選取的名稱在目前工作階段中必須是唯一的。預設值為 Windows PowerShell 指派的 GUID。

此參數的值會出現在訂閱者物件以及所有與這個訂閱相關聯之事件物件的 SourceIdentifier 屬性值中。

必要?	false
位置?	101
預設值	GUID
接受管線輸入?	false
接受萬用字元?	false

-SupportEvent

隱藏事件訂閱。當目前的訂閱屬於較複雜的事件註冊機制，而且不可單獨進行探索時，請使用此參數。

若要檢視或取消以 SupportEvent 參數建立的訂閱，請使用 Get-EventSubscriber 和 Unregister-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 所傳回的物件型別。

輸入

無

您無法透過管道將物件傳遞給 Register-WmiEvent。

輸出

無

這個 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 命令。

共用方式為