Register-WmiEvent

  • 參考
模組:
Microsoft.PowerShell.Management

訂閱 Windows Management Instrumentation （WMI） 事件。

Syntax

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>]

Description

Cmdlet Register-WmiEvent 會訂閱本機計算機或遠端電腦上的 Windows Management Instrumentation （WMI） 事件。

引發已訂閱的 WMI 事件時，即使事件發生在遠端電腦上，也會將其新增至本機會話中的事件佇列。 若要取得事件佇列中的事件，請使用 Get-Event Cmdlet。

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

當您訂閱事件時，事件訂閱者會新增至您的會話。 若要在會話中取得事件訂閱者，請使用 Get-EventSubscriber Cmdlet。 若要取消訂閱，請使用 Unregister-Event Cmdlet，從會話中刪除事件訂閱者。

新的 Common Information Model （CIM） Cmdlet 引進 Windows PowerShell 3.0，會執行與 WMI Cmdlet 相同的工作。 CIM Cmdlet 符合 WS-Management （WSMan） 標準和 CIM 標準，這可讓 Cmdlet 使用相同的技術來管理執行 Windows 作業系統的電腦，以及執行其他操作系統的計算機。 請考慮使用 Register-CimIndicationEvent Cmdlet，而不是使用 。Register-WmiEvent

範例

範例 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 會傳回代表事件動作的背景作業。 您可以使用 作業 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 名詞 （Job Cmdlet） 的 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 物件，例如 Cmdlet 所產生的 Get-Credential 物件。 如果您輸入使用者名稱，此 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 查詢語言 （WQL） 中的查詢，以識別 WMI 事件類別，例如： 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 參數建立的訂用帳戶，請指定 和 Unregister-Event Cmdlet 的 Get-EventSubscriber 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。

輸出

None

此 Cmdlet 不會產生任何輸出。

備註

若要在 Windows Vista 或更新版本的 Windows 作業系統中使用此 Cmdlet，請使用 [以系統管理員身分執行] 選項啟動 Windows PowerShell。

事件、事件訂閱和事件佇列只存在於目前的會話中。 如果您關閉目前的會話，則會捨棄事件佇列，並取消事件訂閱。