Register-EngineEvent

  • 參考
模組:
Microsoft.PowerShell.Utility

訂閱 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 不會傳回任何輸出。

PSEventJob

當您使用 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() 逾時且目前的編輯緩衝區空白時才會發出訊號。