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 将生成一个行断点对象 (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 关键字停止执行。 替代值（和默认值）为 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 脚本中设置三个行断点。 它将在脚本中每个指定行上的第 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：在运行空间中设置断点

在此示例中，将启动一个作业。 运行空间存储在变量中，并通过“运行空间”参数传递到 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。

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

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

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

-Command

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

执行正好在执行每个命令的每个实例之前停止。 如果该命令是一个函数，则执行在每次调用该函数时以及在每个开始、过程和结束部分上停止。

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

-Line

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

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

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

-Mode

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

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

• Write - 在新值写入变量前立即停止执行。
• 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

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

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

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

-Variable

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

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

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

输入

None

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

输出

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

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

备注

PowerShell 包含 Set-PSBreakpoint 的以下别名：

• 所有平台：

  • sbp

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

• 当你在多个行、命令或变量上设置断点时，Set-PSBreakpoint 将为每个条目生成一个断点对象。

• 当在命令提示符下在函数或变量上设置断点时，你可以在创建函数或变量之前或之后设置断点。

相关链接

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