訂閱由 Windows PowerShell 引擎和 New-Event Cmdlet 所產生的事件。

語法

Register-EngineEvent [-SourceIdentifier] <string> [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]

描述

Register-EngineEvent Cmdlet 會訂閱由 Windows PowerShell 引擎和 New-Event Cmdlet 所產生的事件。請使用 SourceIdentifier 參數指定事件。

您可以使用此 Cmdlet 訂閱 New-Event Cmdlet 所產生的 "Exiting" 引擎事件。這些事件會自動新增到工作階段中的事件佇列,不需訂閱。但是訂閱能讓您轉送事件、指定要回應事件的動作,以及取消訂閱。

當引發訂閱的事件時,訂閱的事件會新增到工作階段中的事件佇列。若要取得事件佇列中的事件,請使用 Get-Event Cmdlet。

訂閱事件時,事件訂閱者會新增到工作階段。若要取得工作階段中的事件訂閱者,請使用 Get-EventSubscriber Cmdlet。若要取消訂閱,請使用 Unregister-Event Cmdlet,它會從工作階段刪除事件訂閱者。

參數

-Action <scriptblock>

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

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

指定動作時,Register-EngineEvent 會傳回代表該動作的事件工件物件。您可以使用 Job Cmdlet 管理事件工作。

必要?

false

位置?

102

預設值

接受管線輸入?

false

接受萬用字元?

false

-Forward

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

必要?

false

位置?

named

預設值

False

接受管線輸入?

false

接受萬用字元?

false

-MessageData <psobject>

指定與事件關聯的其他資料。此參數的值會出現在事件物件的 MessageData 屬性。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-SourceIdentifier <string>

指定所要訂閱之事件的來源識別元。來源識別元在目前工作階段中必須是唯一的。此參數為必要項。

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

必要?

true

位置?

101

預設值

接受管線輸入?

false

接受萬用字元?

false

-SupportEvent

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

若要檢視或取消以 SupportEvent 參數建立的訂閱,請使用 Get-EventSubscriberUnregister-Event Cmdlet 的 Force 參數。

必要?

false

位置?

named

預設值

False

接受管線輸入?

false

接受萬用字元?

false

<CommonParameters>

這個 Cmdlet 支援一般參數:-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊,請參閱 about_Commonparameters.

輸入和輸出

輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。

輸入

您無法經由管道將輸入輸出至 Register-EngineEvent。

輸出

無或 System.Management.Automation.PSEventJob

如果您使用 Action 參數,Register-EngineEvent 就會傳回 System.Management.Automation.PSEventJob 物件。否則,這個 Cmdlet 不會產生任何輸出。

附註

事件、事件訂閱和事件佇列只存在於目前的工作階段中。如果關閉目前的工作階段,則會捨棄事件佇列並取消事件訂閱。

範例 1

C:\PS>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s { Register-EngineEvent -sourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -forward }

描述
-----------
這個命令會在兩台遠端電腦上註冊 Windows PowerShell 引擎事件。

第一個命令會在每一台遠端電腦上建立 PSSession。

第二個命令會使用 Invoke-Command Cmdlet 在遠端工作階段中執行 Register-EngineEvent 命令。

Register-EngineEvent 命令會使用 SourceIdentifier 參數指定事件,並使用 Forward 參數將事件從遠端工作階段轉送到本機工作階段。






範例 2

C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated -action { $processName | add-content processLog.txt } 

C:\PS> get-event

C:\PS> $results = $j | receive-job

C:\PS> unregister-event PowerShell.ProcessCreated

描述
-----------
這個命令示範如何使用 Job Cmdlet 管理事件工作物件,而這個物件是在您使用 Action 參數時 Register-EngineEvent 所傳回的。

管理事件工作,如同任何其他 Windows PowerShell 工作一樣。如需詳細資訊,請參閱 about_jobs。在這個範例中,Receive-Job Cmdlet 是用來取得工作的結果。

若要從工作階段刪除工作,請使用 Remove-Job。若要取消事件訂閱,請使用 Unregister-Event Cmdlet。若要刪除事件佇列中的事件,請使用 Remove-Event。






請參閱




目錄