Set-PSBreakpoint

模組:

Microsoft.PowerShell.Utility

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

語法

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

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

範例 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 關鍵詞，在符合條件時停止執行。 替代專案（和預設值）是 繼續。

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

類型:	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

-Script

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

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

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

-Variable

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

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

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

輸入

None

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

輸出

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

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

備註

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

相關連結

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