Register-EngineEvent
訂閱 PowerShell 引擎和 New-Event Cmdlet 所產生的事件。
Syntax
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Description
Cmdlet Register-EngineEvent 會訂閱 PowerShell 引擎和 New-Event Cmdlet 所產生的事件。 使用 SourceIdentifier 參數來指定事件。
您可以使用此 Cmdlet 來訂閱 Cmdlet 所產生的 New-Event OnIdle 或 Exiting 引擎事件和事件。 這些事件會自動新增至會話中的事件佇列，而不需要訂閱。 不過，訂閱可讓您轉寄事件、指定回應事件的動作，以及取消訂閱。
當您訂閱事件時，事件訂閱者會新增至您的會話。 若要在會話中取得事件訂閱者，請使用 Get-EventSubscriber Cmdlet。 若要取消訂閱，請使用 Unregister-Event Cmdlet，從會話中刪除事件訂閱者。
引發訂閱的事件時，它會新增至會話中的事件佇列。 若要取得事件佇列中的事件，請使用 Get-Event Cmdlet。
範例
範例 1：在遠端電腦上註冊 PowerShell 引擎事件
此範例會在兩部遠端電腦上註冊 PowerShell 引擎事件。
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}New-PSSession 在每個遠端電腦上建立使用者管理的會話 （PSSession）。Cmdlet 會在 Invoke-Command 遠程會話中執行 Register-EngineEvent 命令。
Register-EngineEvent會使用SourceIdentifier參數來識別事件。 Forward 參數會告知引擎將事件從遠端會話轉送至本機會話。
範例 2：發生 Exiting 事件時採取指定的動作
此範例示範如何在Register-EngineEvent發生PowerShell.Exiting事件時執行 以採取特定動作。
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $HOME\history.clixml
}新增 SupportEvent 參數以隱藏事件訂閱。 當 PowerShell 結束時，在此案例中，結束會話的命令歷程記錄會匯出用戶目錄中的 $HOME XML 檔案。
範例 3：建立及訂閱使用者定義的事件
此範例會為來源 MyEventSource 的事件建立訂用帳戶。 這是我們將用來監視作業進度的任意來源。 Register-EngineEvent 用來建立訂用帳戶。 Action 參數的腳本區塊會將事件數據記錄至文本檔。
Register-EngineEvent -SourceIdentifier MyEventSource -Action {
"Event: {0}" -f $event.messagedata | Out-File c:\temp\MyEvents.txt -Append
}
Start-Job -Name TestJob -ScriptBlock {
While ($True) {
Register-EngineEvent -SourceIdentifier MyEventSource -Forward
Start-Sleep -seconds 2
"Doing some work..."
New-Event -SourceIdentifier MyEventSource -Message ("{0} - Work done..." -f (Get-Date))
}
}
Start-Sleep -seconds 4
Get-EventSubscriber
Get-Job
SubscriptionId : 12
SourceObject :
EventName :
SourceIdentifier : MyEventSource
Action : System.Management.Automation.PSEventJob
HandlerDelegate :
SupportEvent : False
ForwardEvent : False
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Running True …
19 TestJob BackgroundJob Running True localhost …Register-EngineEvent 已建立作業標識碼 18。 Start-Job 已建立作業標識碼 19。 在範例 #4 中，我們會移除事件訂用帳戶和作業，然後檢查記錄檔。
範例 4：取消註冊事件並清除作業
這是範例 3 的接續。 在此範例中，我們等候 10 秒，讓數個事件發生。 然後，我們會取消註冊事件訂用帳戶。
PS> Start-Sleep -seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Stopped False …
19 TestJob BackgroundJob Running True localhost …
PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM - Work done...
Event: 2/18/2020 2:36:21 PM - Work done...
Event: 2/18/2020 2:36:23 PM - Work done...
Event: 2/18/2020 2:36:25 PM - Work done...
Event: 2/18/2020 2:36:27 PM - Work done...
Event: 2/18/2020 2:36:29 PM - Work done...
Event: 2/18/2020 2:36:31 PM - Work done...Cmdlet 會 Unregister-Event 停止與事件訂用帳戶相關聯的作業（作業標識碼 18）。 作業標識碼 19 仍在執行中，並建立新的事件。 我們使用 Job Cmdlet停止作業，並移除不需要的工作物件。 Get-Content 會顯示記錄檔的內容。
參數
-Action
指定要處理事件的命令。 動作中的命令會在引發事件時執行，而不是將事件傳送至事件佇列。 以大括弧 （{}） 括住命令，以建立腳本區塊。
Action 參數的值可以包含 $Event、$EventSubscriber、$Sender、 $EventArgs和 $Args 自動變數，這些變數會將事件的相關信息提供給 Action 腳本區塊。 如需詳細資訊，請參閱 about_Automatic_Variables。
當您指定動作時， Register-EngineEvent 會傳回代表該動作的事件作業物件。 您可以使用作業 Cmdlet 來管理事件作業。
| Type: | ScriptBlock |
| Position: | 101 |
| 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 |
-SourceIdentifier
指定您要訂閱之事件的來源標識碼。 來源標識碼在目前的會話中必須是唯一的。 此為必要參數。
此參數的值會出現在 訂閱者物件的SourceIdentifier 屬性值，以及與此訂閱相關聯的所有事件物件。
值是事件來源特有的值。 這可以是您用來搭配 New-Event Cmdlet 使用的任意值。 PowerShell 引擎支援 PSEngineEvent 值 PowerShell.Exiting 和 PowerShell.OnIdle。
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SupportEvent
指出 Cmdlet 會隱藏事件訂閱。 當目前的訂用帳戶是更複雜的事件註冊機制的一部分，而且不應該獨立探索時，請新增此參數。
若要檢視或取消使用 SupportEvent 參數建立的訂用帳戶，請將 Force 參數新增至 Get-EventSubscriber 或 Unregister-Event Cmdlet。
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
輸入
None
您無法使用管線將物件傳送至此 Cmdlet。
輸出
None
根據預設，此 Cmdlet 不會傳回任何輸出。
當您使用 Action 參數時，這個 Cmdlet 會 傳回 PSEventJob 物件。
備註
事件、事件訂閱和事件佇列只存在於目前的會話中。 如果您關閉目前的會話，則會捨棄事件佇列，並取消事件訂閱。
訂閱 Exiting 事件時，Action 參數可執行的 Cmdlet 僅限於 Microsoft.PowerShell.Core 和 Microsoft.PowerShell.Utility 模組中的 Cmdlet。 只有在會話在PowerShell的控制下結束時，才會引發Exiting事件。 關閉主應用程式或終端機視窗時，不會引發事件。
如果引擎未執行管線，則會被視為閑置。 當 PowerShell 閒置 300 毫秒（毫秒）時，就會引發 OnIdle 事件。
注意
當 PSReadLine 正在使用中時， OnIdle 事件會在逾時時引發 ReadKey() （未輸入 300 毫秒）。 當使用者在編輯命令行時，可能會發出訊號，例如，使用者正在閱讀協助來決定要使用的參數。 從 PSReadLine 2.2.0-beta4 開始， OnIdle 行為已變更為只有在有 ReadKey() 逾時且目前的編輯緩衝區空白時才會發出訊號。
