Set-PSBreakpoint

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

语法

Set-PSBreakpoint -Command <string[]> [[-Script] <string[]>] [-Action <scriptblock>] [<CommonParameters>]

Set-PSBreakpoint [-Script] <string[]> [-Line] <Int32[]> [[-Column] <int>] [-Action <scriptblock>] [<CommonParameters>]

Set-PSBreakpoint -Variable <string[]> [[-Script] <string[]>] [-Mode {<Read> | <Write> | <ReadWrite>}] [-Action <scriptblock>] [<CommonParameters>]

说明

Set-PSBreakpoint cmdlet 会在脚本或当前会话中运行的任何命令中设置一个断点。您可以在执行脚本或运行命令之前，或者在调试过程中在另一个断点处停止时，使用 Set-PSBreakpoint 设置断点。

注意：Set-PSBreakpoint 不能在远程计算机上设置断点。若要调试远程计算机上的脚本，请将该脚本复制到本地计算机，然后在本地调试。

每条 Set-PSBreakpoint 命令都创建以下三种断点中的一种：

-- 行断点：在特定的行和列坐标处设置断点。

-- 命令断点：在命令和函数上设置断点。

-- 变量断点：在变量上设置断点。

您可以使用一条 Set-PSBreakpoint 命令在多个行、命令或变量上设置断点，但是每条 Set-PSBreakpoint 命令只设置一种断点。

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

Set-PSBreakpoint cmdlet 是设计用于调试 Windows PowerShell 脚本的多个 cmdlet 之一。有关 Windows PowerShell 调试程序的详细信息，请参阅 about_Debuggers。

参数

-Action <scriptblock>

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

如果省略此参数或不指定操作，则会在断点处停止执行并启动调试程序。

在使用 Action 参数时，会在每个断点处运行 Action 脚本块。不会停止执行，除非脚本块包括 Break 关键字。如果您在脚本块中使用 Continue 关键字，将会继续执行，直到下一个断点。

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

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	false

-Column <int>

指定脚本文件中执行过程将会停止的列的列号。只输入一个列号。默认值是第 1 列。

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

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

是否为必需？	false
位置？	3
默认值
是否接受管道输入？	false
是否接受通配符？	false

-Command <string[]>

设置命令断点。输入命令名称（如“Get-Process”）或函数名称。允许使用通配符。

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

是否为必需？	true
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	true

-Line <Int32[]>

在脚本中设置行断点。输入一个或多个行号（以逗号分隔）。Windows PowerShell 会恰好在执行开始于每个指定行的语句之前停止。

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

是否为必需？	true
位置？	2
默认值
是否接受管道输入？	false
是否接受通配符？	false

-Mode <VariableAccessMode>

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

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

有效值包括：

-- Write：恰好在将新值写入变量之前停止执行。

-- Read：在读取变量也就是访问变量的值（目的可能是要分配、显示或使用此值）时停止执行。在 Read 模式中，当变量的值更改时，执行过程不会停止。

-- ReadWrite：在读取或写入变量时停止执行。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	false

-Script <string[]>

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

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

是否为必需？	false
位置？	1
默认值
是否接受管道输入？	false
是否接受通配符？	true

-Variable <string[]>

设置变量断点。输入以逗号分隔的变量（无美元符号 ($)）列表。

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

是否为必需？	true
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	false

<CommonParameters>

此 cmdlet 支持通用参数：-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。有关详细信息，请参阅 about_Commonparameters.

输入和输出

输入类型是指可通过管道传递给 cmdlet 的对象的类型。返回类型是指 Cmdlet 所返回对象的类型。

输入	无 不能通过管道将输入传递给 Set-PSBreakpoint。
输出	断点对象（System.Management.Automation.LineBreakpoint、System.Management.Automation.VariableBreakpoint、System.Management.Automation.CommandBreakpoint） Set-PSBreakpoint 返回一个表示它所设置的每个断点的对象。

说明

Set-PSBreakpoint 不能在远程计算机上设置断点。若要调试远程计算机上的脚本，请将该脚本复制到本地计算机，然后在本地调试。

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

在命令提示符处设置函数或变量上的断点时，您可以在创建函数或变量之前或之后设置断点。

示例 1

C:\PS>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

说明
-----------
此命令在 Sample.ps1 脚本中的第 5 行设置断点。因此，当脚本运行时，执行过程会恰好在要执行第 5 行时停止。

当您按行号设置新断点时，Set-PSBreakpoint cmdlet 会生成一个包含断点 ID 和命中计数的行断点对象 (System.Management.Automation.LineBreakpoint)，如以下输出示例中所示。

示例 2

C:\PS>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

说明
-----------
此命令在 Sample.ps1 cmdlet 中的 Increment 函数上创建一个命令断点。此脚本恰好在每次调用指定函数之前停止执行。

结果会生成一个命令断点对象。在脚本运行之前，HitCount 属性的值为 0。

示例 3

C:\PS>set-psbreakpoint -script sample.ps1 -variable Server -Mode ReadWrite

说明
-----------
此命令在 Sample.ps1 脚本中的 Server 变量上设置断点。它使用值为 ReadWrite 的 Mode 参数，以便在读取变量值之后、值发生更改之前停止执行。

示例 4

C:\PS>set-psbreakpoint -script Sample.ps1 -command "write*"

说明
-----------
此命令在 Sample.ps1 脚本中每个以“write”开头的命令（如“write-host”）上设置一个断点。

示例 5

C:\PS>set-psbreakpoint -script test.ps1 -command DiskTest `
  -action { (if $disk -gt 2) { break } }

说明
-----------
只有当 $disk 变量的值大于 2 时，此命令才会在 Test.ps1 脚本中的 DiskTest 函数处停止执行。

它使用 Set-PSBreakpoint cmdlet 在 DiskTest 函数上设置命令断点。该操作值是用于测试函数中 $disk 变量值的脚本块。

该操作使用 BREAK 关键字在满足条件时停止执行。替代项（也是默认值）是 CONTINUE。

示例 6

C:\PS>set-psbreakpoint -command checkpoint-computer

Id       : 0
Command  : checkpoint-computer
Enabled  : True
HitCount : 0
Action   :

C:\PS> function CheckLog {
>> get-eventlog -log Application | 
>> where {($_.source -like "TestApp") -and ($_.Message -like "*failed*")}
>>}
>>
C:\PS> Checklog
DEBUG: Hit breakpoint(s)
DEBUG:  Function breakpoint on 'prompt:Checklog'
C:\PS>>>

说明
-----------
此命令在 CheckLog 函数上设置断点。由于此命令未指定脚本，因此断点会设置在当前会话中运行的任何内容上。在调用函数而不是声明函数时，调试程序会中断。

示例 7

C:\PS>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

说明
-----------
此命令在 Sample.ps1 脚本中设置 3 个行断点。它在脚本中的每个指定行上的第 2 列设置一个断点。Action 参数中指定的操作适用于所有断点。

另请参阅

概念

about_Debuggers
Get-PSBreakpoint
Enable-PSBreakpoint
Disable-PSBreakpoint
Remove-PSBreakpoint
Get-PSCallStack