PowerShell スクリプトのデバッグ手法
.ユーザー作成のバッチファイルからPowerShellを利用する場合が多いと思います。
ここではデバッグ手法をまとめてみました。
以下は現場で役立つ実践的な手順とテクニック。まずは出力を確実に得て、問題を段階的に切り分けることが最短ルートです。
基本コマンドと挙動確認
- Write-Output / Write-Host / Write-Verbose / Write-Debug / Write-Error：目的別に出力を使い分ける。デバッグ時は Write-Verbose と Write-Debug を活用し、スクリプト実行時に -Verbose や -Debug を付けて詳細を確認する。
- -WhatIf / -Confirm：破壊的操作（Remove-Item, Stop-Service 等）を安全に検証する。
- $Error / $LASTEXITCODE / $PSCmdlet.WriteError：エラー情報や外部コマンドの終了コードを確認する。
実行制御とブレークポイント
- Set-PSBreakpoint / Get-PSBreakpoint / Remove-PSBreakpoint：関数・行・コマンドにブレークポイントを置いて停止させ、ローカル変数やスタックを調べる。
- Enter-PSHostProcess / Debug-Runspace（高度）: リモートセッションやプロセス内でのステップ実行に使う（必要時のみ）。
- Step-Into / Step-Over / Continue：PowerShell ISE や VS Code のデバッガーで逐次実行し、変数の変化を追う。
ロギングと詳細情報の出力
- Start-Transcript / Stop-Transcript：セッション全体の入出力をファイルに残す。
- Out-File / Tee-Object / >> リダイレクト：コマンド単位の出力をログに残す。Tee-Object は出力を画面表示しつつファイルに書き込める。
- 詳細な例：
Start-Transcript -Path .\debug.log -Append
Write-Verbose "処理開始" -Verbose
Get-Item "C:\path\to\file.txt" 2>&1 | Tee-Object -FilePath .\cmd.log
Stop-Transcript
変数とスコープの確認
- Get-Variable / $variable / Trace-Command：変数の中身や値の変化を確認する。関数内と外のスコープ差に注意する。
- 遅延評価の注意：文字列内での展開やスクリプトブロックの評価タイミングを意識する（"$(...)", { } の違い）。
- 例：
Write-Host "User: $env:USERNAME"
Get-Variable -Name MyVar -Scope 0..5
エラーハンドリングとテスト
- try / catch / finally：例外を捕捉して原因ログを出す。catch で $.Exception.Message や $ | Format-List * を出力すると詳細が分かる。
- -ErrorAction Stop / -ErrorVariable：コマンドのエラー振る舞いを制御して catch に流す。
- 例：
try {
Get-Content "C:\no\exist.txt" -ErrorAction Stop
} catch {
Write-Error "読み込み失敗: $($_.Exception.Message)"
$_ | Format-List * | Out-File .\error-dump.txt
}
開発環境と便利ツール
- Visual Studio Code + PowerShell 拡張：ブレークポイント、変数ウォッチ、呼び出しスタック、REPL（デバッグコンソール）を使える。
- PSScriptAnalyzer：静的解析でベストプラクティスや潜在的バグを指摘する。
- ISE / PowerShell Debugger：簡易的なデバッグには ISE や組み込みデバッガーも有効。
すぐ使えるチェックリスト
- -Verbose / -Debug を付けて再実行。
- Start-Transcript でセッションログを取得。
- 疑わしい箇所に Write-Verbose/Write-Debug を追加。
- try/catch で例外情報を拾いログ化。
- VS Code でブレークポイントを貼ってステップ実行。
