Register-ObjectEvent

リファレンス

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

Microsoft .NET Framework オブジェクトによって生成されるイベントをサブスクライブします。

構文

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

説明

Register-ObjectEvent コマンドレットは、ローカルコンピューターまたはリモートコンピューター上の .NET オブジェクトによって生成されるイベントをサブスクライブします。

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

Register-ObjectEventのパラメーターを使用して、キュー内のイベントを識別するのに役立つイベントのプロパティ値を指定できます。 Action パラメーターを使用して、サブスクライブされたイベントが発生したときに実行するアクションと、ローカルセッションのイベントキューにリモートイベントを送信する Forward パラメーターを指定することもできます。

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

例

例 1: 新しいプロセスの開始時にイベントをサブスクライブする

この例は、新しいプロセスの開始時に生成されたイベントをサブスクライブします。

このコマンドは、 ManagementEventWatcher オブジェクトを使用して、 EventArrived イベントを取得します。クエリオブジェクトは、イベントが Win32_Process クラスのインスタンス作成イベントであることを指定します。

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"

例 2: イベントに応答するアクションを指定する

アクションを指定した場合には、発生するイベントはイベントキューに追加されません。その代わり、指定したアクションが発生したイベントに応答します。この例では、新しいプロセスが開始されたことを示すインスタンス作成イベントが発生すると、新しい ProcessCreated イベントが発生します。

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
$newEventArgs = @{
    SourceIdentifier = 'PowerShell.ProcessCreated'
    Sender = $Sender
    EventArguments = $EventArgs.NewEvent.TargetInstance
}
$Action = { New-Event @newEventArgs }
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action

Id   Name               PSJobTypeName   State       HasMoreData   Location   Command
--   ----               -------------   -----       -----------   --------   -------
 5   3db2d67a-efff-...                 NotStarted   False                    New-Event @newEventArgs

アクションでは、 $Sender と $EventArgs 自動変数が使用されます。この変数は、イベントアクションにのみ設定されます。

Register-ObjectEvent コマンドは、バックグラウンドジョブとして実行されるアクションを表すジョブオブジェクトを返します。 Get-JobやReceive-Jobなどの Job コマンドレットを使用して、バックグラウンドジョブを管理できます。詳細については、「about_Jobs」を参照してください。

例 3: リモートコンピューター上のオブジェクトイベントをサブスクライブする

この例は、リモートコンピューター上のオブジェクトイベントをサブスクライブする方法を示しています。この例では、ProcessCreationEvent.ps1 スクリプトファイルで定義されているEnable-ProcessCreationEvent関数を使用します。このスクリプトは、この例のすべてのコンピューターで使用できます。

# ProcessCreationEvent.ps1
function  Enable-ProcessCreationEvent {
    $queryParameters = "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1),
        "TargetInstance isa 'Win32_Process'"
    $Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters

    $objectEventArgs = @{
        Input = New-Object System.Management.ManagementEventWatcher $Query
        EventName = 'EventArrived'
        SourceIdentifier = 'WMI.ProcessCreated'
        MessageData = 'Test'
        Forward = $True
    }
    Register-ObjectEvent @objectEventArgs
}

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
Invoke-Command -Session $S { Enable-ProcessCreationEvent }

最初に、2 台のリモートコンピューターに PSSessions を作成し、 $S 変数に保存します。次に、Invoke-Command コマンドレットは、$Sの各 PSSession でProcessCreationEvent.ps1 スクリプトを実行します。このアクションにより、リモートセッションに Enable-ProcessCreationEvent 関数が作成されます。最後に、リモートセッションで Enable-ProcessCreationEvent 関数を実行します。

この関数には、ManagementEventWatcher オブジェクトとそのEventArrived イベントを介してWin32_Process オブジェクトのインスタンス作成イベントをサブスクライブするRegister-ObjectEvent コマンドが含まれています。

例 4: PSEventJob オブジェクトで動的モジュールを使用する

