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

構文

Register-EngineEvent [-SourceIdentifier] <string> [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]

説明

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

このコマンドレットを使用して、"終了する" エンジン イベントおよび New-Event コマンドレットによって生成されたイベントにサブスクライブできます。これらのイベントは、サブスクライブしなくてもセッションのイベント キューに自動的に追加されます。ただし、サブスクライブすることで、イベントを転送したり、イベントに対応するアクションを指定したり、サブスクリプションをキャンセルしたりできます。

サブスクライブされたイベントが発生すると、セッションのイベント キューに追加されます。イベント キューのイベントを取得するには、Get-Event コマンドレットを使用します。

イベントにサブスクライブするとき、イベント サブスクライバーがセッションに追加されます。セッションのイベント サブスクライバーを取得するには、Get-EventSubscriber コマンドレットを使用します。サブスクリプションをキャンセルするには、Unregister-Event コマンドレットを使用して、セッションからイベント サブスクライバーを削除します。

パラメーター

-Action <scriptblock>

イベントを取り扱うコマンドを指定します。Action のコマンドは、イベント キューへのイベントの送信時ではなく、イベントの発生時に実行されます。コマンドを中かっこ ({ }) で囲み、スクリプト ブロックを作成します。

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

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

必須

false

位置

102

既定値

なし

パイプライン入力を許可する

false

ワイルドカード文字を許可する

false

-Forward

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

必須

false

位置

named

既定値

False

パイプライン入力を許可する

false

ワイルドカード文字を許可する

false

-MessageData <psobject>

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

必須

false

位置

named

既定値

なし

パイプライン入力を許可する

false

ワイルドカード文字を許可する

false

-SourceIdentifier <string>

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

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

必須

true

位置

101

既定値

パイプライン入力を許可する

false

ワイルドカード文字を許可する

false

-SupportEvent

イベント サブスクリプションを非表示にします。このパラメーターは、現在のサブスクリプションがさらに複雑なイベント登録メカニズムの一部であり、単独で検出されない場合に使用します。

SupportEvent パラメーターを使用して作成されたサブスクリプションを表示またはキャンセルするには、Get-EventSubscriber および Unregister-Event コマンドレットの Force パラメーターを使用します。

必須

false

位置

named

既定値

False

パイプライン入力を許可する

false

ワイルドカード文字を許可する

false

<CommonParameters>

このコマンドレットは、次の共通パラメーターをサポートします: -Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer、および -OutVariable。Ô”¼š¤Ë¤Ä¤¤¤Æ¤Ï¡¢次を参照してください: about_Commonparameters.

入力と出力

入力値の型は、コマンドレットへのパイプが可能なオブジェクトの型です。戻り値の型は、コマンドレットによって返されるオブジェクトの型です。

入力

なし

パイプを使用して入力を Register-EngineEvent に渡すことはできません。

出力

なし、または System.Management.Automation.PSEventJob

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

注

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

例 1

C:\PS>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s { Register-EngineEvent -sourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -forward }

説明
-----------
このコマンドは、2 台のリモート コンピューターの Windows PowerShell エンジン イベントを登録します。

最初のコマンドは、それぞれのリモート コンピューターに PSSession を作成します。

2 番目のコマンドは、Invoke-Command コマンドレットを使用して、リモート セッションの Register-EngineEvent コマンドを実行します。

Register-EngineEvent コマンドは、SourceIdentifier パラメーターを使用してイベントを識別します。Forward パラメーターを使用してイベントをリモート セッションからローカル セッションに転送します。

例 2

C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated -action { $processName | add-content processLog.txt } 

C:\PS> get-event

C:\PS> $results = $j | receive-job

C:\PS> unregister-event PowerShell.ProcessCreated

説明
-----------
このコマンドは、Job コマンドレットを使用して、Action パラメーターの使用時に Register-EngineEvent が返すイベント ジョブ オブジェクトを管理する方法を示します。

イベント ジョブは、他の Windows PowerShell のジョブと同様に管理されます。詳細については、「about_jobs」を参照してください。この例では、ジョブの結果を取得するために Receive-Job コマンドレットが使用されています。

セッションからジョブを削除するには、Remove-Job を使用します。イベント サブスクリプションをキャンセルするには、Unregister-Event コマンドレットを使用します。イベント キューのイベントを削除するには、Remove-Event を使用します。

関連項目



目次