about_Debuggers

  • [アーティクル]

簡単な説明

PowerShell デバッガーについて説明します。

長い説明

デバッグとは、スクリプトの実行中にスクリプトを調べて、スクリプト命令のエラーを特定して修正するプロセスです。 PowerShell デバッガーは、スクリプト、関数、コマンド、PowerShell Desired State Configuration (DSC) 構成、または式のエラーと非効率性を調べて特定するのに役立ちます。

PowerShell 5.0 以降では、PowerShell デバッガーが更新され、リモート コンピューター上のコンソールまたは Windows PowerShell ISE で実行されているスクリプト、関数、コマンド、構成、または式がデバッグされました。 リモート コンピューターでブレークポイントを設定し、スクリプト ファイルとコマンドをデバッグできる対話型のリモート PowerShell セッションを開始するために実行 Enter-PSSession できます。 Enter-PSSession 機能が更新され、リモート コンピューターでスクリプトまたはコマンドを実行している切断されたセッションに再接続して入力できます。 実行中のスクリプトがブレークポイントに達すると、クライアント セッションによってデバッガーが自動的に開始されます。 スクリプトを実行している切断されたセッションが既にブレークポイントに達し、ブレークポイントで停止している場合は、 Enter-PSSession セッションに再接続した後、コマンド ライン デバッガーを自動的に開始します。

PowerShell デバッガーの機能を使用して、実行中に PowerShell スクリプト、関数、コマンド、または式を調べることができます。 PowerShell デバッガーには、ブレークポイントの設定、ブレークポイントの管理、呼び出し履歴の表示を可能にする一連のコマンドレットが含まれています。

デバッガー コマンドレット

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: スクリプトの 16 行を、指定した <m>行番号で始まる表示します。

  • l <m> <n>, List: スクリプトの行を、指定した<m>行番号で始まる行を表示<n>します。

  • q、StopExit: スクリプトの実行を停止し、デバッガーを終了します。 コマンドレットを実行 Debug-Job してジョブをデバッグする場合、コマンドは Exit デバッガーをデタッチし、ジョブの実行を続行できるようにします。

  • k、 Get-PsCallStack: 現在の呼び出し履歴を表示します。

  • <Enter>: 最後のコマンドがステップ (s)、StepOver (v)、または List (l) の場合は、最後のコマンドを繰り返します。 それ以外の場合は、送信アクションを表します。

  • ?、 h: デバッガー コマンドのヘルプを表示します。

デバッガーを終了するには、Stop (q) を使用します。

PowerShell 5.0 以降では、Exit コマンドを実行して、または実行してDebug-JobDebug-Runspace開始した入れ子になったデバッグ セッションを終了できます。

これらのデバッガー コマンドを使用すると、スクリプトを実行し、問題が発生した時点で停止し、変数の値とシステムの状態を調べ、問題が特定されるまでスクリプトの実行を続行できます。

注: ">" などのリダイレクト演算子を使用してステートメントにステップインすると、PowerShell デバッガーはスクリプト内の残りのすべてのステートメントをステップ実行します。

スクリプト変数の値の表示

デバッガーにいる間は、コマンドを入力したり、変数の値を表示したり、コマンドレットを使用したり、コマンド ラインでスクリプトを実行したりすることもできます。

次の自動変数を除き、デバッグ中のスクリプト内のすべての変数の現在の値を表示できます。

$_
$Args
$Input
$MyInvocation
$PSBoundParameters

これらの変数のいずれかの値を表示しようとする場合は、スクリプト内の変数の値ではなく、デバッガーが使う内部パイプラインでその変数の値を取得します。

デバッグ中のスクリプトのこれらの変数の値を表示するには、スクリプトで自動変数の値を新しい変数に割り当てます。 その後、新しい変数の値を表示できます。

たとえば、次のように入力します。

$scriptArgs = $Args
$scriptArgs

このトピックの例では、変数の $MyInvocation 値を次のように再割り当てします。

$scriptname = $MyInvocation.PSCommandPath

デバッガー環境

ブレークポイントに到達すると、デバッガー環境に入ります。 コマンド プロンプトが変更され、"[DBG]:" で始まります。

プロンプトのカスタマイズの詳細については、「 about_Prompts」を参照してください。

また、PowerShell コンソールなどの一部のホスト アプリケーションでは (ただし、統合スクリプト環境 [ISE]Windows PowerShellではない) には、デバッグ用の入れ子になったプロンプトが開きます。 入れ子になったプロンプトは、コマンド プロンプトに表示される繰り返し文字 (ASCII 62) によって検出できます。

たとえば、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-Variableコマンドレットの Scope パラメーターをGet-Alias使用します。

たとえば、次のコマンドは、ローカル (スクリプト) スコープ内の変数を取得します。

Get-Variable -scope 0

コマンドは次のように省略できます。

gv -s 0

これは、スクリプトで定義した変数とデバッグ中に定義した変数のみを表示する便利な方法です。

コマンド ラインでのデバッグ

変数ブレークポイントまたはコマンド ブレークポイントを設定する場合は、スクリプト ファイル内でのみブレークポイントを設定できます。 ただし、既定では、ブレークポイントは現在のセッションで実行されるものに設定されます。

たとえば、変数に $name ブレークポイントを設定すると、ブレークポイントを無効にするか削除するまで、実行する任意のスクリプト、コマンド、関数、スクリプト コマンドレット、または式内の任意の変数でデバッガーが中断 $name されます。

これにより、セッション内の関数、変数、およびその他のスクリプトやユーザーのプロファイルの影響を受ける可能性がある、より現実的なコンテキストでスクリプトをデバッグできます。

