Register-ObjectEvent
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
、バックグラウンド ジョブとして実行されるアクションを表すジョブ オブジェクトを返します。 ジョブ コマンドレット (や Receive-Job
などGet-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 つのリモート コンピューターに PSSessions を作成し、変数に $S
保存します。 次に、 コマンドレットは Invoke-Command
、 ProcessCreationEvent.ps1
の各 PSSession でスクリプトを実行します $S
。 このアクションにより、 Enable-ProcessCreationEvent
リモート セッションに 関数が作成されます。
最後に、リモート セッションで 関数を実行 Enable-ProcessCreationEvent
します。
この関数には、Register-ObjectEvent
ManagementEventWatcher オブジェクトとその EventArrived イベントを介して、Win32_Process オブジェクトのインスタンス作成イベントをサブスクライブするコマンドが含まれています。
例 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 パラメーターの値には、、$EventSubscriber
、$Event
、$Sender
$EventArgs
、および自動変数を$Args
含めることができます。 これらの変数は、イベントに関する情報を 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 パラメーターを使用して作成されたサブスクリプションを表示または取り消すには、 コマンドレットと Unregister-Event
コマンドレットの Force パラメーターをGet-EventSubscriber
使用します。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
入力
None
オブジェクトをこのコマンドレットにパイプすることはできません。
出力
None
既定では、このコマンドレットは出力を返しません。
Action パラメーターを使用すると、このコマンドレットは PSEventJob オブジェクトを返します。
メモ
イベント、イベント サブスクリプション、およびイベント キューは、現在のセッションにのみ存在します。 現在のセッションを閉じた場合、イベント キューが破棄され、イベント サブスクリプションが取り消されます。