Set-PSBreakpoint

モジュール:

Microsoft.PowerShell.Utility

行、コマンド、または変数にブレークポイントを設定します。

構文

Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Column] <Int32>]
   [-Line] <Int32[]>
   [-Script] <String[]>
   [<CommonParameters>]

Set-PSBreakpoint
   [-Action <ScriptBlock>]
   -Command <String[]>
   [[-Script] <String[]>]
   [<CommonParameters>]

Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Script] <String[]>]
   -Variable <String[]>
   [-Mode <VariableAccessMode>]
   [<CommonParameters>]

説明

Set-PSBreakpoint コマンドレットは、スクリプトまたは現在のセッションで実行される任意のコマンドでブレークポイントを設定します。 Set-PSBreakpoint を使用して、スクリプトを実行する前またはコマンドを実行する前、またはデバッグ中に別のブレークポイントで停止したときにブレークポイントを設定できます。

Set-PSBreakpoint リモート コンピューターにブレークポイントを設定することはできません。 リモート コンピューターでスクリプトをデバッグするには、スクリプトをローカル コンピューターにコピーし、ローカルでデバッグします。

各 Set-PSBreakpoint コマンドは、次の 3 種類のブレークポイントのいずれかを作成します。

• 行ブレークポイント - 特定の行座標と列座標にブレークポイントを設定します。
• コマンド ブレークポイント - コマンドと関数にブレークポイントを設定します。
• 変数ブレークポイント - 変数にブレークポイントを設定します。

1 つの Set-PSBreakpoint コマンドで複数の行、コマンド、または変数にブレークポイントを設定できますが、各 Set-PSBreakpoint コマンドはブレークポイントの種類を 1 つだけ設定します。

ブレークポイントでは、PowerShell は一時的に実行を停止し、デバッガーに制御を提供します。 コマンド プロンプトが DBG\>に変わり、一連のデバッガー コマンドが使用できるようになります。 ただし、Action パラメーターを使用して、ブレークポイントの条件や、ログ記録や診断などの追加タスクを実行する手順などの代替応答を指定できます。

Set-PSBreakpoint コマンドレットは、PowerShell スクリプトのデバッグ用に設計されたいくつかのコマンドレットの 1 つです。 PowerShell デバッガーの詳細については、「about_Debuggers」を参照してください。

例

例 1: 行にブレークポイントを設定する

次の使用例は、Sample.ps1 スクリプトの 5 行目にブレークポイントを設定します。 スクリプトを実行すると、5 行目が実行される直前に実行が停止します。

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

新しいブレークポイントを行番号で設定すると、Set-PSBreakpoint コマンドレットは、ブレークポイント ID とヒットカウントを含む行ブレークポイント オブジェクト (System.Management.Automation.LineBreakpoint) を生成します。

例 2: 関数にブレークポイントを設定する

この例では、Sample.ps1 コマンドレットの Increment 関数にコマンド ブレークポイントを作成します。 スクリプトは、指定された関数の各呼び出しの直前に実行を停止します。

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

結果は、コマンド ブレークポイント オブジェクトです。 スクリプトを実行する前に、HitCount プロパティの値は 0 です。

例 3: 変数にブレークポイントを設定する

次の使用例は、Sample.ps1 スクリプトの Server 変数にブレークポイントを設定します。 Mode パラメーターと値 ReadWrite を使用して、変数の値が読み取られ、値が変更される直前に実行を停止します。

Set-PSBreakpoint -Script "sample.ps1" -Variable "Server" -Mode ReadWrite

例 4: 指定したテキストで始まるすべてのコマンドにブレークポイントを設定する

次の使用例は、Write-Hostなど、"write" で始まる Sample.ps1 スクリプト内のすべてのコマンドにブレークポイントを設定します。

Set-PSBreakpoint -Script Sample.ps1 -Command "write*"

例 5: 変数の値に応じてブレークポイントを設定する

次の使用例は、DiskTest 変数の値が 2 より大きい場合にのみ、Test.ps1 スクリプトの $Disk 関数での実行を停止します。

Set-PSBreakpoint -Script "test.ps1" -Command "DiskTest" -Action { if ($Disk -gt 2) { break } }

Action の値は、関数内の $Disk 変数の値をテストするスクリプト ブロックです。

アクションでは、break キーワードを使用して、条件が満たされた場合に実行を停止します。 別の方法 (および既定値) は Continueです。

例 6: 関数にブレークポイントを設定する

次の使用例は、CheckLog 関数にブレークポイントを設定します。 このコマンドはスクリプトを指定しないため、現在のセッションで実行されるすべてのブレークポイントにブレークポイントが設定されます。 関数が宣言されている場合ではなく、関数が呼び出されたときにデバッガーが中断します。

PS> Set-PSBreakpoint -Command "checklog"
Id       : 0
Command  : checklog
Enabled  : True
HitCount : 0
Action   :

function CheckLog {
>> Get-EventLog -Log Application |
>> Where-Object {($_.Source -like "TestApp") -and ($_.Message -like "*failed*")}
>>}
>>
PS> Checklog
DEBUG: Hit breakpoint(s)
DEBUG:  Function breakpoint on 'prompt:Checklog'

例 7: 複数行にブレークポイントを設定する

