Register-EngineEvent
PowerShell エンジンと コマンドレットによって生成されるイベントを New-Event サブスクライブします。
構文
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] 説明
コマンドレットは Register-EngineEvent 、PowerShell エンジンと コマンドレットによって生成されるイベントを New-Event サブスクライブします。 SourceIdentifier パラメーターを使用してイベントを指定します。
このコマンドレットを使用して、 コマンドレットによって生成された OnIdle または Exiting エンジン のイベントとイベントを New-Event サブスクライブできます。 これらのイベントは、サブスクライブせずにセッションのイベント キューに自動的に追加されます。 ただし、サブスクライブすることにより、イベントへの転送、イベントに応答するアクションの指定、サブスクリプションの取り消しを実行できます。
イベントをサブスクライブすると、イベント サブスクライバーがセッションに追加されます。 セッションのイベント サブスクライバーを取得するには、Get-EventSubscriber コマンドレットを使用します。 サブスクリプションをキャンセルするには、Unregister-Event コマンドレットを使用して、セッションからイベント サブスクライバーを削除します。
サブスクライブされているイベントが発生すると、セッションのイベント キューにそのイベントが追加されます。 イベント キュー内のイベントを取得するには、 コマンドレットを使用します Get-Event 。
例
例 1: リモート コンピューターに PowerShell エンジン イベントを登録する
次の使用例は、2 台のリモート コンピューターで PowerShell エンジン イベントを登録します。
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}New-PSSession は、各リモート コンピューターにユーザー管理セッション (PSSession) を作成します。コマンドレットは 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 作成されたジョブ ID 18。 Start-Job 作成されたジョブ ID 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...コマンドレットは Unregister-Event 、イベント サブスクリプションに関連付けられているジョブを停止します (ジョブ ID 18)。 ジョブ ID 19 は引き続き実行され、新しいイベントが作成されています。 Job コマンドレットを使用してジョブを停止し、不要なジョブ オブジェクトを削除します。 Get-Content には、ログ ファイルの内容が表示されます。
パラメーター
-Action
イベントを処理するコマンドを指定します。 Action で指定したコマンドは、イベント キューにイベントを送信する時点ではなく、イベントが発生した時点で実行されます。 コマンドを中かっこ ({}) で囲み、スクリプト ブロックを作成します。
Action パラメーターの値には、イベントに関する情報を $Event$Sender$EventArgs$EventSubscriberAction スクリプト ブロックに提供する、および$Args自動変数を含めることができます。 詳細については、「about_Automatic_Variables」を参照してください。
アクションを指定すると、 Register-EngineEvent そのアクションを表すイベント ジョブ オブジェクトが返されます。 Job コマンドレットを使用して、イベント ジョブを管理できます。
| Type: | ScriptBlock |
| Position: | 101 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Forward
コマンドレットが、このサブスクリプションのイベントをローカル コンピューター上のセッションに送信することを示します。 このパラメーターは、リモート コンピューターまたはリモート セッションのイベントに登録する場合に使用します。
| 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 指定できます。 PowerShell エンジンでは、 PSEngineEvent 値 PowerShell.Exiting と PowerShell.OnIdle がサポートされています。
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SupportEvent
コマンドレットがイベント サブスクリプションを非表示にすることを示します。 現在のサブスクリプションがより複雑なイベント登録メカニズムの一部であり、個別に検出されない場合は、このパラメーターを追加します。
SupportEvent パラメーターを使用して作成されたサブスクリプションを表示または取り消すには、 または Unregister-Event コマンドレットに Force パラメーターをGet-EventSubscriber追加します。
| 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-EngineEventSystem.Management.Automation.PSEventJob オブジェクトが返されます。 それ以外の場合、出力は生成されません。
メモ
イベント、イベント サブスクリプション、およびイベント キューは、現在のセッションにのみ存在します。 現在のセッションを閉じた場合、イベント キューが破棄され、イベント サブスクリプションが取り消されます。
Exiting イベントをサブスクライブする場合、Action パラメーターで実行できるコマンドレットは、Microsoft.PowerShell.Core および Microsoft.PowerShell.Utility モジュールのコマンドレットに制限されます。 Exiting イベントは、PowerShell の制御下でセッションが終了した場合にのみ発生します。 ホスト アプリケーションまたはターミナル ウィンドウが閉じられると、イベントは発生しません。
パイプラインを実行していない場合、エンジンはアイドル状態と見なされます。 OnIdle イベントは、PowerShell が 300 ミリ秒 (ミリ秒) アイドル状態のときに発生します。
注意
PSReadLine が使用されている場合、 OnIdle イベントはタイムアウト時 ReadKey() に発生します (300 ミリ秒で入力しません)。 ユーザーがコマンド ラインの編集中にイベントが通知される可能性があります。たとえば、ユーザーが使用するパラメーターを決定するためのヘルプを読み取っている場合などです。 PSReadLine 2.2.0-beta4 以降では、 OnIdle の動作が ReadKey() 変更され、タイムアウトがあり、現在の編集バッファーが空の場合にのみイベントが通知されます。