PowerShellエラーハンドリングマスター: ノンセンスガイド

チュートリアル
PowerShell

PowerShellスクリプトに煩わしい赤いエラーメッセージが表示されるのに疲れていませんか？それらは intimidating に見えるかもしれませんが、適切なエラーハンドリングは信頼性の高いPowerShell自動化を構築するために不可欠です。このチュートリアルでは、エラータイプの理解からtry/catchブロックの習得まで、スクリプト内で堅牢なエラーハンドリングを実装する方法を学びます。

前提条件

このチュートリアルでは、次のことを前提としています：

  • Windows PowerShell 5.1またはPowerShell 7+がインストールされていること
  • PowerShellスクリプティングに関する基本的な知識があること
  • エラーを学びの機会として受け入れる意欲があること！

PowerShellエラータイプの理解

エラー処理に飛び込む前に、PowerShellが投げる2つの主要なエラータイプを理解する必要があります：

終端エラー

これは深刻なもので、スクリプトの実行を完全に停止させるエラーです。次のような場合に終端エラーに遭遇します：

  • スクリプトに構文エラーがあり、解析できない場合
  • 未処理の例外が.NETメソッド呼び出しで発生する場合
  • 明示的にErrorAction Stopを指定した場合
  • 重大なランタイムエラーが発生し、続行不可能になる場合

非終端エラー

これらはスクリプトを停止しない、より一般的な運用エラーです：

  • ファイルが見つからないエラー
  • アクセス拒否のシナリオ
  • ネットワーク接続の問題
  • 無効なパラメータ値

エラーアクションパラメータ：あなたの最初の防御線

実際の例から始めましょう。ある日数より古いファイルを削除しようとするスクリプトが以下にあります。

param (
    [Parameter(Mandatory)]
    [string]$FolderPath,

    [Parameter(Mandatory)]
    [int]$DaysOld
)

$Now = Get-Date
$LastWrite = $Now.AddDays(-$DaysOld)
$oldFiles = (Get-ChildItem -Path $FolderPath -File -Recurse).Where{$_.LastWriteTime -le $LastWrite}

foreach ($file in $oldFiles) {
    Remove-Item -Path $file.FullName
    Write-Verbose -Message "Successfully removed [$($file.FullName)]."
}

デフォルトでは、Remove-Item は終了しないエラーを生成します。捕捉できるように終了するエラーを生成するには、-ErrorAction Stop を追加してください：

Remove-Item -Path $file.FullName -ErrorAction Stop

Try/Catch Blocks: エラーハンドリングのスイスアーミーナイフ

さて、ファイルの削除を try/catch ブロックでラップしましょう：

foreach ($file in $oldFiles) {
    try {
        Remove-Item -Path $file.FullName -ErrorAction Stop
        Write-Verbose -Message "Successfully removed [$($file.FullName)]."
    }
    catch {
        Write-Warning "Failed to remove file: $($file.FullName)"
        Write-Warning "Error: $($_.Exception.Message)"
    }
}

try ブロックにはエラーを生成する可能性のあるコードが含まれています。エラーが発生すると、(終了エラーであれば)実行は catch ブロックに移動し、以下のような処置ができます：

  • エラーをログに記録する
  • 正しい処置を取る
  • 管理者に通知する
  • スクリプトの実行をスムーズに続行する

$Error: を使用した作業: エラー調査ツール

PowerShell は、自動変数 $Error にエラーオブジェクトの配列を保持しています。 $Error を PowerShell の「ブラックボックスレコーダー」と考えてください – PowerShell セッション中に発生したすべてのエラーを追跡し、トラブルシューティングやデバッグに非常に便利です。

次に、いつ、なぜ $Error を使用するかを見てみましょう：

  1. 過去のエラーのトラブルシューティング: 赤いエラーメッセージを見逃した場合でも、$Error は履歴を維持します：

    # 最近のエラーの詳細を表示
$Error[0] | Format-List * -Force

# 最後の 5 つのエラーを表示
$Error[0..4] | Select-Object CategoryInfo, Exception

# 特定の種類のエラーを検索
$Error | Where-Object { $_.Exception -is [System.UnauthorizedAccessException] }

  2. スクリプトのデバッグ: 問題がどこで発生したのかを理解するために$Errorを使用します:

    # エラーが発生した正確な行番号とスクリプトを取得
$Error[0].InvocationInfo | Select-Object ScriptName, ScriptLineNumber, Line

# 完全なエラーコールスタックを見る
$Error[0].Exception.StackTrace

  3. エラー回復と報告: 詳細なエラーレポートを作成するのに最適です:

    # エラーレポートを作成
function Write-ErrorReport {
    param($ErrorRecord = $Error[0])
    [PSCustomObject]@{
    TimeStamp = Get-Date
    ErrorMessage = $ErrorRecord.Exception.Message
    ErrorType = $ErrorRecord.Exception.GetType().Name
    Command = $ErrorRecord.InvocationInfo.MyCommand
    ScriptLine = $ErrorRecord.InvocationInfo.Line
    ErrorLineNumber = $ErrorRecord.InvocationInfo.ScriptLineNumber
    StackTrace = $ErrorRecord.ScriptStackTrace
}

    

    }

  4. セッション管理: エラーをクリーンアップするか、エラーの状態を確認します:

    # エラー履歴をクリア（スクリプトの開始時に便利）
