Register-EngineEvent
訂閱 PowerShell 引擎和 New-Event Cmdlet 所產生的事件。
Syntax
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Description
Register-EngineEvent Cmdlet 會訂閱 PowerShell 引擎和 New-Event Cmdlet 所產生的事件。 請使用 SourceIdentifier 參數指定事件。
您可以使用此 Cmdlet 來訂閱 Cmdlet 所產生的 New-EventOnIdle 或 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 事件時，採取指定的動作
此範例示範如何在發生PowerShell.Exiting事件時執行 Register-EngineEvent 以採取特定動作。
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $HOME\history.clixml
}已新增 SupportEvent 參數來隱藏事件訂閱。 當 PowerShell 結束時，在此情況下，結束工作階段的命令歷程記錄會匯出使用者 $HOME 目錄中的 XML 檔案。
範例 3：Create 和訂閱使用者定義事件
此範例會從來源 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 中的命令，而不會將事件傳送到事件佇列。 以大括弧括住命令， () {} 以建立腳本區塊。
Action 參數的值可以包含 $Event、$EventSubscriber、$Sender、 $EventArgs和 $Args 自動變數，這些變數會將事件的相關信息提供給 Action 腳本區塊。 如需詳細資訊，請參閱 about_Automatic_Variables。
當您指定動作時， Register-EngineEvent 會傳回代表該動作的事件作業物件。 您可以使用各種 Job 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 正在使用中時ReadKey()，會在逾時時引發 OnIdle 事件， (沒有輸入 300 毫秒) 。 當使用者在編輯命令行時，可能會發出訊號，例如，使用者正在閱讀說明來決定要使用的參數。 從 PSReadLine 2.2.0-beta4 開始， OnIdle 行為只有在有 ReadKey() 逾時且目前的編輯緩衝區是空的時，才會變更為發出訊號。