次の方法で共有

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: 変数の値に応じてブレークポイントを設定する

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

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 {($_.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」を参照してください。

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

-Column

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

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

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

型: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

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

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

  • 書き込み - 新しい値が変数に書き込まれる直前に実行を停止します。
  • 読み取り - 変数の読み取り時、つまり値にアクセスするときに、割り当て、表示、または使用されるときに実行を停止します。 Read モードでは、変数の値が変更されたときは実行を停止しません。
  • ReadWrite - 変数の読み取りまたは書き込み時に実行を停止します。
型:VariableAccessMode
指定可能な値:Read, Write, ReadWrite
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Runspace

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

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

型:Runspace
配置: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 は、設定した各ブレークポイントを表すオブジェクトを返します。

メモ

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

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

    • sbp

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

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

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