$Error.Clear()

# 総エラー数をカウント（エラー閾値チェックに便利）
if ($Error.Count -gt 10) {
    Write-Warning "高エラー数が検出されました: $($Error.Count) エラー"
}

これらの概念を組み合わせた実例:

function Test-DatabaseConnections {
    $Error.Clear()  # Start fresh

    try {
        # Attempt database operations...
    }
    catch {
        # If something fails, analyze recent errors
        $dbErrors = $Error | Where-Object {
            $_.Exception.Message -like "*SQL*" -or
            $_.Exception.Message -like "*connection*"
        }

        if ($dbErrors) {
            Write-ErrorReport $dbErrors[0] |
                Export-Csv -Path "C:\\Logs\\DatabaseErrors.csv" -Append
        }
    }
}

プロのヒント:

  • $ErrorはPowerShellセッションごとに維持されます
  • デフォルトの容量は256エラー（$MaximumErrorCountで制御）です
  • これは固定サイズの配列で、満杯になると新しいエラーが古いエラーを押し出します
  • 最初に必ず$Error[0]を確認してください – それが最も最近のエラーです
  • 重要なスクリプトの開始時に$Errorをクリアすることを検討してください、エラー追跡をクリーンに保つために

複数のキャッチブロック: 目的別エラー処理

すべてのホーム修理作業に同じツールを使用しないように、すべてのPowerShellエラーを同じ方法で処理すべきではありません。複数のキャッチブロックを使用することで、異なる種類のエラーに異なる反応をすることができます。

これがその仕組みです:

try {
    Remove-Item -Path $file.FullName -ErrorAction Stop
}
catch [System.UnauthorizedAccessException] {
    # This catches permission-related errors
    Write-Warning "Access denied to file: $($file.FullName)"
    Request-ElevatedPermissions -Path $file.FullName  # Custom function
}
catch [System.IO.IOException] {
    # This catches file-in-use errors
    Write-Warning "File in use: $($file.FullName)"
    Add-ToRetryQueue -Path $file.FullName  # Custom function
}
catch [System.Management.Automation.ItemNotFoundException] {
    # This catches file-not-found errors
    Write-Warning "File not found: $($file.FullName)"
    Update-FileInventory -RemovePath $file.FullName  # Custom function
}
catch {
    # This catches any other errors
    Write-Warning "Unexpected error: $_"
    Write-EventLog -LogName Application -Source "MyScript" -EntryType Error -EventId 1001 -Message $_
}

遭遇する一般的なエラータイプ:

  • [System.UnauthorizedAccessException] – アクセスが拒否されました
  • [System.IO.IOException] – ファイルがロックされています/使用中
  • [System.Management.Automation.ItemNotFoundException] – ファイル/パスが見つかりません
  • [System.ArgumentException] – 無効な引数
  • [System.Net.WebException] – ネットワーク/ウェブの問題

これを実践した実際の例があります:

function Remove-StaleFiles {
    [CmdletBinding()]
    param(
        [string]$Path,
        [int]$RetryCount = 3,
        [int]$RetryDelaySeconds = 30
    )

    $retryQueue = @()

    foreach ($file in (Get-ChildItem -Path $Path -File)) {
        $attempt = 0
        do {
            $attempt++
            try {
                Remove-Item -Path $file.FullName -ErrorAction Stop
                Write-Verbose "Successfully removed $($file.FullName)"
                break  # Exit the retry loop on success
            }
            catch [System.UnauthorizedAccessException] {
                if ($attempt -eq $RetryCount) {
                    # Log to event log and notify admin
                    $message = "Permission denied after $RetryCount attempts: $($file.FullName)"
                    Write-EventLog -LogName Application -Source "FileCleanup" -EntryType Error -EventId 1001 -Message $message
                    Send-AdminNotification -Message $message  # Custom function
                }
                else {
                    # Request elevated permissions and retry
                    Request-ElevatedAccess -Path $file.FullName  # Custom function
                    Start-Sleep -Seconds $RetryDelaySeconds
                }
            }
            catch [System.IO.IOException] {
                if ($attempt -eq $RetryCount) {
                    # Add to retry queue for later
                    $retryQueue += $file.FullName
                    Write-Warning "File locked, added to retry queue: $($file.FullName)"
                }
                else {
                    # Wait and retry
                    Write-Verbose "File in use, attempt $attempt of $RetryCount"
                    Start-Sleep -Seconds $RetryDelaySeconds
                }
            }
            catch {
                # Unexpected error - log and move on
                $message = "Unexpected error with $($file.FullName): $_"
                Write-EventLog -LogName Application -Source "FileCleanup" -EntryType Error -EventId 1002 -Message $message
                break  # Exit retry loop for unexpected errors
            }
        } while ($attempt -lt $RetryCount)
    }

    # Return retry queue for further processing
    if ($retryQueue) {
        return $retryQueue
    }
}

