PowerShell Cmdlet - Set-PSBreakpoint
 記事記号:[mg1989] 初版:2011/Sep/30

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

名前
    Set-PSBreakpoint
    
概要
    行、コマンド、または変数にブレークポイントを設定します。
    
構文
    Set-PSBreakpoint -Command <string[]> [[-Script] <string[]>] [-Action <script
    block>] [<CommonParameters>]
    
    Set-PSBreakpoint [-Script] <string[]> [-Line] <Int32[]> [[-Column] <int>] [-
    Action <scriptblock>] [<CommonParameters>]
    
    Set-PSBreakpoint -Variable <string[]> [[-Script] <string[]>] [-Mode {Read | 
    Write | ReadWrite}] [-Action <scriptblock>] [<CommonParameters>]
    
説明
    Set-PSBreakpoint コマンドレットは、スクリプトまたは現在のセッションで実行さ
    れている任意のコマンドに、ブレークポイントを設定します。スクリプトを実行する
    前、コマンドを実行する前、または他のブレークポイントで停止した際のデバッグ中
    に、Set-PSBreakpoint を使用してブレークポイントを設定できます。
    
    注: Set-PSBreakpoint では、リモート コンピューターにブレークポイントを設定す
    ることはできません。リモート コンピューターでスクリプトをデバッグするには、
    スクリプトをローカル コンピューターにコピーしてからローカルでデバッグします。
    
    各 Set-PSBreakpoint コマンドでは、次の 3 種類のブレークポイントのいずれかが
    作成されます。
      -- 行ブレークポイント:  特定の行および列座標でブレークポイントを設定します。
      -- コマンド ブレークポイント:  コマンドおよび関数にブレークポイントを設定
         します。
      -- 変数ブレークポイント:  変数にブレークポイントを設定します。
    
    複数の行、複数のコマンド、または単一の Set-PSBreakpoint コマンドの複数の変数
    にブレークポイントを設定できます。ただし、それぞれの Set-PSBreakpoint コマン
    ドに対して 1 種類のブレークポイントのみを設定できます。
    
    ブレークポイントで Windows PowerShell の実行が一時停止され、デバッガーに制御
    が渡されます。コマンド プロンプトが "DBG>" に変わり、一連のデバッガー コマン
    ドが使用できるようになります。ただし、Action パラメーターを使用して、ブレー
    クポイントの条件や、ログや診断などの追加タスクを実行する命令など、別の応答を
    指定することもできます。
     
    Set-PSBreakpoint コマンドレットは、Windows PowerShell スクリプトのデバッグ用
    に設計された複数のコマンドレットの 1 つです。Windows PowerShell デバッガーの
    詳細については、「about_Debuggers」を参照してください。
    
