Set-PSBreakpoint

  • リファレンス
モジュール:
Microsoft.PowerShell.Utility

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

構文

Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Column] <Int32>]
   [-Line] <Int32[]>
   [-Script] <String[]>
   [-Runspace <Runspace>]
   [<CommonParameters>]
Set-PSBreakpoint
   [-Action <ScriptBlock>]
   -Command <String[]>
   [[-Script] <String[]>]
   [-Runspace <Runspace>]
   [<CommonParameters>]
Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Script] <String[]>]
   -Variable <String[]>
   [-Mode <VariableAccessMode>]
   [-Runspace <Runspace>]
   [<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" で始まる Sample.ps1 スクリプト内のすべてのコマンドにブレークポイントを設定します。次に例を示 Write-Hostします。

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スクリプト ブロックです。

アクションでは、キーワード (keyword)を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 {($_.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

例 8: 実行空間にブレークポイントを設定する

この例では、ジョブが開始されます。 実行空間は変数に格納され、Runspace パラメーターを使用して Set-PSBreakPoint コマンドに渡されます。

Start-Job -ScriptBlock {
    Start-Sleep -Seconds 10
}

$runspace = Get-Runspace -Id 1

Set-PSBreakpoint -Command Start-Sleep -Runspace $runspace

パラメーター

-Action

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

このパラメーターを省略し、アクションを指定しない場合、ブレークポイントに達すると実行が停止し、デバッガーが開始されます。

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

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

Type:ScriptBlock
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Column

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

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

列は、最上位の左余白の先頭が列番号 1 でカウントされます (0 ではありません)。 スクリプトに存在しない列を指定した場合、エラーにはなりませんが、ブレークポイントが実行されることはありません。

Type:Int32
Position:2
Default value:1
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Command

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

各コマンドの各インスタンスが実行される直前に、実行が停止します。 コマンドが関数の場合、関数が呼び出されるたびに、BEGIN、PROCESS、および END セクションごとに実行が停止します。

Type:String[]
Aliases:C
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:True

-Line

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

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

Type:Int32[]
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Mode

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

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

  • 書き込み - 新しい値が変数に書き込まれる直前に実行を停止します。
  • 読み取り - 変数が読み取られるときの実行を停止します。つまり、変数の値にアクセスするときに、割り当て、表示、または使用されます。 Read モードでは、変数の値が変更されたときは実行を停止しません。
  • ReadWrite - 変数の読み取りまたは書き込み時に実行を停止します。
Type:VariableAccessMode
Accepted values:Read, Write, ReadWrite
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Runspace

指定した実行空間内の ブレークポイントを操作できるように、Runspace オブジェクトの ID を指定します。

このパラメーターは PowerShell 7.2 で追加されました。

Type:Runspace
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Script

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

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

Type:String[]
Position:0
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Variable

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

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

Type:String[]
Aliases:V
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

入力

None

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

出力

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

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

メモ

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

  • すべてのプラットフォーム:

    • sbp

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

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

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