次の方法で共有

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 エンジンのイベントと、コマンドレットによって生成されたイベントを 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$EventSubscriberAction スクリプト ブロックに提供する、、$Sender$EventArgs、、および$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 エンジンでは、POWERShell.Exiting と PowerShell.OnIdle の PSEngineEvent 値がサポートされています。

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

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

出力

None

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

PSEventJob

Action パラメーターを使用すると、このコマンドレットは 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() 場合にのみイベントを通知するように変更されました。