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 、バックグラウンドジョブとして実行されるアクションを表すジョブオブジェクトを返します。 Job コマンドレットを使用して、Get-JobReceive-Jobバックグラウンドジョブを管理できます。詳細については、「about_Jobs」を参照してください。

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

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

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

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

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

この例では、イベント登録に Action を含めると作成される P Standard Edition ventJob オブジェクトで動的モジュールを使用する方法を示します。まず、タイマーオブジェクトを作成して有効にしてから、タイマーの間隔を 500 (ミリ秒) に設定します。コマンドレットは Register-ObjectEvent 、タイマーオブジェクトの Elapsed イベントを登録します。 P Standard Edition ventJob オブジェクトは変数に$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

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

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

パラメーター

-Action

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

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

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

Type:	ScriptBlock
Position:	101
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-EventName

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

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

Type:	String
Position:	1
Default value:	None
Required:	True
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

-InputObject

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

Type:	PSObject
Position:	0
Default value:	None
Required:	True
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

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

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

Type:	String
Position:	100
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SupportEvent

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

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

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 オブジェクトを返します。

メモ

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

Register-ObjectEvent

構文

説明

例

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

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

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

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

パラメーター

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

入力

出力

メモ

フィードバック

その他のリソース

Register-ObjectEvent

構文

説明

例

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

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

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

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

パラメーター

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

入力

出力

メモ

関連リンク

フィードバック

その他のリソース

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