Set-PSBreakpoint

模組:

Microsoft.PowerShell.Utility

在行、命令或變數上設定中斷點。

Syntax

Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Column] <Int32>]
   [-Line] <Int32[]>
   [-Script] <String[]>
   [<CommonParameters>]

Set-PSBreakpoint
   [-Action <ScriptBlock>]
   -Command <String[]>
   [[-Script] <String[]>]
   [<CommonParameters>]

Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Script] <String[]>]
   -Variable <String[]>
   [-Mode <VariableAccessMode>]
   [<CommonParameters>]

Description

Cmdlet 會在 Set-PSBreakpoint 腳本或目前會話中執行的任何命令中設定斷點。 當在另一個斷點停止時，您可以使用 Set-PSBreakpoint 來設定斷點，再執行腳本或執行命令，或在偵錯期間設定斷點。

Set-PSBreakpoint 無法在遠端電腦上設定斷點。 若要在遠端電腦上執行指令碼偵錯，請將指令碼複製到本機電腦，然後在本機偵錯。

每個 Set-PSBreakpoint 命令都會建立下列三種類型的斷點之一：

• 行斷點 - 在特定行和數據行座標上設定斷點。
• 命令斷點 - 在命令和函式上設定斷點。
• 變數斷點 - 設定變數上的斷點。

您可以在單 Set-PSBreakpoint 一命令中的多行、命令或變數上設定斷點，但每個 Set-PSBreakpoint 命令只會設定一種類型的斷點。

在斷點上，PowerShell 會暫時停止執行，並將控制權提供給調試程式。 命令提示字元會變更為 DBG\>，而且一組調試程式命令可供使用。 不過，您可以使用 Action 參數來指定替代回應，例如斷點的條件或指示來執行其他工作，例如記錄或診斷。

Cmdlet Set-PSBreakpoint 是數個專為偵錯 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) ，其中包含斷點標識符和叫用計數。

範例 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 變數上設定斷點。 它會使用 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 腳本中設定三行斷點。 它會在指令碼中每一指定行上的欄位 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

參數

-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。

Column 值會與 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、 或 函式名稱。 允許使用萬用字元。

執行會在每個命令的每個執行個體執行之前停止。 如果命令是函式，執行就會在每次呼叫函式時，以及在 BEGIN、PROCESS 及 END 區段中停止。

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 參數時，這個參數才有效。 此模式適用於命令中設定的所有中斷點。 此參數可接受的值為：

• 寫入 - 在將新值寫入變數之前立即停止執行。
• Read - 讀取 變數時停止執行，亦即存取其值時，要指派、顯示或使用。 在讀取模式中，變數的值變更時不會停止執行。
• ReadWrite - 讀取或寫入變數時停止執行。

Type:	VariableAccessMode
Accepted values:	Read, Write, ReadWrite
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

您無法使用管線將輸入傳送至 Set-PSBreakpoint。

輸出

Breakpoint object (System.Management.Automation.LineBreakpoint, System.Management.Automation.VariableBreakpoint, System.Management.Automation.CommandBreakpoint)

Set-PSBreakpoint 會傳回 物件，表示它設定的每個斷點。

備註

• Set-PSBreakpoint 無法在遠端電腦上設定斷點。 若要在遠端電腦上執行指令碼偵錯，請將指令碼複製到本機電腦，然後在本機偵錯。
• 當您在多個行、命令或變數上設定斷點時， Set-PSBreakpoint 會為每個專案產生斷點物件。
• 在命令提示字元設定函式或變數的中斷點時，您可以在建立函式或變數之前或之後設定中斷點。

相關連結

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