设置 PSBreakpoint (Microsoft.PowerShell.Utility)

设置 PSBreakpoint

在行、命令或变量上设置断点。

句法

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 cmdlet 在脚本或当前会话中运行的任何命令中设置断点。您可以使用 Set-PSBreakpoint 在执行脚本或运行命令之前或在调试期间在另一个断点处停止时设置断点。

Set-PSBreakpoint 无法在远程计算机上设置断点。要在远程计算机上调试脚本，请将脚本复制到本地计算机，然后在本地进行调试。

每个 Set-PSBreakpoint 命令都会创建以下三种类型的断点之一：

• 行断点 - 在特定行和列坐标处设置断点。
• 命令断点 - 在命令和函数上设置断点。
• 变量断点 - 在变量上设置断点。

您可以在单个 Set-PSBreakpoint 命令中对多行、命令或变量设置断点，但每个 Set-PSBreakpoint 命令仅设置一种类型的断点。

在断点处，PowerShell 暂时停止执行并将控制权交给调试器。命令提示符更改为 DBG\>，并且一组调试器命令可供使用。但是，您可以使用 Action 参数指定备用响应，例如断点的条件或执行其他任务（例如日志记录或诊断）的指令。

Set-PSBreakpoint cmdlet 是设计用于调试 PowerShell 脚本的多个 cmdlet 之一。有关 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 cmdlet 会生成一个行断点对象 (System.Management.Automation.LineBreakpoint)，其中包含断点 ID 和命中数数。

示例 2：在函数上设置断点

此示例在 Sample.ps1 cmdlet 中的 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 变量上设置断点。它使用值为 ReadWrite 的 Mode 参数，在读取变量值时且值发生变化之前停止执行。

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

示例 4：在以指定文本开头的每个命令上设置断点

此示例在 Sample.ps1 脚本中以“write”开头的每个命令（例如 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 关键字停止执行。替代方案（也是默认设置）是继续。

示例 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 脚本中设置三个行断点。它在脚本中指定的每一行的第 2 列设置一个断点。 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

命名

None

False

False

False

-Column

指定脚本文件中执行停止的列的列号。仅输入一列编号。默认为第 1 列。

Column 值与 Line 参数的值一起使用来指定断点。如果 Line 参数指定多行，则 Column 参数会在每条指定行的指定列处设置断点。 PowerShell 在包含指定行和列位置处的字符的语句或表达式之前停止执行。

列从左上角开始计数，从列号 1（不是 0）开始。如果指定脚本中不存在的列，则不会声明错误，但永远不会执行断点。

整数32

2

1

False

False

False

-Command

设置命令断点。输入 cmdlet 名称，例如 Get-Process 或函数名称。允许使用通配符。

执行在每个命令的每个实例执行之前停止。如果命令是函数，则每次调用该函数时以及在每个 BEGIN、PROCESS 和 END 部分，执行都会停止。

String[]

C

命名

None

True

False

True

-Line

在脚本中设置行断点。输入一个或多个行号，以逗号分隔。 PowerShell 在执行每指定行开始的语句之前立即停止。

行数从脚本文件的左上角开始计数，从行号 1（不是 0）开始。如果指定空行，则执行将在下一个非空行之前停止。如果该行超出范围，则永远不会命中断点。

Int32[]

1

None

True

False

False

-Mode

指定触发变量断点的访问模式。默认为写入。

该参数仅当命令中使用Variable参数时有效。该模式适用于命令中设置的所有断点。该参数可接受的值为：

• 写入 - 在将新值写入变量之前立即停止执行。
• 读取 - 读取变量时停止执行，即访问其值（进行分配、显示或使用）时停止执行。在读模式下，当变量的值发生变化时，执行不会停止。
• ReadWrite - 当读取或写入变量时停止执行。

变量访问模式

读、写、读写

命名

None

False

False

False

-Runspace

指定运行空间对象的 ID，以便您可以与指定运行空间中的断点进行交互。

此参数是在 PowerShell 7.2 中添加的。

运行空间

命名

None

False

False

False

-Script

指定此 cmdlet 在其中设置断点的一组脚本文件。输入一个或多个脚本文件的路径和文件名。如果文件位于当前目录中，则可以省略路径。允许使用通配符。

默认情况下，变量断点和命令断点设置在当前会话中运行的任何命令上。仅当设置行断点时才需要此参数。

String[]

0

None

False

False

False

-Variable

指定此 cmdlet 在其上设置断点的变量数组。输入以逗号分隔的变量列表，不带美元符号 ($)。

使用模式参数来确定触发断点的访问模式。默认模式“写入”会在新值写入变量之前停止执行。

String[]

V

命名

None

True

False

False

输入

无

您无法将对象通过管道传输到此 cmdlet。

输出

命令断点

行断点

变量断点

Set-PSBreakpoint 返回一个表示它设置的每个断点的对象。

笔记

PowerShell 包含以下 Set-PSBreakpoint 别名：

• 所有平台：

  sbp