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 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 将生成一个包含断点 ID 和命中计数的行断点对象（System.Management.Automation.LineBreakpoint）。

示例 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：对以指定文本开头的每个命令设置断点

本示例在以“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 关键字停止执行。替代项（和默认值）为“继续”。

示例 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 存储在变量中，并使用 Runspace 参数传递给 Set-PSBreakPoint 命令。

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

$runspace = Get-Runspace -Id 1

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

参数

-Action

指定在每个断点而不是中断时运行的命令。输入包含命令的脚本块。可以使用此参数设置条件断点或执行其他任务，例如测试或日志记录。

如果省略此参数或未指定任何作，则执行会在断点处停止，调试器将启动。

使用 Action 参数时，作脚本块在每个断点上运行。除非脚本块包含 Break 关键字，否则执行不会停止。如果在脚本块中使用 Continue 关键字，则执行将恢复到下一个断点。

有关详细信息，请参阅 about_Script_Blocks、about_Break和 about_Continue。

类型:	ScriptBlock
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Column

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

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

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

类型:	Int32
Position:	2
默认值:	1
必需:	False
接受管道输入:	False
接受通配符:	False

-Command

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

在执行每个命令的每个实例之前，执行将停止。如果命令是函数，则每次调用函数时，执行都会停止，并在每个 BEGIN、PROCESS 和 END 节中停止。

类型:	String[]
别名:	C
Position:	Named
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	True

-Line

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

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

类型:	Int32[]
Position:	1
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-Mode

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

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

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

类型:	VariableAccessMode
接受的值:	Read, Write, ReadWrite
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Runspace

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

此参数已在 PowerShell 7.2 中添加。

类型:	Runspace
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Script

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

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

类型:	String[]
Position:	0
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Variable

指定此 cmdlet 设置断点的变量数组。输入不带美元符号的变量的逗号分隔列表（$）。

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

类型:	String[]
别名:	V
Position:	Named
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

输入

None

不能通过管道将对象传递给此 cmdlet。

输出

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

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

备注

PowerShell 包含以下 Set-PSBreakpoint别名：

所有平台：
- sbp
Set-PSBreakpoint 无法在远程计算机上设置断点。若要在远程计算机上调试脚本，请将脚本复制到本地计算机，然后将其在本地调试。
在多个行、命令或变量上设置断点时，Set-PSBreakpoint 为每个条目生成断点对象。
在命令提示符处对函数或变量设置断点时，可以在创建函数或变量之前或之后设置断点。

通过