複数のキャッチブロックに関するプロのヒント:

  1. 順序が重要です – より具体的な例外を最初に配置してください
  2. カスタム関数を使用して各エラータイプを一貫して処理します
  3. 一時的なエラーに対してリトライロジックを考慮します
  4. 異なるエラータイプを異なる場所にログします
  5. 可能な限り具体的な例外タイプを使用します
  6. 各エラータイプを意図的に発生させて各キャッチブロックをテストします

ファイナリーブロックを使用する：自分自身を片付ける

ファイナリーブロックはあなたのクリーンクルーです – エラーがあってもなくても常に実行されます。これにより、次のことに最適です：

  • ファイルハンドルを閉じる
  • データベースから切断する
  • システムリソースを解放する
  • 元の設定を復元する

以下は実用的な例です：

try {
    $stream = [System.IO.File]::OpenRead($file.FullName)
    # Process file contents here...
}
catch {
    Write-Warning "Error processing file: $_"
}
finally {
    # This runs even if an error occurred
    if ($stream) {
        $stream.Dispose()
        Write-Verbose "File handle released"
    }
}

ファイナリーを責任感のあるキャンパーのルールのように考えてください：「旅行中に何が起こっても、出発する前に必ずキャンプサイトを片付ける。」

エラーハンドリングのベストプラクティス

  1. エラーアクションを具体的にする
    一律のErrorAction Stopではなく、エラーをキャッチする必要があるコマンドに選択的に使用します。

  2. エラー変数を使用する

    Remove-Item $path -ErrorVariable removeError
if ($removeError) {
    Write-Warning "アイテムの削除に失敗しました: $($removeError[0].Exception.Message)"
}

  3. エラーを適切にログに記録する

    • 回復可能なエラーには Write-Warning を使用する
    • 重大な問題には Write-Error を使用する
    • 重大な障害については Windows イベントログに書き込むことを検討する

  4. リソースのクリーンアップ
    常に finally ブロックを使用して、ファイルハンドルやネットワーク接続などのリソースをクリーンアップする。

  5. エラー処理のテスト
    エラーを故意に引き起こして、エラー処理が期待通りに機能することを確認する。

すべてをまとめる

これらのベストプラクティスを取り入れた完全な例は次のとおりです：

function Remove-OldFiles {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string]$FolderPath,

        [Parameter(Mandatory)]
        [int]$DaysOld,

        [string]$LogPath = "C:\\Logs\\file-cleanup.log"
    )

    try {
        # Validate input
        if (-not (Test-Path -Path $FolderPath)) {
            throw "Folder path '$FolderPath' does not exist"
        }

        $Now = Get-Date
        $LastWrite = $Now.AddDays(-$DaysOld)

        # Find old files
        $oldFiles = Get-ChildItem -Path $FolderPath -File -Recurse |
                    Where-Object {$_.LastWriteTime -le $LastWrite}

        foreach ($file in $oldFiles) {
            try {
                Remove-Item -Path $file.FullName -ErrorAction Stop
                Write-Verbose -Message "Successfully removed [$($file.FullName)]"

                # Log success
                "$(Get-Date) - Removed file: $($file.FullName)" |
                    Add-Content -Path $LogPath
            }
            catch [System.UnauthorizedAccessException] {
                Write-Warning "Access denied to file: $($file.FullName)"
                "$ErrorActionPreference - Access denied: $($file.FullName)" |
                    Add-Content -Path $LogPath
            }
            catch [System.IO.IOException] {
                Write-Warning "File in use: $($file.FullName)"
                "$(Get-Date) - File in use: $($file.FullName)" |
                    Add-Content -Path $LogPath
            }
            catch {
                Write-Warning "Unexpected error removing file: $_"
                "$(Get-Date) - Error: $_ - File: $($file.FullName)" |
                    Add-Content -Path $LogPath
            }
        }
    }
    catch {
        Write-Error "Critical error in Remove-OldFiles: $_"
        "$(Get-Date) - Critical Error: $_" |
            Add-Content -Path $LogPath
        throw  # Re-throw error to calling script
    }
}

この実装は：

  • 入力パラメータを検証する
  • 一般的なエラーに対して特定の catch ブロックを使用する
  • 成功と失敗の両方をログに記録する
  • トラブルシューティングのために詳細な出力を提供する
  • 重大なエラーを呼び出し元のスクリプトに再スローする

結論

適切なエラー処理は信頼性のあるPowerShellスクリプトにとって重要です。エラーの種類を理解し、try/catchブロックを効果的に使用することで、失敗を上手に処理し、意味のあるフィードバックを提供するスクリプトを作成することができます。エラー処理を徹底的にテストすることを忘れずに – 本番環境で問題をトラブルシューティングする際に、将来の自分が感謝するでしょう！

さあ、エラーをキャッチしに行きましょう！ただ覚えておいてください – 対処されていないエラーこそが唯一の悪いエラーです。

Source:
https://adamtheautomator.com/powershell-error-handling/