行ブレークポイントはスクリプト ファイルに固有であるため、スクリプト ファイルでのみ設定されます。

デバッグ関数

およびセクションがある関数にブレークポイントを設定すると、デバッガーはBeginProcessEnd各セクションの最初の行で中断します。

次に例を示します。

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>

リモート スクリプトのデバッグ

PowerShell 5.0 以降では、コンソールまたは ISE Windows PowerShellのリモート セッションで PowerShell デバッガーを実行できます。 Enter-PSSession 機能が更新され、リモート コンピューターで実行され、現在スクリプトが実行されている切断されたセッションに再接続して入力できます。 実行中のスクリプトがブレークポイントに達すると、クライアント セッションによってデバッガーが自動的に開始されます。

次の例は、6 行目、11 行目、22 行目、25 行目にスクリプトにブレークポイントを設定した場合の動作を示しています。 この例では、デバッガーの起動時に、セッションが実行されているコンピューターの名前と、デバッグ モードであることを知らせる DBG プロンプトという 2 つの識別プロンプトがあることに注意してください。

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>

例

このテスト スクリプトは、オペレーティング システムのバージョンを検出し、システムに適したメッセージを表示します。 これには、関数、関数呼び出し、変数が含まれます。

次のコマンドは、テスト スクリプト ファイルの内容を表示します。

PS C:\PS-test>  Get-Content test.ps1

function psversion {
  "PowerShell " + $PSVersionTable.PSVersion
  if ($PSVersionTable.PSVersion.Major -lt 6) {
    "Upgrade to PowerShell 6.0!"
  }
  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

このコマンドは、省略形

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 コマンドを使用して、スクリプトの最初のステートメントを実行し、次のステートメントをプレビューします。 次のステートメントでは、自動変数を $MyInvocation 使用して、変数の値を $scriptName スクリプト ファイルのパスとファイル名に設定します。

DBG> s
test.ps1:11  $scriptName = $MyInvocation.PSCommandPath

この時点では、 $scriptName 変数は設定されませんが、変数の値を表示することで確認できます。 この場合、値は $null です。

DBG> $scriptname
# DBG>

別の Step コマンドを使用して、現在のステートメントを実行し、スクリプト内の次のステートメントをプレビューします。 次のステートメントは 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>

変数$nullの現在の値を$scriptName表示します。

DBG> $scriptName
# DBG>

Step コマンドを使用して、変数を設定するステートメントを実行します。 次に、変数の新しい値を $scriptName 表示します。

DBG> $scriptName
C:\ps-test\test.ps1
```powershell

Use a Step command (s) to preview the next statement in the script.

```powershell
DBG> s
test.ps1:12  psversion

次のステートメントは、PsVersion 関数の呼び出しです。 関数をスキップしても実行するには、StepOver コマンド (v) を使用します。 StepOver を使用するときに関数に既に存在する場合は、有効ではありません。 関数呼び出しは表示されますが、実行されません。

DBG> v
Windows PowerShell 2.0
Have you run a background job today (start-job)?
test.ps1:13  "Done $scriptName"

StepOver コマンドによって関数が実行され、スクリプト内の次のステートメントがプレビューされ、最後の行が出力されます。

Stop コマンド (t) を使用してデバッガーを終了します。 コマンド プロンプトが標準のコマンド プロンプトに戻ります。

C:\ps-test>

ブレークポイントを削除するには、コマンドレットとRemove-PsBreakpointコマンドレットをGet-PsBreakpoint使用します。

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>

スクリプトは関数呼び出しでブレークポイントに到達します。 この時点で、関数はまだ呼び出されていません。 これにより、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 キーワードはアクションで使用されないため、実行は停止しません。 (backtick (`) は行連結文字です。

PS C:\ps-test> Set-PSBreakpoint -command psversion -script test.ps1  `
-action { add-content "The value of `$scriptName is $scriptName." `
-path action.log}

ブレークポイントの条件を設定するアクションを追加することもできます。 次のコマンドでは、実行ポリシーが RemoteSigned (スクリプトの実行を引き続き許可する最も制限の厳しいポリシー) に設定されている場合にのみ、コマンド ブレークポイントが実行されます。 (backtick (`) は継続文字です。

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コマンドレットまたはGet-PsCallStackデバッガー コマンド (k) を使用します。 次のコマンドは、現在の呼び出し履歴を取得します。

DBG> k
2: prompt
1: .\test.ps1: $args=[]
0: prompt: $args=[]

この例では、PowerShell デバッガーを使用する多くの方法のほんの一部を示します。

デバッガー コマンドレットの詳細については、次のコマンドを入力します。

help <cmdlet-name> -full

たとえば、次のように入力します。

help Set-PSBreakpoint -full

PowerShell のその他のデバッグ機能

PowerShell デバッガーに加えて、PowerShell には、スクリプトと関数のデバッグに使用できる他のいくつかの機能が含まれています。

  • ISE Windows PowerShellには、対話型のグラフィカル デバッガーが含まれています。 詳細については、ISE Windows PowerShell開始し、F1 キーを押します。

  • このコマンドレットには Set-PSDebug 、ステップ実行やトレースなど、非常に基本的なスクリプト デバッグ機能が用意されています。

  • このコマンドレットを Set-StrictMode 使用して、初期化されていない変数への参照、オブジェクトの存在しないプロパティへの参照、および無効な関数構文への参照を検出します。

  • 変数の値を表示するステートメント、コマンド ラインから入力を読み取るステートメント、現在の命令を報告するステートメントなど、診断ステートメントをスクリプトに追加します。 このタスクの書き込み動詞を含むコマンドレットを使用します (例: Write-Host, Write-Debug, Write-Warning, .Write-Verbose

こちらもご覧ください