PowerShell Cmdlet - Register-ObjectEvent
 記事記号:[mg1951] 初版:2011/Sep/30

この文書は、Windows PowerShellのヘルプ機能で表示される内容を再構成したものです。

名前
    Register-ObjectEvent
    
概要
    Microsoft .NET Framework オブジェクトによって生成されたイベントをサブスクラ
    イブします。
    
構文
    Register-ObjectEvent [-InputObject] <psobject> [-EventName] <string> [[-Sour
    ceIdentifier] <string>] [[-Action] <scriptblock>] [-Forward] [-MessageData <
    psobject>] [-SupportEvent] [<CommonParameters>]
    
説明
    Register-ObjectEvent コマンドレットは、ローカル コンピューターまたはリモート 
    コンピューター上の .NET Framework オブジェクトによって生成されたイベントをサ
    ブスクライブします。
    
    サブスクライブされたイベントが発生すると、セッションのイベント キューに追加
    されます。イベント キューのイベントを取得するには、Get-Event コマンドレット
    を使用します。
    
    Register-ObjectEvent のパラメーターを使用してイベントのプロパティ値を指定し、
    キューのイベントを識別しやすくすることができます。Action パラメーターを使用
    して、サブスクライブしたイベントが発生したときに実行するアクションを指定し、
    Forward パラメーターを使用してローカル セッションのイベント キューにリモート 
    イベントを送信することもできます。
    
    イベントをサブスクライブするとき、イベント サブスクライバーがセッションに追
    加されます。セッションのイベント サブスクライバーを取得するには、Get-EventSu
    bscriber コマンドレットを使用します。サブスクリプションをキャンセルするには、
    Unregister-Event コマンドレットを使用して、セッションからイベント サブスクラ
    イバーを削除します。
    
パラメーター
    -Action <scriptblock>
        イベントを取り扱うコマンドを指定します。Action のコマンドは、イベント キ
        ューへのイベントの送信時ではなく、イベントの発生時に実行されます。コマン
        ドを中かっこ ({ }) で囲み、スクリプト ブロックを作成します。
        
        Action パラメーターの値には、イベントに関する情報を Action スクリプト ブ
        ロックに提供する、$Event、$EventSubscriber、$Sender、$SourceEventArgs、
        および $SourceArgs 自動変数を含めることができます。詳細については、「abo
        ut_Automatic_Variables」を参照してください。
        
        アクションを指定すると、Register-ObjectEvent は、そのアクションを表すイ 
        ベント ジョブ オブジェクトを返します。Job コマンドレットを使用して、イベ
        ント ジョブを管理できます。
        
        必須                         false
        位置                         102
        既定値                       なし。
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -EventName <string>
        サブスクライブするイベントを指定します。イベント名を入力します。このパラ
        メーターは必須です。
        
        このパラメーターの値は、イベント サブスクリプション用に選択する名前では
        ありません。.NET Framework オブジェクトが公開するイベントの名前です。た
        とえば、ManagementEventWatcher クラスには、"EventArrived" および "Stopp
        ed" という名前のイベントがあります。イベントのイベント名を検索するには、
        Get-Member コマンドレットを使用します。
        
        必須                         true
        位置                         2
        既定値                       なし
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -Forward [<SwitchParameter>]
        このサブスクリプションのイベントをリモート セッションに送信します。この
        パラメーターは、リモート コンピューターまたはリモート セッションのイベン
        トに登録する場合に使用します。
        
        必須                         false
        位置                         named
        既定値                       False
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -InputObject <psobject>
        イベントを生成する .NET Framework オブジェクトを指定します。オブジェクト
        が格納されている変数を入力するか、オブジェクトを取得するコマンドまたは式
        を入力します。このパラメーターは必須です。
        
        必須                         true
        位置                         1
        既定値                       なし
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -MessageData <psobject>
        このイベント サブスクリプションに関連付けられている任意の追加データを指
        定します。このパラメーターの値は、このサブスクリプションに関連付けられた
        すべてのイベントの MessageData プロパティに表示されます。
        
        必須                         false
        位置                         named
        既定値                       なし
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -SourceIdentifier <string>
        サブスクリプション用に選択した名前を指定します。選択した名前は、現在のセ
        ッションで一意でなければなりません。既定値は Windows PowerShell が割り当
        てた GUID です。
        
        このパラメーターの値は、サブスクライバー オブジェクトおよびこのサブスク
        リプションに関連付けられたすべてのイベント オブジェクトの SourceIdentifi
        er プロパティの値に表示されます。
        
        必須                         false
        位置                         101
        既定値                       GUID
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -SupportEvent [<SwitchParameter>]
        イベント サブスクリプションを非表示にします。このパラメーターは、現在の
        サブスクリプションがさらに複雑なイベント登録メカニズムの一部であり、単独
        で検出されない場合に使用します。
        
        SupportEvent パラメーターを使用して作成されたサブスクリプションを表示ま
        たはキャンセルするには、Get-EventSubscriber および Unregister-Event コマ
        ンドレットの Force パラメーターを使用します。
        
        必須                         false
        位置                         named
        既定値                       False
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    <CommonParameters>
        このコマンドレットは、次の共通パラメーターをサポートします: Verbose、
        Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
        OutBuffer、および OutVariable。詳細については、
        「get-help about_commonparameters」と入力してヘルプを参照してください。
    