次の使用例は、Sample.ps1 スクリプトに 3 行のブレークポイントを設定します。 スクリプトで指定された各行の 2 列目に 1 つのブレークポイントを設定します。 Action パラメーターで指定されたアクションは、すべてのブレークポイントに適用されます。

PS C:\> 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

パラメーター

-Action

中断するのではなく、各ブレークポイントで実行するコマンドを指定します。 コマンドを含むスクリプト ブロックを入力します。 このパラメーターを使用して、条件付きブレークポイントを設定したり、テストやログ記録などの他のタスクを実行したりできます。

このパラメーターを省略するか、アクションを指定しない場合は、ブレークポイントで実行が停止し、デバッガーが起動します。

Action パラメーターを使用すると、Action スクリプト ブロックは各ブレークポイントで実行されます。 スクリプト ブロックに break キーワードが含まれていない限り、実行は停止しません。 スクリプト ブロックで continue キーワードを使用すると、次のブレークポイントまで実行が再開されます。

詳細については、「about_Script_Blocks、about_Break、および about_Continue」を参照してください。

型:	ScriptBlock
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Column

実行を停止するスクリプト ファイル内の列の列番号を指定します。 列番号を 1 つだけ入力します。 既定値は列 1 です。

Column 値は、ブレークポイントを指定するために、Line パラメーターの値と共に使用されます。 Line パラメーターで複数行を指定した場合、Column パラメーターは、指定された各行の指定した列にブレークポイントを設定します。 PowerShell は、指定した行と列の位置にある文字を含むステートメントまたは式の前に実行を停止します。

列は、(0 ではなく) 列番号 1 で始まる左上の余白からカウントされます。 スクリプトに存在しない列を指定した場合、エラーは宣言されませんが、ブレークポイントは実行されません。

型:	Int32
配置:	2
規定値:	1
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Command

コマンド ブレークポイントを設定します。 コマンドレット名 (Get-Process、関数名など) を入力します。 ワイルドカードを使用できます。

各コマンドの各インスタンスが実行される直前に、実行が停止します。 コマンドが関数の場合、関数が呼び出されるたびに実行が停止し、各 begin、process、および end ブロックで実行が停止します。

型:	String[]
Aliases:	C
配置:	Named
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	True

-Line

スクリプト内の行ブレークポイントを設定します。 1 つ以上の行番号をコンマで区切って入力します。 PowerShell は、指定された各行で始まるステートメントを実行する直前に停止します。

行数は、スクリプト ファイルの左上の余白から行番号 1 (0 ではなく) からカウントされます。 空白行を指定すると、次の空白行以外の行の前に実行が停止します。 行が範囲外の場合、ブレークポイントはヒットしません。

型:	Int32[]
配置:	1
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Mode

変数ブレークポイントをトリガーするアクセス モードを指定します。 既定値は書き込み です。

このパラメーターは、コマンドで Variable パラメーターが使用されている場合にのみ有効です。 モードは、コマンドで設定されたすべてのブレークポイントに適用されます。 このパラメーターに使用できる値は次のとおりです。

• 書き込み - 新しい値が変数に書き込まれる直前に実行を停止します。
• 読み取り - 変数の読み取り時、つまり値にアクセスしたときに、割り当て、表示、または使用されるときに実行を停止します。 読み取りモードでは、変数の値が変化しても実行は停止しません。
• ReadWrite - 変数の読み取りまたは書き込み時に実行を停止します。

型:	VariableAccessMode
指定可能な値:	Read, Write, ReadWrite
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Script

このコマンドレットがブレークポイントを設定するスクリプト ファイルの配列を指定します。 1 つ以上のスクリプト ファイルのパスとファイル名を入力します。 ファイルが現在のディレクトリにある場合は、パスを省略できます。 ワイルドカードを使用できます。

既定では、変数ブレークポイントとコマンド ブレークポイントは、現在のセッションで実行されるすべてのコマンドに設定されます。 このパラメーターは、行ブレークポイントを設定する場合にのみ必要です。

型:	String[]
配置:	0
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Variable

このコマンドレットがブレークポイントを設定する変数の配列を指定します。 ドル記号 ($) を含まない変数のコンマ区切りのリストを入力します。

Mode パラメーターを使用して、ブレークポイントをトリガーするアクセス モードを決定します。 既定のモードである Write は、新しい値が変数に書き込まれる直前に実行を停止します。

型:	String[]
Aliases:	V
配置:	Named
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

入力

None

このコマンドレットにオブジェクトをパイプすることはできません。

出力

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

Set-PSBreakpoint は、設定した各ブレークポイントを表すオブジェクトを返します。

メモ

Windows PowerShell には、Set-PSBreakpointの次のエイリアスが含まれています。

• sbp

• Set-PSBreakpoint リモート コンピューターにブレークポイントを設定することはできません。 リモート コンピューターでスクリプトをデバッグするには、スクリプトをローカル コンピューターにコピーし、ローカルでデバッグします。

• 複数の行、コマンド、または変数にブレークポイントを設定すると、Set-PSBreakpoint はエントリごとにブレークポイント オブジェクトを生成します。

• コマンド プロンプトで関数または変数にブレークポイントを設定する場合は、関数または変数を作成する前または後にブレークポイントを設定できます。

関連リンク

• Disable-PSBreakpoint
• Enable-PSBreakpoint
• Get-PSBreakpoint
• Get-PSCallStack
• Remove-PSBreakpoint