Register-EngineEvent

モジュール:

Microsoft.PowerShell.Utility Module

PowerShell エンジンと New-Event コマンドレットによって生成されるイベントをサブスクライブします。

構文

Default (既定)

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 イベントが発生したときに指定したアクションを実行する

この例では、Register-EngineEvent イベントが発生したときに、 を実行して特定のアクションを実行する方法を示します。

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 が作成したジョブ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 はまだ実行中であり、新しいイベントを作成しています。 ジョブ コマンドレットを使用してジョブを停止し、不要なジョブ オブジェクトを削除します。 Get-Content ログ ファイルの内容が表示されます。

パラメーター

-Action

イベントを処理するコマンドを指定します。 アクションにあるコマンドは、イベントキューにイベントを送信するのではなく、イベントが発生したときに実行されます。 コマンドを中かっこ ({}) で囲み、スクリプト ブロックを作成します。

Action パラメーターの値には、$Event スクリプト ブロックにイベントに関する情報を提供する、$EventSubscriber、$Sender、$EventArgs、$Args、および 自動変数を含めることができます。 詳細については、about_Automatic_Variablesを参照してください。

アクションを指定すると、Register-EngineEvent はそのアクションを表すイベント ジョブ オブジェクトを返します。 Job コマンドレットを使用して、イベント ジョブを管理できます。

パラメーターのプロパティ

型:	ScriptBlock
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーター セット

(All)

配置:	101
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-Forward

コマンドレットが、このサブスクリプションのイベントをローカル コンピューター上のセッションに送信することを示します。 このパラメーターは、リモート コンピューターまたはリモート セッションのイベントに登録する場合に使用します。

パラメーターのプロパティ

型:	SwitchParameter
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーター セット

(All)

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-MaxTriggerCount

イベント サブスクリプションに対してアクションが実行される最大回数を指定します。

パラメーターのプロパティ

型:	Int32
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーター セット

(All)

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-MessageData

イベントに関連付けられている追加のデータを指定します。 このパラメーターの値は、イベント オブジェクトの MessageData プロパティに表示されます。

パラメーターのプロパティ

型:	PSObject
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーター セット

(All)

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-SourceIdentifier

サブスクライブするイベントのソース識別子を指定します。 ソース識別子は、現在のセッションで一意である必要があります。 このパラメーターは必須です。

このパラメーターの値は、サブスクライバー オブジェクトの SourceIdentifier プロパティの値と、このサブスクリプションに関連付けられているすべてのイベント オブジェクトの値に表示されます。

値はイベントのソースに固有です。 New-Event コマンドレットで使用するために作成した任意の値を指定できます。 PowerShell エンジンは、PSEngineEvent 値の PowerShell.Exiting と PowerShell.OnIdleをサポートしています。

パラメーターのプロパティ

型:	String
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーター セット

(All)

配置:	100
必須:	True
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-SupportEvent

コマンドレットがイベント サブスクリプションを非表示にすることを示します。 現在のサブスクリプションがより複雑なイベント登録メカニズムの一部であり、個別に検出すべきでない場合は、このパラメーターを追加します。

SupportEvent パラメーターを使用して作成されたサブスクリプションを表示または取り消すには、Force パラメーターを Get-EventSubscriber または Unregister-Event コマンドレットに追加します。

パラメーターのプロパティ

型:	SwitchParameter
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーター セット

(All)

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

CommonParameters

このコマンドレットでは、一般的なパラメーター -Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction、-WarningVariable の各パラメーターがサポートされています。 詳細については、about_CommonParametersを参照してください。

入力

None

Register-EngineEventに入力をパイプすることはできません。

出力

None or System.Management.Automation.PSEventJob

Action パラメーターを使用すると、Register-EngineEvent は System.Management.Automation.PSEventJob オブジェクトを返します。 それ以外の場合、出力は生成されません。

メモ

イベント、イベント サブスクリプション、およびイベント キューは、現在のセッションにのみ存在します。 現在のセッションを閉じると、イベント キューは破棄され、イベント サブスクリプションは取り消されます。

Exiting イベントをサブスクライブする場合、Action パラメーターで実行できるコマンドレットは、Microsoft.PowerShell.Core および Microsoft.PowerShell.Utility モジュール コマンドレットに制限されます。 Exiting イベントは、PowerShell の制御下でセッションが終了した場合にのみ発生します。 ホスト アプリケーションまたはターミナル ウィンドウが閉じられると、イベントは発生しません。

パイプラインが実行されていない場合、エンジンはアイドル状態とみなされます。 OnIdle イベントは、PowerShell が 300 ミリ秒 (ミリ秒) アイドル状態のときに発生します。

注

PSReadLine が使用されている場合、 がタイムアウトすると (300 ミリ秒以内に入力がないと) ReadKey() イベントが発生します。 ユーザーがコマンド ラインの編集中にイベントを通知できます。たとえば、ユーザーが使用するパラメーターを決定するためのヘルプを読んでいる場合などです。 PSReadLine 2.2.0-beta4 以降では、OnIdle 動作が変更され、ReadKey() タイムアウトがあり、現在の編集バッファーが空の場合にのみイベントが通知されます。

関連リンク

• Get-Event
• 新しいイベント
• Register-ObjectEvent
• Remove-Event
• Unregister-Event（イベント登録解除）
• Wait-Event