Register-EngineEvent

モジュール:

Microsoft.PowerShell.Utility Module

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

構文

Default (既定)

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

説明

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

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

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

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

例

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

PS C:\> $S = New-PSSession -ComputerName "Server01, Server02"
PS C:\> 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: Exiting イベントが発生したときに指定したアクションを実行する

PS C:\> Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
     Get-History | Export-Clixml $Home\history.clixml
}

このコマンドは、PowerShell.Exiting イベントが発生したときに特定のアクションを実行 Register-EngineEvent を実行する方法を示します。 SupportEvent パラメーターが追加され、イベント サブスクリプションが非表示になります。 Windows PowerShell が終了すると、この場合、終了セッションからのコマンド履歴は XML 形式でユーザーの $Home ディレクトリ内のファイル名とパスにエクスポートされます。

パラメーター

-Action

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

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

アクションを指定すると、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

最大トリガー数を指定します。

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

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

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

型:	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 プロパティの値と、このサブスクリプションに関連付けられているすべてのイベント オブジェクトの値に表示されます。

サポートされている EngineEvent 値には、PowerShell.Exiting、PowerShell.OnIdle、PowerShell.OnScriptBlockInvoke などがあります。

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

型:	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 オブジェクトを返します。 それ以外の場合、出力は生成されません。

メモ

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

関連リンク

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