入力
    なし
        パイプを使用してオブジェクトを Register-ObjectEvent に渡すことはできませ
        ん。
    
出力
    なし
        このコマンドレットは出力を生成しません。
    
メモ
        イベント、イベント サブスクリプション、およびイベント キューは、現在のセ
        ッションにのみ存在します。現在のセッションを閉じた場合、イベント キュー
        が破棄され、イベント サブスクリプションが取り消されます。
    
    -------------------------- 例 1 --------------------------
    
    C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreatio
    nEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" 
    
    C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher 
    $query 
    
    C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventAr
    rived"
    
    説明
    -----------
    この例は、新しいプロセスの開始時に生成されるイベントにサブスクライブします。
    
    このコマンドは ManagementEventWatcher オブジェクトを使用して、EventArrived 
    イベントを取得します。クエリ オブジェクトにより、イベントが Win32_Process ク
    ラスのインスタンス作成イベントであることが指定されています。
    
    -------------------------- 例 2 --------------------------
    
    C:\PS>$query = New-Object System.Management.WqlEventQuery "__InstanceCreatio
    nEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" 
    
    C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher 
    $query 
    
    C:\PS> $action = { New-Event "PowerShell.ProcessCreated" -Sender $sender -Ev
    entArguments $SourceEventArgs.NewEvent.TargetInstance } 
    
    C:\PS> register-objectEvent -inputObject $processWatcher -eventName "EventAr
    rived" -action $action
    
    Id    Name            State    HasMoreData  Location  Command
    --    ----            -----    -----------  --------  -------
    2     422cfe5a-65e... Running  True                   New-Event "PowerShe...
    
    説明
    -----------
    この例は、イベントに応えるアクションの指定方法を示しています。アクションを指
    定した場合、発生するイベントはイベント キューに追加されません。代わりに、ア
    クションがイベントに応答します。
    
    この例では、インスタンス作成イベントが発生して、新しいプロセスが開始されたこ
    とが示されると、新しい ProcessCreated イベントが発生します。
    
    アクションは、イベント アクションに対してのみ設定される $Sender および $Sour
    ceEventArgs 自動変数を使用します。
    
    Register-ObjectEvent コマンドは、バックグラウンド ジョブとして実行されるアク
    ションを表すジョブ オブジェクトを返します。Get-Job や Receive-Job などの Job 
    コマンドレットを使用して、バックグラウンド ジョブを管理できます。
    
    詳細については、「about_Jobs」を参照してください。
    
    -------------------------- 例 3 --------------------------
    
    C:\PS>$s = new-pssession -computername Server01, Server02
    
    C:\PS> invoke-command -session $s -filepath ProcessCreationEvent.ps1
    
    C:\PS> invoke-command -session $s { get-event }
    
    # ProcessCreationEvent.ps1
    
    function Enable-ProcessCreationEvent 
    { 
       $query = New-Object System.Management.WqlEventQuery "__InstanceCreationEv
       ent", ` 
           (New-Object TimeSpan 0,0,1), ` 
           "TargetInstance isa 'Win32_Process'" 
       $processWatcher = New-Object System.Management.ManagementEventWatcher $qu
       ery 
    
       $identifier = "WMI.ProcessCreated" 
       Register-ObjectEvent -input $processWatcher -eventName "EventArrived" `
          -sourceIdentifier $identifier -messageData "Test" -forward 
       } 
    } 
    
    EnableProcessCreationEvent
    
    説明
    -----------
    この例は、リモート コンピューターのオブジェクト イベントにサブスクライブする
    方法を示しています。
    
    最初のコマンドは、2 台のリモート コンピューターに PSSession を作成し、それら
    を $s 変数に保存します。
    
    2 番目のコマンドは、Invoke-Command コマンドレットの FilePath パラメーターを
    使用して、$s 内の各 PSSession で ProcessCreationEvent.ps1 スクリプトを実行し
    ます。
    
    このスクリプトには、ManagementEventWatcher オブジェクトとその EventArrived 
    イベントを介して Win32_Process オブジェクトのインスタンス作成イベントにサブス
    クライブする Register-ObjectEvent コマンドが含まれています。
    
    -------------------------- 例 4 --------------------------
    
    C:\PS>$timer  = New-Object Timers.Timer
    
    C:\PS> $timer.Interval = 500
    
    C:\PS> $job = Register-ObjectEvent -inputObject $timer -eventName Elapsed -s
    ourceIdentifier Timer.Random -Action {$random = Get-Random -Min 0 -Max 100}
    
    C:\PS> $job.gettype().fullname
    System.Management.Automation.PSEventJob
    
    C:\PS> $job | format-list -property *
    
    State         : Running
    Module        : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0
    StatusMessage :
    HasMoreData   : True
    Location      :
    Command       : $random = Get-Random -Min 0 -Max 100
    JobStateInfo  : Running
    Finished      : System.Threading.ManualResetEvent
    InstanceId    : 88944290-133d-4b44-8752-f901bd8012e2
    Id            : 1
    Name          : Timer.Random
    ChildJobs     : {}
    ...
    
    C:\PS> $timer.Enabled = $true
    
    C:\PS> & $job.module {$random}
    60
    
    C:\PS> & $job.module {$random}
    47
    
    説明
    -----------
    この例は、イベントの登録で Action を指定した場合に作成される PSEventJob オブ
    ジェクトの動的モジュールを使用する方法を示しています。
    
    最初のコマンドは New-Object コマンドレットを使用してタイマー オブジェクトを
    作成します。2 番目のコマンドは、タイマーの間隔を 500 (ミリ秒) に設定します。
    
    3 番目のコマンドは、Register-ObjectEvent コマンドレットを使用して、タイマー 
    オブジェクトの Elapsed イベントを登録します。このコマンドには、イベントを処
    理するアクションが指定されています。タイマーの間隔が経過するたびに、イベント
    が発生し、このアクションに指定されたコマンドが実行されます。ここでは、Get-Ra
    ndom コマンドレットによって、0 〜 100 の乱数が生成されて、$random 変数に保存
    されます。
    
    Register-ObjectEvent コマンドに Action パラメーターを指定すると、そのアクシ
    ョンを表す PSEventJob オブジェクトが返されます。このコマンドは、ジョブ オブ
    ジェクトを $job 変数に保存します。
    
    Register-ObjectEvent コマンドレットが返す PSEventJob オブジェクトも、イベント 
    サブスクライバーの Action プロパティで使用できます。詳細については、「Get-Eve
    ntSubscriber」を参照してください。
    
    4 番目のコマンドは、$job 変数に PSEventJob オブジェクトが格納されていることを
    示しています。5 番目のコマンドは、Format-List コマンドレットを使用して、PSEve
    ntJob オブジェクトのプロパティをすべて一覧表示します。
    
    PSEventJob には Module プロパティが存在し、そのプロパティに、アクションを実装
    する動的スクリプト モジュールが含まれています。
    
    6 番目のコマンドは、タイマーを有効にします。
    
    残りのコマンドは、呼び出し演算子 (&) を使用し、モジュール内のコマンドを呼び出
    して、$random 変数の値を表示します。呼び出し演算子を使用すると、エクスポート
    されないコマンドを含め、モジュール内のコマンドを自由に呼び出すことができます。
    ここでは、Elapsed イベントの発生時に生成される乱数を表示しています。
    
    モジュールの詳細については、「about_Modules」を参照してください。
    
関連するリンク
    Online version: http://go.microsoft.com/fwlink/?LinkID=135244
    Register-EngineEvent 
    Register-WmiEvent 
    Unregister-Event 
    Get-Event 
    New-Event 
    Remove-Event 
    Wait-Event 
    	
記事で解説しているパソコンの環境
 基本ソフト: Windows 7
 キーワード: Windows PowerShell、ヘルプ、Cmdlet、Register-ObjectEvent
ご利用数: 1858238
感想・要望・問い合わせは こちら