パラメーター
    -Action <scriptblock>
        停止する代わりに各ブレークポイントで実行されるコマンドを指定します。コマ
        ンドを含んでいるスクリプト ブロックを入力します。このパラメーターを使用
        して条件付きブレークポイントを設定したり、テストやログなどの他のタスクを
        実行したりできます。
        
        このパラメーターを省略するか、アクションを指定しないと、実行がブレークポ
        イントで停止し、デバッガーが起動します。
        
        Action パラメーターを使用すると、各ブレークポイントで Action スクリプト 
        ブロックが実行されます。スクリプト ブロックに Break キーワードが含まれて
        いなければ、実行が停止されることはありません。スクリプト ブロックに Cont
        inue キーワードを使用すると、次のブレークポイントまで実行が再開されます。
        
        詳細については、「about_Script_Blocks」、「about_Break」、および「about_
        Continue」を参照してください。
        
        必須                         false
        位置                         named
        既定値                       
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -Column <int>
        スクリプト ファイル内で、実行を停止する列の列番号を指定します。列番号を 
        1 つだけ入力します。既定値は列 1 です。
        
        ブレークポイントを指定するには、Column の値と Line パラメーターの値を使
        用します。Line パラメーターが複数行を指定すると、Column パラメーターは指
        定された各行の指定された列にブレークポイントを設定します。Windows PowerS
        hell は、指定された行および列位置に対象の文字を含んでいるステートメント
        または式の前で実行を停止します。
        
        列は、列番号 1 から始まる (0 ではない) 左上の余白から数えます。スクリプ
        ト内に存在しない列を指定すると、エラーは宣言されませんがブレークポイント
        が実行されません。
        
        必須                         false
        位置                         3
        既定値                       
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -Command <string[]>
        コマンドのブレークポイントを設定します。"Get-Process" などのコマンド名、
        または関数名を入力します。ワイルドカードを使用できます。
        
        各コマンドの各インスタンスが実行される直前に実行が停止されます。コマンド
        が関数である場合は、関数が呼び出されるたび、また、BEGIN、PROCESS、END の
        各セクションで、実行が停止されます。
        
        必須                         true
        位置                         named
        既定値                       
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する true
        
    -Line <Int32[]>
        スクリプトで行のブレークポイントを設定します。1 つまたは複数の行番号をコ
        ンマで区切って入力します。Windows PowerShell は、指定された各行で始まる
        ステートメントが実行される直前に停止します。
        
        行は、行番号 1 から始まる (0 ではない) スクリプト ファイルの左上の余白か
        ら数えます。空白行を指定すると、次の非空白行の前で実行が停止されます。行
        が範囲外にあると、ブレークポイントは機能しません。
        
        必須                         true
        位置                         2
        既定値                       
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -Mode <VariableAccessMode>
        変数のブレークポイントをトリガーするアクセス モードを定義します。既定値
        は Write です。
        
        このパラメーターは、Variable パラメーターがコマンドで使用されている場合
        にのみ有効です。モードは、コマンドに設定されているすべてのブレークポイン
        トに適用されます。
        
        有効な値は次のとおりです。
        
        -- Write: 新しい値が変数に書き込まれる直前に実行が停止します。
        
        --  Read: 変数が読み取られる際、つまり、割り当て、表示、または使用のいず
            れかの目的で変数の値がアクセスされたときに実行が停止します。Read モ
            ードでは、変数の値が変更されても実行は停止しません。
        
        --  ReadWrite: 変数の読み取りまたは書き込みの際に実行が停止します。
        
        必須                         false
        位置                         named
        既定値                       
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    -Script <string[]>
        指定したそれぞれのスクリプト ファイルにブレークポイントを設定します。1 
        つ以上のスクリプト ファイルのパスとファイル名を入力します。ファイルが現
        在のディレクトリにある場合は、パスを省略できます。ワイルドカードを使用で
        きます。
        
        既定では、変数のブレークポイントとコマンドのブレークポイントは、現在のセ
        ッションで実行されているコマンドに設定されます。このパラメーターは、行ブ
        レークポイントを設定する場合にのみ必須です。
        
        必須                         false
        位置                         1
        既定値                       
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する true
        
    -Variable <string[]>
        変数のブレークポイントを設定します。ドル記号 ($) を付けずに変数のコンマ
        区切り一覧を入力します。
        
        Mode パラメーターを使用して、ブレークポイントをトリガーするアクセス モー
        ドを定義します。既定の Write モードでは、新しい値が変数に書き込まれる直
        前に実行が停止します。
        
        必須                         true
        位置                         named
        既定値                       
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    <CommonParameters>
        このコマンドレットは、次の共通パラメーターをサポートします: Verbose、
        Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
        OutBuffer、および OutVariable。詳細については、
        「get-help about_commonparameters」と入力してヘルプを参照してください。
    
入力
    なし
        パイプを使用して入力を Set-PSBreakpoint に渡すことはできません。
    
出力
    ブレークポイント オブジェクト (System.Management.Automation.LineBreakpoint、
    System.Management.Automation.VariableBreakpoint、System.Management.Automatio
    n.CommandBreakpoint)
        Set-PSBreakpoint は、設定した各ブレークポイントを表すオブジェクトを返し
        ます。
    
