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結束引擎事件和事件。 這些事件會自動新增到您工作階段中的事件佇列但不會訂閱。 不過，訂閱可讓您轉送事件、指定回應事件的動作，以及取消訂閱。
當訂閱的事件被引發時，它會被新增到您工作階段的事件佇列中。 若要取得事件佇列中的事件，請使用 Get-Event Cmdlet。
當您訂閱事件時，事件訂閱者會新增至您的會話。 若要取得會話中的事件訂閱者，請使用 Get-EventSubscriber Cmdlet。 若要取消訂閱，請使用 Unregister-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 引擎支援 EngineEvent 值 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
您無法使用管線將輸入傳送至 Register-EngineEvent。
輸出
None or System.Management.Automation.PSEventJob
如果您使用 Action 參數， Register-EngineEvent 會傳回 System.Management.Automation.PSEventJob 物件。 否則，它不會產生任何輸出。
備註
Linux 或macOS平台上沒有可用的事件來源。
事件、事件訂閱與事件佇列僅存在目前工作階段中。 若關閉目前工作階段，便會捨棄事件佇列，並取消事件訂閱。