PowerShell Error Handling with Functions

Question

This is a best practice question I suppose.

When designing functions that will be used within scripts, what is the best way to handle errors that could occur within the function?

For example, say we have a basic function that does X and Y:

Function Test-Function
{
    Try
    {
        <# Something in here that would generate an error #>
    }
    Catch
    {
        Throw
    }

    Return $someReturnResultIWantInMyScript
}

My script calls this function:

Try
{
    $ValueIWantFromFunction = Test-Function
}
Catch
{
    <# Do something here #>
}

If the Test-Function hits a terminating error, it will throw to the caller. The Try/Catch around my function call in the script will receive this error and hit its own catch. I can then decide what to do.

If I didn't throw an error within the function, the script wouldn't see the terminating error, and then my $ValueIWantFromFunction could contain $Null or something not useful.

Is this a good way of error handling with functions and function calls within scripts? Is there a better way?

Answer 1

As a best practice, I like to use exceptions to handle errors in my functions/scripts and document them so the caller knows what went wrong. For example:

Function Remove-File
{
    [CmdletBinding()]
    [OutputType([Int])]
    Param(
        [Parameter(Mandatory)]
        [String]$Path
    )

    Try
    {
        Remove-Item -Path $Path
        Return 0
    }
    Catch
    {
        Return 1
    }
}

If I'm designing my own function/cmdlet, I'll generate a custom [ErrorRecord] object to be thrown:

#Requires -Version 5
If ($ErrorCondition)
{
    $PSCmdlet.ThrowTerminatingError(
        [System.Management.Automation.ErrorRecord]::new(
            [System.Exception]::new('Error message'),
            'FullyQualifiedName',
            [System.Management.Automation.ErrorCategory]::DeviceError,
            $ErrorCausingObject
        )
    )
}

Using this method, I can include in the documentation which errors get thrown depending on what went wrong so the caller can utilize multiple catches depending on the thrown error and handle it.

Here are some nice articles:
Everything about exceptions
Scripting Guy: Handling errors
On the OutputType attribute