メモ
        Set-PSBreakpoint では、リモート コンピューターにブレークポイントを設定す
        ることはできません。リモート コンピューターでスクリプトをデバッグするに
        は、スクリプトをローカル コンピューターにコピーしてからローカルでデバッ
        グします。
        
        複数の行、コマンド、または変数にブレークポイントを設定すると、Set-PSBrea
        kpoint はエントリごとにブレークポイント オブジェクトを生成します。
        
        コマンド プロンプトで関数または変数にブレークポイントを設定する場合は、
        関数または変数の作成前でも作成後でもブレークポイントを設定できます。
    
    -------------------------- 例 1 --------------------------
    
    C:\PS>set-psbreakpoint -script sample.ps1 -line 5
    
    Column     : 0
    Line       : 5
    Action     :
    Enabled    : True
    HitCount   : 0
    Id         : 0
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1
    
    説明
    -----------
    このコマンドは、Sample.ps1 スクリプト内の行 5 にブレークポイントを設定します。
    結果として、スクリプトを実行すると、行 5 が実行される直前に実行が停止されま
    す。
    
    行番号によって新しいブレークポイントを設定すると、Set-PSBreakpoint コマンド
    レットは、次のサンプル出力に示されているようにブレークポイント ID およびヒッ
    ト カウントが含まれる行ブレークポイント オブジェクト (System.Management.Auto
    mation.LineBreakpoint) を生成します。
    
    -------------------------- 例 2 --------------------------
    
    C:\PS>set-psbreakpoint -command Increment -script sample.ps1
    
    Command    : Increment
    Action     :
    Enabled    : True
    HitCount   : 0
    Id         : 1
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1
    
    説明
    -----------
    このコマンドは、Sample.ps1 コマンドレットの Increment 関数にコマンド ブレー
    クポイントを作成します。スクリプトは、指定された関数を呼び出す直前に実行を停
    止します。
    
    この結果がコマンド ブレークポイント オブジェクトになります。スクリプトの実行
    前、HitCount プロパティの値は 0 です。
    
    -------------------------- 例 3 --------------------------
    
    C:\PS>set-psbreakpoint -script sample.ps1 -variable Server -Mode ReadWrite
    
    説明
    -----------
    このコマンドは、Sample.ps1 スクリプト内の Server 変数にブレークポイントを設
    定します。ReadWrite 値と共に Mode パラメーターを使用して、変数値が読み取られ
    たときや変数値が変更される直前に実行を停止します。
    
    -------------------------- 例 4 --------------------------
    
    C:\PS>set-psbreakpoint -script Sample.ps1 -command "write*"
    
    説明
    -----------
    このコマンドは、"write-host" などの "write" で始まる Sample.ps1 スクリプト内
    のすべてのコマンドにブレークポイントを設定します。
    
    -------------------------- 例 5 --------------------------
    
    C:\PS>set-psbreakpoint -script test.ps1 -command DiskTest `
      -action { (if $disk -gt 2) { break } }
    
    説明
    -----------
    このコマンドは、$disk 変数の値が 2 よりも大きい場合にのみ、Test.ps1 スクリプ
    ト内の DiskTest 関数で実行を停止します。
    
    このコマンドは、Set-PSBreakpoint コマンドレットを使用して DiskTest 関数にコ
    マンド ブレークポイントを設定します。アクションの値は、関数で $disk 変数の値
    をテストするスクリプト ブロックになります。
    
    このアクションでは、条件が満たされたときに Break キーワードを使用して実行が
    停止されます。代わりに使用できるのは (および既定値は) CONTINUE です。
    
    -------------------------- 例 6 --------------------------
    
    C:\PS>set-psbreakpoint -command checkpoint-computer
    
    Id       : 0
    Command  : checkpoint-computer
    Enabled  : True
    HitCount : 0
    Action   :
    
    C:\PS> function CheckLog {
    >> get-eventlog -log Application | 
    >> where {($_.source -like "TestApp") -and ($_.Message -like "*failed*")}
    >>}
    >>
    C:\PS> Checklog
    DEBUG: Hit breakpoint(s)
    DEBUG:  Function breakpoint on 'prompt:Checklog'
    C:\PS>>>
    
    説明
    -----------
    このコマンドは、CheckLog 関数にブレークポイントを設定します。このコマンドは
    スクリプトを指定しないため、現在のセッションで実行されているものにブレークポ
    イントが設定されます。デバッガーは、関数の宣言時ではなく呼び出し時に割り込み
    ます。
    
    -------------------------- 例 7 --------------------------
    
    C:\PS>set-psbreakpoint -script sample.ps1 -line 1, 14, 19 -column 2 -action 
    {&(log.ps1)}
    
    Column     : 2
    Line       : 1
    Action     :
    Enabled    : True
    HitCount   : 0
    Id         : 6
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1
    
    Column     : 2
    Line       : 14
    Action     :
    Enabled    : True
    HitCount   : 0
    Id         : 7
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1
    
    Column     : 2
    Line       : 19
    Action     :
    Enabled    : True
    HitCount   : 0
    Id         : 8
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1
    
    説明
    -----------
    このコマンドは、Sample.ps1 スクリプトに 3 つの行ブレークポイントを設定します。
    スクリプトで指定された各行で、列 2 に 1 つのブレークポイントを設定します。Act
    ion パラメーターで指定されたアクションは、すべてのブレークポイントに適用され
    ます。
    
関連するリンク
    Online version: http://go.microsoft.com/fwlink/?LinkID=113449
    about_Debuggers 
    Get-PSBreakpoint 
    Enable-PSBreakpoint 
    Disable-PSBreakpoint 
    Remove-PSBreakpoint 
    Get-PSCallStack 
    	
記事で解説しているパソコンの環境
 基本ソフト: Windows 7
 キーワード: Windows PowerShell、ヘルプ、Cmdlet、Set-PSBreakpoint
ご利用数: 1857826
感想・要望・問い合わせは こちら