about_Debuggers
簡単な説明
PowerShell デバッガーについて説明します。
長い説明
デバッグとは、スクリプトの実行中にスクリプトを調べて、スクリプト命令のエラーを特定して修正するプロセスです。 PowerShell デバッガーは、スクリプト、関数、コマンド、PowerShell Desired State Configuration (DSC) 構成、または式のエラーと非効率性を調べて特定するのに役立ちます。
PowerShell 5.0 以降では、PowerShell デバッガーが更新され、リモート コンピューター上のコンソールまたは Windows PowerShell Integrated Scripting Environment (ISE) で実行されているスクリプト、関数、コマンド、構成、または式をデバッグできるようになりました。
注意
Windows PowerShell ISE では、Windows PowerShellのみがサポートされます。 PowerShell 6 以降では、PowerShell の拡張機能と共に Visual Studio Code を使用する必要があります。 詳細については、「 Visual Studio Code を使用したデバッグ」を参照してください。
デバッガー コマンドレット
PowerShell デバッガーには、次のコマンドレットのセットが含まれています。
Set-PSBreakpoint
: 行、変数、およびコマンドにブレークポイントを設定します。Get-PSBreakpoint
: 現在のセッションのブレークポイントを取得します。Disable-PSBreakpoint
: 現在のセッションのブレークポイントをオフにします。Enable-PSBreakpoint
: 現在のセッションでブレークポイントを再度有効にします。Remove-PSBreakpoint
: 現在のセッションからブレークポイントを削除します。Get-PSCallStack
: 現在の呼び出し履歴を表示します。
デバッガーの開始と停止
デバッガーを起動するには、1 つ以上のブレークポイントを設定し、デバッグするスクリプト、コマンド、または関数を実行します。
ブレークポイントに到達すると、実行が停止し、制御がデバッガーに引き継がれます。
デバッガーを停止するには、完了するまでスクリプト、コマンド、または関数を実行します。
または、または と入力しますstop
t
。
デバッガー コマンド
PowerShell コンソールでデバッガーを使用する場合は、次のコマンドを使用して実行を制御します。 WINDOWS POWERSHELL ISE で、[デバッグ] メニューのコマンドを使用します。
注意
他のホスト アプリケーションでデバッガーを使用する方法については、ホスト アプリケーションのドキュメントを参照してください。
s
、StepInto
: 次のステートメントを実行し、停止します。v
、StepOver
: 次のステートメントを実行しますが、関数と呼び出しはスキップします。 スキップしたステートメントは実行されますが、ステップ スルーされることはありません。Ctrl+Break
: (ISE ですべて中断) PowerShell コンソール内で実行中のスクリプトに分割するか、ISE をWindows PowerShellします。 Windows PowerShell 2.0、3.0、4.0 の Ctrl+Break はプログラムを閉じます。 Break All は、ローカルスクリプトとリモートスクリプトの両方で動作します。o
、StepOut
: 現在の関数からステップ アウトします。入れ子になっている場合は 1 レベル上げます。 メイン本文の場合は、末尾または次のブレークポイントに進みます。 スキップしたステートメントは実行されますが、ステップ スルーされることはありません。c
、Continue
: スクリプトが完了するまで、または次のブレークポイントに達するまで、実行を続行します。 スキップしたステートメントは実行されますが、ステップ スルーされることはありません。l
、List
: 実行中のスクリプトの部分を表示します。 既定では、現在の行、前の 5 行、および 10 行が表示されます。 スクリプトの一覧を続けるには、Enter キーを押します。l <m>
、List
: で指定された<m>
行番号で始まるスクリプトの 16 行を表示します。l <m> <n>
、List
: で指定された<m>
行番号で始まるスクリプトの行を表示<n>
します。q
、Stop
、Exit
: スクリプトの実行を停止し、デバッガーを終了します。 コマンドレットを実行Debug-Job
してジョブをデバッグする場合、コマンドはExit
デバッガーをデタッチし、ジョブの実行を続行できるようにします。k
、Get-PsCallStack
: 現在の呼び出し履歴を表示します。<Enter>
: 最後のコマンドが ()、()、StepOver
またはList
l
(s
v
) の場合はStep
繰り返します。 それ以外の場合は、送信アクションを表します。?
、h
: デバッガー コマンドのヘルプを表示します。
デバッガーを終了するには、 (q
) を使用Stop
できます。
PowerShell 5.0 以降では、Exit コマンドを実行して、または Debug-Runspace
をDebug-Job
実行して開始した入れ子になったデバッグ セッションを終了できます。
これらのデバッガー コマンドを使用すると、スクリプトを実行し、問題の点で停止し、変数の値とシステムの状態を調べて、問題が特定されるまでスクリプトを実行し続けることができます。
注意
などの >
リダイレクト演算子を使用してステートメントにステップインする場合、PowerShell デバッガーはスクリプト内の残りのすべてのステートメントをステップ実行します。
スクリプト変数の値の表示
デバッガーの実行中は、コマンドの入力、変数の値の表示、コマンドレットの使用、コマンド ラインでのスクリプトの実行を行うこともできます。 次の自動変数を除き、デバッグ中のスクリプト内のすべての変数の現在の値を表示できます。
$_
$Args
$Input
$MyInvocation
$PSBoundParameters
これらの変数の値を表示すると、スクリプト内の変数の値ではなく、デバッガーが使用する内部パイプラインの変数の値が取得されます。
デバッグ中のスクリプトのこれらの変数の値を表示するには、スクリプトに行を追加して、これらの値を新しい変数に保存します。 これらの新しい行の後にブレークポイントを設定します。 その後、新しい変数の値を表示できます。
たとえば、オブジェクトに適用された
$scriptArgs = $Args
$scriptname = $MyInvocation.PSCommandPath
デバッガー環境
ブレークポイントに達すると、デバッガー環境に入ります。 コマンド プロンプトが変更され、"[DBG]:" で始まります。 また、PowerShell コンソールなどの一部のホスト アプリケーションでは、デバッグ用に入れ子になったプロンプトが開きます。 入れ子になったプロンプトは、コマンド プロンプトに表示される繰り返し文字 (ASCII 62) によって検出できます。
プロンプトのカスタマイズの詳細については、「 about_Prompts」を参照してください。
自動変数を使用すると、入れ子レベルを $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-Variable
コマンドレットの Scope パラメーターをGet-Alias
使用します。
たとえば、次のコマンドは、ローカル (スクリプト) スコープ内の変数を取得します。
Get-Variable -scope 0
これは、スクリプトで定義した変数と、デバッグ中に定義した変数のみを表示する便利な方法です。
コマンド ラインでのデバッグ
変数ブレークポイントまたはコマンド ブレークポイントを設定する場合は、スクリプト ファイル内でのみブレークポイントを設定できます。 ただし、既定では、ブレークポイントは現在のセッションで実行されるすべてのものに設定されます。
たとえば、変数に $name
ブレークポイントを設定すると、ブレークポイントを無効または削除するまで、実行したスクリプト、コマンド、関数、スクリプト コマンドレット、または式内の任意の変数でデバッガーが中断 $name
されます。
これにより、セッションおよびユーザーのプロファイル内の関数、変数、その他のスクリプトの影響を受ける可能性がある、より現実的なコンテキストでスクリプトをデバッグできます。
行ブレークポイントはスクリプト ファイルに固有であるため、スクリプト ファイルでのみ設定されます。
デバッグ関数
、、および end
の各セクションを持つbegin
process
関数にブレークポイントを設定すると、デバッガーは各セクションの最初の行で中断します。
例:
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>
リモート スクリプトのデバッグ
を実行 Enter-PSSession
して、リモート コンピューターでブレークポイントを設定したり、スクリプト ファイルやコマンドをデバッグしたりできる対話型のリモート PowerShell セッションを開始できます。 Enter-PSSession
では、リモート コンピューターでスクリプトまたはコマンドを実行している切断されたセッションを再接続できます。 実行中のスクリプトがブレークポイントにヒットすると、クライアント セッションによってデバッガーが自動的に開始されます。 スクリプトを実行している切断されたセッションが既にブレークポイントに達している場合は、 Enter-PSSession
セッションに再接続すると、コマンド ライン デバッガーが自動的に起動します。
次の例は、このしくみを示しています。 ブレークポイントは、スクリプトの 6 行目、11 行目、22 行目、25 行目に設定されています。 デバッガーが起動すると、プロンプトに対して次の 2 つの変更が識別されます。
- セッションが実行されているコンピューターの名前
- デバッグ モードであることを知らせる 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>
例
このテスト スクリプトは、PowerShell のバージョンを検出し、バージョンに適したメッセージを表示します。 これには、関数、関数呼び出し、変数が含まれます。
次のコマンドは、テスト スクリプト ファイルの内容を表示します。
PS C:\PS-test> Get-Content test.ps1
function psversion {
"PowerShell " + $PSVersionTable.PSVersion
if ($PSVersionTable.PSVersion.Major -lt 7) {
"Upgrade to PowerShell 7!"
}
else {
"Have you run a background job today (start-job)?"
}
}
$scriptName = $MyInvocation.PSCommandPath
psversion
"Done $scriptName."
開始するには、行、コマンド、変数、関数など、スクリプトの目的のポイントにブレークポイントを設定します。
まず、現在のディレクトリ内の Test.ps1 スクリプトの最初の行に行ブレークポイントを作成します。
PS C:\ps-test> Set-PSBreakpoint -line 1 -script 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 コマンドを使用して、スクリプトの最初のステートメントを実行し、次のステートメントをプレビューします。 次のステートメントでは、自動変数を $MyInvocation
使用して、変数の値を $scriptName
スクリプト ファイルのパスとファイル名に設定します。
DBG> s
test.ps1:11 $scriptName = $MyInvocation.PSCommandPath
この時点では、変数は $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」と入力します。
DBG> s
test.ps1:2 "PowerShell " + $PSVersionTable.PSVersion
デバッグ メッセージには、 関数の ステートメントのプレビューが含まれています。 このステートメントを実行し、関数の次のステートメントをプレビューするには、 コマンドを Step
使用できます。 ただし、この場合は StepOut コマンド (o) を使用します。 関数の実行が完了し (ブレークポイントに達しない限り)、スクリプト内の次のステートメントにステップ実行されます。
DBG> o
Windows PowerShell 2.0
Have you run a background job today (start-job)?
test.ps1:13 "Done $scriptName"
スクリプトの最後のステートメントを使用しているため、Step、StepOut、および Continue コマンドの効果は同じです。 この場合は、StepOut (o) を使用します。
Done C:\ps-test\test.ps1
PS C:\ps-test>
StepOut コマンドは、最後のコマンドを実行します。 標準のコマンド プロンプトは、デバッガーが終了し、コマンド プロセッサに制御を返したことを示します。
次に、デバッガーをもう一度実行します。 最初に、現在のブレークポイントを削除するには、 コマンドレットと Remove-PsBreakpoint
コマンドレットをGet-PsBreakpoint
使用します。 (ブレークポイントを再利用する可能性があると思われる場合は、 ではなく コマンドレットRemove-PsBreakpoint
をDisable-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.PSCommandPath
DBG>
変数の現在の値 ( $scriptName
) $null
を表示します。
DBG> $scriptName
DBG>
コマンド (s
) をStep
使用して、変数を設定する ステートメントを実行します。 次に、変数の新しい値を $scriptName
表示します。
DBG> $scriptName
C:\ps-test\test.ps1
Step コマンドを使用して、スクリプト内の次のステートメントをプレビューします。
DBG> s
test.ps1:12 psversion
次のステートメントは、 関数の呼び出しです psversion
。 関数をスキップしても実行するには、コマンド (v
) を使用StepOver
します。 を使用 StepOver
するときに関数に既に存在する場合は、有効ではありません。 関数呼び出しは表示されますが、実行されません。
DBG> v
Windows PowerShell 2.0
Have you run a background job today (start-job)?
test.ps1:13 "Done $scriptName"
コマンドは StepOver
関数を実行し、スクリプト内の次のステートメントをプレビューして、最後の行を出力します。
コマンド (t
) をStop
使用してデバッガーを終了します。 コマンド プロンプトは、標準のコマンド プロンプトに戻ります。
C:\ps-test>
ブレークポイントを削除するには、 コマンドレットと Remove-PsBreakpoint
コマンドレットをGet-PsBreakpoint
使用します。
PS C:\ps-test> Get-PSBreakpoint| Remove-PSBreakpoint
関数に新しいコマンド ブレークポイントをpsversion
Createします。
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>
スクリプトは、関数呼び出しでブレークポイントに到達します。 この時点で、 関数はまだ呼び出されていません。 これにより、 の Action パラメーター Set-PSBreakpoint
を使用してブレークポイントの実行条件を設定したり、ログの開始や診断スクリプトやセキュリティ スクリプトの呼び出しなどの準備タスクや診断タスクを実行したりできます。
アクションを設定するには、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
キーワード (keyword)はアクションで使用されないため、実行は停止しません。 バックティック (`
) は行連結文字です。
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
アクションのキーワード (keyword)は、ブレークポイントを実行するようにデバッガーに指示します。 また、キーワード (keyword)をcontinue
使用して、中断することなくデバッガーを実行するように指示することもできます。 既定のキーワード (keyword)は であるため、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
コマンドレットまたはデバッガー コマンド (k
) をGet-PsCallStack
使用します。 次のコマンドは、現在の呼び出し履歴を取得します。
DBG> k
2: prompt
1: .\test.ps1: $args=[]
0: prompt: $args=[]
この例では、PowerShell デバッガーを使用する多くの方法のほんの一部を示します。
PowerShell のその他のデバッグ機能
PowerShell デバッガーに加えて、PowerShell には、スクリプトと関数のデバッグに使用できる他のいくつかの機能が含まれています。
コマンドレットは
Set-PSDebug
、ステップ実行やトレースなど、非常に基本的なスクリプト デバッグ機能を提供します。コマンドレットを
Set-StrictMode
使用して、初期化されていない変数への参照、オブジェクトの存在しないプロパティへの参照、および無効な関数構文への参照を検出します。変数の値を表示するステートメント、コマンド ラインから入力を読み取るステートメント、現在の命令を報告するステートメントなど、診断ステートメントをスクリプトに追加します。 、、、 など
Write-Host
Write-Debug
Write-Warning
、このタスクの Write 動詞を含むコマンドレットをWrite-Verbose
使用します。