Register-EngineEvent

リファレンス

モジュール:: Microsoft.PowerShell.Utility

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

構文

Register-EngineEvent
        [-SourceIdentifier] <String>
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

説明

コマンドレットは Register-EngineEvent 、PowerShell エンジンとコマンドレットによって生成されたイベントを New-Event サブスクライブします。 SourceIdentifier パラメーターを使用してイベントを指定します。

このコマンドレットを使用して、OnIdle または Exiting engine イベントおよびコマンドレットによって生成されたイベントを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: ユーザー定義イベントを作成してサブスクライブする

この例では、ソース 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 パラメーターの値には、$EventSubscriber$EventArgs$Senderイベントに関する情報を $EventAction スクリプトブロックに提供する、、、、および$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 エンジンは、P Standard Edition ngineEvent 値 PowerShell.Exiting と PowerShell.OnIdle をサポートしています。

Type:	String
Position:	100
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-SupportEvent

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

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

入力

None

このコマンドレットにオブジェクトをパイプすることはできません。

出力

None

既定では、このコマンドレットは出力を返しません。

PSEventJob

Action パラメーターを使用すると、このコマンドレットは P Standard Edition ventJob オブジェクトを返します。

メモ

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

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

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

Note

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

Register-EngineEvent

構文

説明

例

例 1: リモートコンピューターに PowerShell エンジンイベントを登録する

例 2: Exiting イベントが発生したときに指定したアクションを実行する

例 3: ユーザー定義イベントを作成してサブスクライブする

例 4: イベントの登録解除とジョブのクリーン

パラメーター

-Action

-Forward

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

入力

出力

メモ

フィードバック

その他のリソース

Register-EngineEvent

構文

説明

例

例 1: リモート コンピューターに PowerShell エンジン イベントを登録する

例 2: Exiting イベントが発生したときに指定したアクションを実行する

例 3: ユーザー定義イベントを作成してサブスクライブする

例 4: イベントの登録解除とジョブのクリーン

パラメーター

-Action

-Forward

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

入力

出力

メモ

関連リンク

フィードバック

その他のリソース

例 1: リモートコンピューターに PowerShell エンジンイベントを登録する