PowerShell Exception Handling: Capturing Complete Error Messages and Deep Analysis of WebException

Fundamentals of PowerShell Exception Handling

In PowerShell, errors and exceptions are structured objects. The error messages displayed in the console are actually formatted combinations of multiple error object elements. Understanding this structure is crucial for effective exception handling.

Error Object Structure Analysis

PowerShell error objects contain several key properties:

$formatstring = "{0} : {1}`n{2}`n" +
                "    + CategoryInfo          : {3}`n" +
                "    + FullyQualifiedErrorId : {4}`n"
$fields = $_.InvocationInfo.MyCommand.Name,
          $_.ErrorDetails.Message,
          $_.InvocationInfo.PositionMessage,
          $_.CategoryInfo.ToString(),
          $_.FullyQualifiedErrorId

$formatstring -f $fields

Basic Exception Capture Methods

The simplest way to catch exceptions is using try-catch blocks:

try {
    Invoke-WebRequest $sumoApiURL -Headers @{"Content-Type"= "application/json"} -Credential $cred -WebSession $webRequestSession -Method post -Body $sumojson -ErrorAction Stop
} catch {
    $_
}

Nested Exception Handling

Many exceptions contain inner exceptions that provide more detailed error information. You can traverse all nested exceptions using a loop:

$e = $_.Exception
$msg = $e.Message
while ($e.InnerException) {
    $e = $e.InnerException
    $msg += "`n" + $e.Message
}
$msg

WebException Special Handling

For WebException, the Response property contains detailed information about the server response:

$e.Exception.Response

This property provides key information such as StatusCode, StatusDescription, and Headers, which helps diagnose HTTP request issues.

Error Details Message Parsing

In web request scenarios, error messages may be returned in JSON format:

$_.ErrorDetails | Get-Member
$_.ErrorDetails | Format-List *

If ErrorDetails.Message is an object:

$_.ErrorDetails.Message.message

If it's a JSON string:

$_.ErrorDetails.Message | ConvertFrom-Json | Select-Object -Expand message

Specific Exception Type Handling

Use specific handling logic for different types of exceptions:

try {
    # Business logic
} catch [System.ArgumentException] {
    # Handle argument exceptions
} catch [System.Net.WebException] {
    # Handle web exceptions
    Write-Host "HTTP Status Code: " $_.Exception.Response.StatusCode
} catch {
    # Handle all other exceptions
}

Resource Cleanup and Finally Block

Cleanup operations that need to be executed regardless of whether an exception occurred should be placed in a finally block:

try {
    # Operations that may throw exceptions
} catch {
    # Exception handling
} finally {
    # Cleanup operations, such as closing connections and releasing resources
}

Formatted Error Output

Use Write-Host for colored error output:

try {
    # Business logic
} catch {
    Write-Host -Foreground Red -Background Black ($formatstring -f $fields)
}

Debugging Information Retrieval

Exception objects provide rich debugging information:

• $_.Exception.HResult - Error number
• $_.ScriptStackTrace - PowerShell script stack trace
• $_.Exception.StackTrace - .NET exception stack trace
• $_.InvocationInfo - Invocation context information

Practical Application Scenarios

In automated scripts, complete error capture is essential for generating detailed reports. The server hardening script case mentioned in the reference article demonstrates the practical need to store error information in strings and write to files. Similarly, in web request scenarios, complete error information helps quickly locate and resolve issues.

Best Practices Summary

1. Use -ErrorAction Stop to ensure exceptions can be caught by catch blocks

2. Fully utilize various properties of structured error objects

3. Use specialized catch blocks for specific exception types

4. Properly handle nested exceptions to obtain complete error chains

5. Ensure proper resource release in finally blocks

6. Choose appropriate error information display methods based on business requirements