about_Debuggers
適用於: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
在此插入簡介。
主題
about_Debuggers
簡短描述
描述 Windows PowerShell® 偵錯工具。
詳細描述
偵錯是檢查執行中指令碼的程序，用以識別及更正指令碼指示中的錯誤。Windows PowerShell 偵錯工具設計用來協助您檢查及識別您的指令碼、函式、命令、Windows PowerShell 工作流程或運算式中的錯誤和無效率事例。
在 Windows PowerShell 4.0 中，Windows PowerShell 偵錯工具已更新為在遠端電腦上的 Windows PowerShell 主控台 (而非 ISE) 中執行的偵錯指令碼、函數、工作流程、命令或運算式。您可以執行 Enter-PSSession 以啟動互動式遠端 PowerShell 工作階段，以便在遠端電腦上設定中斷點及偵錯指令碼檔案和命令。Enter-PSSession 功能已更新，可讓您重新連接至並進入在遠端電腦上執行指令碼或命令的已斷線工作階段。如果執行中的指令碼到達中斷點，您的用戶端工作階段就會自動啟動偵錯工具。如果正在執行指令碼的已斷線工作階段遇到了中斷點，而且停止於中斷點，則在您重新連線到工作階段之後，Enter-PSSession 將會自動啟動命令列偵錯工具。
Windows PowerShell 4.0 偵錯工具也可在 Windows PowerShell 主控台或 Windows PowerShell ISE 中進行 Windows PowerShell 工作流程偵錯。
您可以使用 Windows PowerShell 偵錯工具的功能來檢查執行中的 Windows PowerShell 指令碼、函式、命令、工作流程或運算式。Windows PowerShell 偵錯工具包含一組 Cmdlet，可讓您設定中斷點、管理中斷點及檢視呼叫堆疊。
偵錯工具 CMDLET
Windows PowerShell 偵錯工具包含下列這組 Cmdlet：
Set-PsBreakpoint: Sets breakpoints on lines, variables, and
commands.
Get-PsBreakpoint: Gets breakpoints in the current session.
Disable-PsBreakpoint: Turns off breakpoints in the current session.
Enable-PsBreakpoint: Re-enables breakpoints in the current session.
Remove-PsBreakpoint: Deletes breakpoints from the current session.
Get-PsCallStack: Displays the current call stack.
啟動和停止偵錯工具
若要啟動偵錯工具，請設定一或多個中斷點。然後執行您要偵錯的指令碼、命令或函式。
當您到達中斷點時，執行作業會停止，而控制權會移交給偵錯工具。
若要停止偵錯工具，請執行指令碼、命令或函數，直到完成為止。或者，輸入"stop" 或 "t"。
偵錯工具命令
當您在 Windows PowerShell 主控台中使用偵錯工具，請使用下列命令來控制執行作業。在 Windows PowerShell ISE 中，使用 [偵錯] 功能表上的命令。
注意：如需如何在其他主應用程式中使用偵錯工具的相關資訊，請參閱主應用程式文件。
s, Step-into Executes the next statement and then stops.
v, Step-over Executes the next statement, but skips functions
and invocations. The skipped statements are
executed, but not stepped through.
o, Step-out Steps out of the current function; up one level
if nested. If in the main body, it continues to
the end or the next breakpoint. The skipped
statements are executed, but not stepped through.
c, Continue Continues to run until the script is complete or
until the next breakpoint is reached. The skipped
statements are executed, but not stepped through.
l, List Displays the part of the script that is executing.
By default, it displays the current line, five
previous lines, and 10 subsequent lines. To continue
listing the script, press ENTER.
l <m>, List Displays 16 lines of the script beginning with the
line number specified by <m>.
l <m> <n>, List Displays <n> lines of the script, beginning with the
line number specified by <m>.
q, Stop Stops executing the script, and exits the debugger.
k, Get-PsCallStack Displays the current call stack.
<Enter> Repeats the last command if it was Step (s),
Step-over (v), or List (l). Otherwise, represents a
submit action.
?, h Displays the debugger command Help.
To exit the debugger, use Stop (q).
使用這些偵錯工具命令，您即可執行指令碼、停止於關注點、檢查變數值和系統狀態，以及繼續執行指令碼，直到您找到問題為止。
注意：
如果您進入具有重新導向運算子 (如 ">") 的陳述式，則 Windows PowerShell 偵錯工具會跳過指令碼中所有剩餘的陳述式。
顯示指令碼變數的值
當您在偵錯工具內時，也可以輸入命令、顯示變數的值、使用 Cmdlet，以及在命令列執行指令碼。
您可以在進行偵錯的指令碼中顯示所有變數目前的值，但下列自動變數除外：
$_
$Args
$Input
$MyInvocation
$PSBoundParameters
如果您嘗試顯示上述任何變數的值，您會在偵錯工具使用的內部管線中取得該變數的值，而不是在指令碼中取得變數的值。
若要針對進行偵錯的指令碼顯示這些變數的值，請在指令碼中將自動變數的值指派給新變數。然後即可顯示新變數的值。
例如，
$scriptArgs = $Args
$scriptArgs
在本主題的範例中，$MyInvocation 變數的值會重新指派如下：
$scriptname = $MyInvocation.MyCommand.Path
偵錯工具環境
當您到達中斷點時，您就會進入偵錯工具環境。命令提示字元會變更，使其以 "[DBG]:" 開頭。如果您正在進行工作流程偵錯，提示字元為 "[WFDBG]"。您可以自訂提示字元。
此外，在某些主應用程式中 (如 Windows PowerShell 主控台，但不是在 Windows PowerShell 整合式指令碼環境 [ISE] 中)，巢狀提示字元會開啟以進行偵錯。您可藉由重複命令提示字元顯示的 greater-than 字元 (ASCII 62)，以偵測巢狀提示字元。
例如，下列是 Windows PowerShell 主控台中的預設偵錯提示字元：
[DBG]: PS (get-location)>>>
您可以使用 $NestedPromptLevel 自動變數來尋找巢狀層級。
此外，自動變數 $PSDebugContext 已定義於本機範圍中。您可以使用 $PsDebugContext 變數的目前狀態來判斷您是否在偵錯工具中。
例如：
if ($psdebugcontext) {"Debugging"} else {"Not Debugging"}
您可以在偵錯時使用 $PSDebugContext 變數的值。
[DBG]: PS>>> $psdebugcontext.invocationinfo
Name CommandLineParameters UnboundArguments Location
---- --------------------- ---------------- --------
= {} {} C:\ps-test\vote.ps1 (1)
偵錯和範圍
強行進入偵錯工具並不會變更您的運作範圍，但是當您到達指令碼的中斷點時，您將移入指令碼範圍。指令碼範圍是您執行偵錯工具所在範圍的子系。
若要尋找指令碼範圍中定義的變數和別名，請使用 Get-Alias 或 Get-Variable Cmdlet 的 Scope 參數。
例如，下列命令會取得本機 (指令碼) 範圍內的變數：
get-variable -scope 0
您可以將此命令縮寫為：
gv -s 0
若只要查看您在指令碼中定義以及您在偵錯時定義的變數，這是很有用的方法。
在命令列偵錯
當您設定變數中斷點或命令中斷點時，您可以只在指令碼檔案中設定中斷點。不過，根據預設，中斷點會設定於在目前工作階段中執行的任何項目。
例如，如果您在 $name 變數上設定中斷點，偵錯工具會在您執行的任何指令碼、命令、函式、指令碼 Cmdlet 或運算式中的任何 $name 變數上中斷，直到您停用或移除中斷點為止。
這可讓您在更真實的內容中偵錯您的指令碼，因為指令碼可能會受工作階段中和使用者的設定檔中的函式、變數和其他指令碼所影響。
行中斷點專屬於指令碼檔案，因此只能在指令碼檔案中設定。
工作流程偵錯
Windows PowerShell 4.0 偵錯工具可在 Windows PowerShell 主控台或 Windows PowerShell ISE 中進行 Windows PowerShell 工作流程偵錯。使用 Windows PowerShell 偵錯工具來偵錯工作流程時有一些限制。
-- You can view workflow variables while you are in the debugger, but
setting workflow variables from within the debugger is not supported.
-- Tab completion when stopped in the workflow debugger is not
available.
-- Workflow debugging works only with synchronous running of workflows from
a Windows PowerShell script. You cannot debug workflows if they are
running as a job (with the –AsJob parameter).
-- Other nested debugging scenarios--such as a workflow calling another
workflow, or a workflow calling a script--are not implemented.
下列範例示範如何進行工作流程偵錯。請注意，當偵錯工具進入工作流程函式時，偵錯工具提示字元會變更為 [WFDBG]。
PS C:\> Set-PSBreakpoint -Script C:\TestWFDemo1.ps1 -Line 8
ID Script Line Command Variable Action
-- ------ ---- ------- -------- ------
0 TestWFDemo1.ps1 8
PS C:\> C:\TestWFDemo1.ps1
Entering debug mode. Use h or ? for help.
Hit Line breakpoint on 'C:\TestWFDemo1.ps1:8'
At C:\TestWFDemo1.ps1:8 char:5
+ Write-Output -InputObject "Now writing output:"
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[WFDBG:localhost]: PS C:\>> list
3:
4: workflow SampleWorkflowTest
5: {
6: param ($MyOutput)
7:
8:* Write-Output -InputObject "Now writing output:"
9: Write-Output -Input $MyOutput
10:
11: Write-Output -InputObject "Get PowerShell process:"
12: Get-Process -Name powershell
13:
14: Write-Output -InputObject "Workflow function complete."
15: }
16:
17: # Call workflow function
18: SampleWorkflowTest -MyOutput "Hello"
[WFDBG:localhost]: PS C:\>> $MyOutput
Hello
[WFDBG:localhost]: PS C:\>> stepOver
Now writing output:
At C:\TestWFDemo1.ps1:9 char:5
+ Write-Output -Input $MyOutput
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[WFDBG:localhost]: PS C:\>> list
4: workflow SampleWorkflowTest
5: {
6: param ($MyOutput)
7:
8: Write-Output -InputObject "Now writing output:"
9:* Write-Output -Input $MyOutput
10:
11: Write-Output -InputObject "Get PowerShell process:"
12: Get-Process -Name powershell
13:
14: Write-Output -InputObject "Workflow function complete."
15: }
16:
17: # Call workflow function
18: SampleWorkflowTest -MyOutput "Hello"
19:
[WFDBG:localhost]: PS C:\>> stepOver
Hello
At C:\TestWFDemo1.ps1:11 char:5
+ Write-Output -InputObject "Get PowerShell process:"
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[WFDBG:localhost]: PS C:\>> stepOut
Get PowerShell process:
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName PSComputerName
------- ------ ----- ----- ----- ------ -- ----------- --------------
433 35 106688 128392 726 2.67 7124 powershell localhost
499 44 134244 172096 787 2.79 7452 powershell localhost
Workflow function complete.
函式偵錯
當您在具有 Begin、Process 和 End 區段的函式上設定中斷點時，偵錯工具會在每個區段的第一行中斷。
例如：
function test-cmdlet
{
begin
{
write-output "Begin"
}
process
{
write-output "Process"
}
end
{
write-output "End"
}
}
C:\PS> set-psbreakpoint -command test-cmdlet
C:\PS> test-cmdlet
Begin
Entering debug mode. Use h or ? for help.
Hit Command breakpoint on 'prompt:test-cmdlet'
test-cmdlet
[DBG]: C:\PS> c
Process
Entering debug mode. Use h or ? for help.
Hit Command breakpoint on 'prompt:test-cmdlet'
test-cmdlet
[DBG]: C:\PS> c
End
Entering debug mode. Use h or ? for help.
Hit Command breakpoint on 'prompt:test-cmdlet'
test-cmdlet
[DBG]: C:\PS>
遠端指令碼偵錯
在 Windows PowerShell 4.0 中，您可以在 Windows PowerShell 4.0 主控台的遠端工作階段中執行 Windows PowerShell 偵錯工具。Enter-PSSession 功能已更新，可讓您重新連接至並進入在遠端電腦上執行且目前正在執行指令碼的已斷線工作階段。如果執行中的指令碼到達中斷點，您的用戶端工作階段就會自動啟動偵錯工具。以下範例示範其運作方式，而中斷點設定於指令碼的第 6、11、22 和 25 行。請注意，在此範例中，當偵錯工具啟動時，有兩個識別提示字元：工作階段執行所在電腦的名稱，以及可讓您知道您在偵錯模式中的 DBG 提示字元。
Enter-Pssession -Cn localhost
[localhost]: PS C:\psscripts> Set-PSBreakpoint .\ttest19.ps1 6,11,22,25
ID Script Line Command Variable Action
-- ------ ---- ------- -------- ------
0 ttest19.ps1 6
1 ttest19.ps1 11
2 ttest19.ps1 22
3 ttest19.ps1 25
[localhost]: PS C:\psscripts> .\ttest19.ps1
Hit Line breakpoint on 'C:\psscripts\ttest19.ps1:11'
At C:\psscripts\ttest19.ps1:11 char:1
+ $winRMName = "WinRM"
+ ~
[localhost]: [DBG]: PS C:\psscripts>> list
6: 1..5 | foreach { sleep 1; Write-Output "hello2day $_" }
7: }
8:
9: $count = 10
10: $psName = "PowerShell"
11:* $winRMName = "WinRM"
12: $myVar = 102
13:
14: for ($i=0; $i -lt $count; $i++)
15: {
16: sleep 1
17: Write-Output "Loop iteration is: $i"
18: Write-Output "MyVar is $myVar"
19:
20: hello2day
21:
[localhost]: [DBG]: PS C:\psscripts>> stepover
At C:\psscripts\ttest19.ps1:12 char:1
+ $myVar = 102
+ ~
[localhost]: [DBG]: PS C:\psscripts>> quit
[localhost]: PS C:\psscripts> Exit-PSSession
PS C:\psscripts>
範例
此測試指令碼會偵測作業系統的版本並顯示適當的系統訊息。其中包含函式、函式呼叫和變數。
下列命令顯示測試指令碼檔案的內容：
c:>\PS-test> get-content test.ps1
function psversion {
"Windows PowerShell " + $psversiontable.psversion
if ($psversiontable.psversion.major -lt 2) {
"Upgrade to Windows PowerShell 2.0!"
}
else {
"Have you run a background job today (start-job)?"
}
}
$scriptname = $MyInvocation.MyCommand.Path
psversion
"Done $scriptname."
若要啟動，請在指令碼中設定感興趣的中斷點，例如行、命令、變數或函式。
首先在目前目錄中的 Test.ps1 指令碼的第一行上建立行中斷點。
PS C:\ps-test> set-psbreakpoint -line 1 -script test.ps1
您可以將此命令縮寫為：
PS C:\ps-test> spb 1 -s test.ps1
此命令會傳回行中斷點物件 (System.Management.Automation.LineBreakpoint)。
Column : 0
Line : 1
Action :
Enabled : True
HitCount : 0
Id : 0
Script : C:\ps-test\test.ps1
ScriptName : C:\ps-test\test.ps1
現在，啟動指令碼。
PS C:\ps-test> .\test.ps1
當指令碼到達第一個中斷點時，中斷點訊息會指出偵錯工具為使用中狀態。該訊息會描述中斷點並預覽指令碼的第一行 (這是函式宣告)。命令提示字元也會變更，表示偵錯工具擁有控制權。
預覽行包含指令碼名稱和所預覽命令的行號。
Entering debug mode. Use h or ? for help.
Hit Line breakpoint on 'C:\ps-test\test.ps1:1'
test.ps1:1 function psversion {
DBG>
使用 Step 命令 (s) 來執行指令碼中的第一個陳述式以及預覽下一個陳述式。下一個陳述式會使用 $MyInvocation 自動變數，將 $ScriptName 變數的值設定為指令碼檔案的路徑和檔名。
DBG> s
test.ps1:11 $scriptname = $MyInvocation.MyCommand.Path
此時不會填入 $ScriptName 變數，但您可藉由顯示其值來驗證此變數的值。在此情況下，此值為 $null。
DBG> $scriptname
DBG>
使用另一個 Step 命令 (s) 來執行目前的陳述式以及預覽指令碼中的下一個陳述式。下一個陳述式會呼叫 PsVersion 函式。
DBG> s
test.ps1:12 psversion
此時會填入 $ScriptName 變數，但您可藉由顯示其值來驗證此變數的值。在此情況下，此值設定為指令碼路徑。
DBG> $scriptname
C:\ps-test\test.ps1
使用另一個 Step 命令來執行函式呼叫。按 ENTER 鍵，或輸入 "s" 代表 Step。
DBG> s
test.ps1:2 "Windows PowerShell " + $psversiontable.psversion
偵錯訊息包含函式中的陳述式預覽。若要執行此陳述式並預覽函式中的下一個陳述式，您可以使用 Step 命令。但是在此情況下，請使用 Step-Out 命令 (o)。它會完成函式執行 (除非到達中斷點) 並進入指令碼中的下一個陳述式。
DBG> o
Windows PowerShell 2.0
Have you run a background job today (start-job)?
test.ps1:13 "Done $scriptname"
因為我們已在指令碼中的最後一個陳述式，所以 Step、Step-Out 和 Continue 命令的作用相同。在此情況下，請使用 Step-Out (o)。
Done C:\ps-test\test.ps1
PS C:\ps-test>
Step-Out 命令會執行最後一個命令。標準命令提示字元會指出偵錯工具已結束並將控制權交回給命令處理器。
現在，再次執行偵錯工具。首先，若要刪除目前的中斷點，請使用 Get-PsBreakpoint 和 Remove-PsBreakpoint Cmdlet。(如果您認為您可能會重複使用中斷點，請使用 Disable-PsBreakpoint Cmdlet 而不是 Remove-PsBreakpoint)。
PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint
您可以將此命令縮寫為：
PS C:\ps-test> gbp | rbp
或者，撰寫函式 (如下列函數) 以執行命令：
function delbr { gbp | rbp }
現在，在 $scriptname 變數上建立中斷點。
PS C:\ps-test> set-psbreakpoint -variable scriptname -script test.ps1
您可以將此命令縮寫為：
PS C:\ps-test> sbp -v scriptname -s test.ps1
現在，啟動指令碼。指令碼會到達中斷點變數。預設模式為 Write，所以會在變更此變數值的陳述式前面停止執行。
PS C:\ps-test> .\test.ps1
Hit Variable breakpoint on 'C:\ps-test\test.ps1:$scriptname'
(Write access)
test.ps1:11 $scriptname = $MyInvocation.mycommand.path
DBG>
顯示 $null $scriptname 變數目前的值 ($null)。
DBG> $scriptname
DBG>
使用 Step 命令 (s) 來執行填入此變數的陳述式。然後，顯示 $scriptname 變數的新值。
DBG> $scriptname
C:\ps-test\test.ps1
使用 Step 命令 (s) 來預覽指令碼中的下一個陳述式。
DBG> s
test.ps1:12 psversion
下一個陳述式是 PsVersion 函式的呼叫。若要跳過此函式但仍加以執行，請使用 Step-Over 命令 (v)。如果當您使用 Step-Over 函式時，您已在此函式中，則沒有作用。函式呼叫會顯示，但不會執行。
DBG> v
Windows PowerShell 2.0
Have you run a background job today (start-job)?
test.ps1:13 "Done $scriptname"
Step-Over 函式會執行此函式，而且預覽指令碼中的下一個陳述式 (可列印最後一行)。
使用 Stop 命令 (t) 來結束偵錯工具。命令提示字元會還原成標準命令提示字元。
C:\ps-test>
若要刪除中斷點，請使用 Get-PsBreakpoint 和 Remove-PsBreakpoint Cmdlet。
PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint
在 PsVersion 函式上建立新的命令中斷點。
PS C:\ps-test> Set-PsBreakpoint -command psversion -script test.ps1
您可以將此命令縮寫為：
PS C:\ps-test> sbp -c psversion -s test.ps1
現在，執行指令碼。
PS C:\ps-test> .\test.ps1
Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion'
test.ps1:12 psversion
DBG>
此指令碼會到達函式呼叫處的中斷點。此時，尚未呼叫此函式。這樣您就有機會使用 Set-PsBreakpoint 的 Action 參數來設定執行中斷點的條件，或執行準備或診斷工作，例如啟動記錄檔或叫用診斷或安全性指令碼。
若要設定動作，請使用 Continue 命令 (c) 來結束指令碼，並使用 Remove-PsBreakpoint 命令來刪除目前的中斷點。(中斷點是唯讀的，所以您無法將動作加入至目前的中斷點)。
DBG> c
Windows PowerShell 2.0
Have you run a background job today (start-job)?
Done C:\ps-test\test.ps1
PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint
PS C:\ps-test>
現在，建立具有動作的新命令中斷點。下列命令會設定具有動作的命令中斷點，該動作會在呼叫函式時記錄 $scriptname 變數的值。因為動作中未使用 Break 關鍵字，所以不會停止執行。(倒單引號 (') 是行接續字元)。
PS C:\ps-test> set-psbreakpoint -command psversion -script test.ps1 `
-action { add-content "The value of `$scriptname is $scriptname." `
-path action.log}
您也可以加入可設定中斷點條件的動作。在下列命令中，只有在執行原則設為 RemoteSigned (仍允許您執行指令碼的最具限制性原則) 時，才會執行命令中斷點。(倒單引號 (') 是接續字元)。
PS C:\ps-test> set-psbreakpoint -script test.ps1 -command psversion `
-action { if ((get-executionpolicy) -eq "RemoteSigned") { break }}
動作中的 Break 關鍵字會指示偵錯工具執行中斷點。您也可以使用 Continue 關鍵字來指示偵錯工具執行而不中斷。因為預設關鍵字為 Continue，所以您必須指定 Break 才能停止執行。
現在，執行指令碼。
PS C:\ps-test> .\test.ps1
Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion'
test.ps1:12 psversion
因為執行原則設為 RemoteSigned，所以會在函式呼叫處停止執行。
此時，您可能想要檢查呼叫堆疊。請使用 Get-PsCallStack cmdlet 或 Get-PsCallStack 偵錯工具命令 (k)。下列命令可取得目前的呼叫堆疊。
DBG> k
2: prompt
1: .\test.ps1: $args=[]
0: prompt: $args=[]
此範例示範使用 Windows PowerShell 偵錯工具的一些方法。
如需偵錯工具 Cmdlet 的詳細資訊，輸入下列命令：
help <cmdlet-name> -full
例如，輸入：
help set-psbreakpoint -full
WINDOWS POWERSHELL 中的其他偵錯功能
除了 Windows PowerShell 偵錯工具以外，Windows PowerShell 還包含可用來偵錯指令碼和函式的其他幾項功能。
-- Windows PowerShell Integrated Scripting Environment (ISE) includes
an interactive graphical debugger. For more information, start Windows
PowerShell ISE and press F1.
-- The Set-PSDebug cmdlet offers very basic script debugging features,
including stepping and tracing.
-- Use the Set-StrictMode cmdlet to detect references to
uninitialized variables, to references to non-existent properties
of an object, and to function syntax that is not valid.
-- Add diagnostic statements to a script, such as statements that
display the value of variables, statements that read input from
the command line, or statements that report the current
instruction. Use the cmdlets that contain the Write verb for
this task, such as Write-Host, Write-Debug, Write-Warning, and
Write-Verbose.
另請參閱
Disable-PsBreakpoint
Enable-PsBreakpoint
Get-PsBreakpoint
Get-PsCallStack
Remove-PsBreakpoint
Set-PsBreakpoint
Set-PsDebug
Set-Strictmode
Write-Debug
Write-Verbose