次の方法で共有


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 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-CommandRegister-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 ngineEventPowerShell.ExitingPowerShell.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()場合にのみイベントを通知するように変更されました。