Powershell-Copilot-Standards errorsandlogs.instructions.md

PowerShell Error Handling and Logging Implementation

Implement robust error handling and structured logging patterns for PowerShell code that ensure proper error management, correlation tracking, and enterprise-grade diagnostic capabilities.

Worked examples: Basic-Function-Example.ps1 and Get-ExampleData.ps1 both generate a correlation ID once in begin, carry it through every message, use $_ in the catch, and continue so one failed item does not abort the batch. Both failure paths are covered by tests.

Error Handling Implementation

Comprehensive Error Handling Pattern

Generate error handling code following this enterprise pattern:

function Verb-Noun {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$InputParameter
    )

    # Initialize correlation tracking
    $correlationId = [System.Guid]::NewGuid()
    $ErrorActionPreference = 'Stop'

    try {
        Write-Verbose "Starting operation - CorrelationId: $correlationId"

        # Main operation logic here
        $result = Invoke-Operation -CorrelationId $correlationId

        Write-Verbose "Operation completed successfully - CorrelationId: $correlationId"
        return $result
    }
    catch {
        # Structured error logging
        $errorDetails = @{
            CorrelationId = $correlationId
            Function = $MyInvocation.MyCommand.Name
            ErrorMessage = $_.Exception.Message
            StackTrace = $_.ScriptStackTrace
            Timestamp = Get-Date
            InputParameters = $PSBoundParameters
        }

        Write-Error "Operation failed: $($_.Exception.Message) - CorrelationId: $correlationId"

        # Log to troubleshooting system
        $errorDetails | ConvertTo-Json | Out-File ".\Troubleshooting\Logs\error-$correlationId.json"

        throw
    }
    finally {
        # Resource cleanup
        if ($resource -and $resource -is [System.IDisposable]) {
            $resource.Dispose()
        }
    }
}