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

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：在每個以指定文字開頭的命令上設定斷點

此範例會在 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：在 Runspace 中設定斷點

在此範例中，會啟動作業。 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。

Column 值會與 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

指定觸發變數斷點的存取模式。 預設值為 Write。

只有在命令中使用 Variable 參數時，此參數才有效。 模式會套用至命令中設定的所有斷點。 此參數可接受的值為：

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

類型:	VariableAccessMode
接受的值:	Read, Write, ReadWrite
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Runspace

指定 Runspace 物件的識別碼 ，讓您可以在指定的 Runspace 中與斷點互動。

此參數已在PowerShell 7.2中新增。

類型:	Runspace
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Script

指定這個 Cmdlet 在 中設定斷點的腳本檔案陣列。 輸入一或多個腳本檔案的路徑和檔名。 如果檔案位於目前目錄中，您可以省略路徑。 允許通配符。

根據預設，變數斷點和命令斷點會在目前會話中執行的任何命令上設定。 只有在設定行斷點時，才需要此參數。

類型:	String[]
Position:	0
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Variable

指定這個 Cmdlet 設定斷點的變數陣列。 輸入不含貨幣符號的變數逗號分隔清單（$）。

使用Mode參數來判斷觸發斷點的存取模式。 預設模式 Write 會在新值寫入變數之前停止執行。

類型:	String[]
別名:	V
Position:	Named
預設值:	None
必要:	True
接受管線輸入:	False
接受萬用字元:	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