この例では、イベント登録に Action を含めると作成される PSEventJob オブジェクトで動的モジュールを使用する方法を示します。まず、タイマーオブジェクトを作成して有効にしてから、タイマーの間隔を 500 (ミリ秒) に設定します。 Register-ObjectEvent コマンドレットは、タイマーオブジェクトの Elapsed イベントを登録します。 PSEventJob オブジェクトは$Job変数に保存され、イベントサブスクライバーの Action プロパティでも使用できます。詳細については、「 Get-EventSubscriberを参照してください。

タイマー間隔が経過するたびに、イベントが発生し、アクションが実行されます。この場合、 Get-Random コマンドレットは 0 から 100 までの乱数を生成し、 $Random 変数に保存します。

$Timer = New-Object Timers.Timer
$Timer.Interval = 500
$Timer.Enabled = $True
$objectEventArgs = @{
    InputObject = $Timer
    EventName = 'Elapsed'
    SourceIdentifier = 'Timer.Random'
    Action = {$Random = Get-Random -Min 0 -Max 100}
}
$Job = Register-ObjectEvent @objectEventArgs
$Job | Format-List -Property *
& $Job.module {$Random}
& $Job.module {$Random}

State         : Running
Module        : __DynamicModule_53113769-31f2-42dc-830b-8749325e28d6
StatusMessage :
HasMoreData   : True
Location      :
Command       : $Random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 47b5ec9f-bfe3-4605-860a-4674e5d44ca8
Id            : 7
Name          : Timer.Random
ChildJobs     : {}
PSBeginTime   : 6/27/2019 10:19:06 AM
PSEndTime     :
PSJobTypeName :
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}
60
47

PSEventJob には、アクションを実装する動的スクリプトモジュールを含む Module プロパティがあります。呼び出し演算子 (&) を使用して、モジュール内のコマンドを呼び出して、 $Random 変数の値を表示します。

モジュールの詳細については、 about_Modulesを参照してください。

パラメーター

-Action

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

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

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

型:	ScriptBlock
配置:	101
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-EventName

サブスクライブするイベントを指定します。

このパラメーターの値は、.NET オブジェクトが公開するイベントの名前である必要があります。たとえば、 ManagementEventWatcher クラスには、 EventArrived および Stopped という名前のイベントがあります。イベントのイベント名を検索するには、 Get-Member コマンドレットを使用します。

型:	String
配置:	1
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Forward

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

型:	SwitchParameter
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-InputObject

イベントを生成する .NET オブジェクトを指定します。オブジェクトが格納されている変数を入力するか、オブジェクトを取得するコマンドまたは式を入力します。

型:	PSObject
配置:	0
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-MaxTriggerCount

イベントをトリガーできる最大回数を指定します。

型:	Int32
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-MessageData

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

型:	PSObject
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-SourceIdentifier

サブスクリプション用に選択した名前を指定します。選択した名前は、現在のセッションで一意でなければなりません。既定値は、PowerShell によって割り当てられる GUID です。

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

型:	String
配置:	100
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-SupportEvent

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

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

型:	SwitchParameter
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

入力

None

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

出力

None

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

PSEventJob

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

メモ

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

次の方法で共有

Register-ObjectEvent

構文

説明

例

例 1: 新しいプロセスの開始時にイベントをサブスクライブする

例 2: イベントに応答するアクションを指定する

例 3: リモートコンピューター上のオブジェクトイベントをサブスクライブする

例 4: PSEventJob オブジェクトで動的モジュールを使用する

パラメーター

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

入力

出力

メモ

その他のリソース

次の方法で共有

Register-ObjectEvent

構文

説明

例

例 1: 新しいプロセスの開始時にイベントをサブスクライブする

例 2: イベントに応答するアクションを指定する

例 3: リモート コンピューター上のオブジェクト イベントをサブスクライブする

例 4: PSEventJob オブジェクトで動的モジュールを使用する

パラメーター

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

入力

出力

メモ

関連リンク

その他のリソース

例 3: リモートコンピューター上のオブジェクトイベントをサブスクライブする