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

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

名前
    Register-EngineEvent
    
概要
    Windows PowerShell エンジンおよび New-Event コマンドレットによって生成された
    イベントにサブスクライブします。
    
構文
    Register-EngineEvent [-SourceIdentifier] <string> [[-Action] <scriptblock>] 
    [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]
    
説明
    Register-EngineEvent コマンドレットは、Windows PowerShell エンジンおよび Ne
    w-Event コマンドレットによって生成されたイベントにサブスクライブします。イ
    ベントを指定するには、SourceIdentifier パラメーターを使用します。
    
    このコマンドレットを使用して、"終了する" エンジン イベントおよび New-Event 
    コマンドレットによって生成されたイベントにサブスクライブできます。これらのイ
    ベントは、サブスクライブしなくてもセッションのイベント キューに自動的に追加
    されます。ただし、サブスクライブすることで、イベントを転送したり、イベントに
    対応するアクションを指定したり、サブスクリプションをキャンセルしたりできます。
    
    サブスクライブされたイベントが発生すると、セッションのイベント キューに追加
    されます。イベント キューのイベントを取得するには、Get-Event コマンドレット
    を使用します。
    
    イベントにサブスクライブするとき、イベント サブスクライバーがセッションに追
    加されます。セッションのイベント サブスクライバーを取得するには、Get-EventSu
    bscriber コマンドレットを使用します。サブスクリプションをキャンセルするには、
    Unregister-Event コマンドレットを使用して、セッションからイベント サブスクラ
    イバーを削除します。
    
パラメーター
    -Action <scriptblock>
        イベントを取り扱うコマンドを指定します。Action のコマンドは、イベント キ
        ューへのイベントの送信時ではなく、イベントの発生時に実行されます。コマン
        ドを中かっこ ({ }) で囲み、スクリプト ブロックを作成します。
        
        Action パラメーターの値には、イベントに関する情報を Action スクリプト ブ
        ロックに提供する、$Event、$EventSubscriber、$Sender、$SourceEventArgs、
        および $SourceArgs 自動変数を含めることができます。詳細については、「abo
        ut_Automatic_Variables」を参照してください。
        
        アクションを指定すると、Register-EngineEvent は、そのアクションを表すイ
        ベント ジョブ オブジェクトを返します。Job コマンドレットを使用して、イベ
        ント ジョブを管理できます。
        
        必須                         false
        位置                         102
        既定値                       なし
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -Forward [<SwitchParameter>]
        このサブスクリプションのイベントをローカル コンピューター上のセッション
        に送信します。このパラメーターは、リモート コンピューターまたはリモート 
        セッションのイベントに登録する場合に使用します。
        
        必須                         false
        位置                         named
        既定値                       False
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -MessageData <psobject>
        このイベントに関連付けられている追加データを指定します。このパラメーター
        の値は、イベント オブジェクトの MessageData プロパティに表示されます。
        
        必須                         false
        位置                         named
        既定値                       なし
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -SourceIdentifier <string>
        サブスクライブするイベントのソース識別子を指定します。ソース識別子は、現
        在のセッションで一意でなければなりません。このパラメーターは必須です。
        
        このパラメーターの値は、サブスクライバー オブジェクトおよびこのサブスク
        リプションに関連付けられたすべてのイベント オブジェクトの SourceIdentifi
        er プロパティの値に表示されます。
        
        必須                         true
        位置                         101
        既定値                       
        パイプライン入力を許可する   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-EngineEvent に渡すことはできません。
    
出力
    なし、または System.Management.Automation.PSEventJob
        Action パラメーターを使用した場合、Register-EngineEvent は System.Manage
        ment.Automation.PSEventJob オブジェクトを返します。それ以外の場合、出力
        は生成されません。
    
メモ
        イベント、イベント サブスクリプション、およびイベント キューは、現在のセ
        ッションにのみ存在します。現在のセッションを閉じた場合、イベント キュー
        が破棄され、イベント サブスクリプションが取り消されます。
        
    -------------------------- 例 1 --------------------------
    
    C:\PS>$s = new-pssession -computername Server01, Server02
    
    C:\PS> 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 --------------------------
    
    C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated 
    -action { $processName | add-content processLog.txt } 
    
    C:\PS> get-event
    
    C:\PS> $results = $j | receive-job
    
    C:\PS> unregister-event PowerShell.ProcessCreated
    
    説明
    -----------
    このコマンドは、Job コマンドレットを使用して、Action パラメーターの使用時に 
    Register-EngineEvent が返すイベント ジョブ オブジェクトを管理する方法を示し
    ます。
    
    イベント ジョブは、他の Windows PowerShell のジョブと同様に管理されます。詳
    細については、「about_jobs」を参照してください。この例では、ジョブの結果を取
    得するために Receive-Job コマンドレットが使用されています。
    
    セッションからジョブを削除するには、Remove-Job を使用します。イベント サブス
    クリプションをキャンセルするには、Unregister-Event コマンドレットを使用しま
    す。イベント キューのイベントを削除するには、Remove-Event を使用します。
    
関連するリンク
    Online version: http://go.microsoft.com/fwlink/?LinkID=135243
    Register-ObjectEvent 
    Register-WmiEvent 
    Unregister-Event 
    Get-Event 
    New-Event 
    Remove-Event 
    Wait-Event 
    Get-Job 
    Receive-Job 
    Remove-Job 
    Wait-Job 
    	
記事で解説しているパソコンの環境
 基本ソフト: Windows 7
 キーワード: Windows PowerShell、ヘルプ、Cmdlet、Register-EngineEvent
ご利用数: 1913377
感想・要望・問い合わせは こちら