PowerShell Step Deployments and Error Handling

Purpose:

You receive an error when running a PowerShell script, wish to know the method errors are returned when running a PowerShell script, or wish to understand the deployment method of the PowerShell step in PDQ Deploy, specifically how errors are handled.

Resolution:

When you deploy a package that contains a PowerShell step, PDQ Deploy bundles the contents of your PowerShell step and adds some basic error handling before sending it to a target. This bundle contains two files: user.ps1 and Error Handling Wrapper.ps1. These files are created automatically when deploying a package that contains PowerShell and allows PDQ Deploy to better report on errors that occur during PowerShell deployments.

The user.ps1 script contains the PowerShell code that is contained in a PowerShell step. The Error Handling Wrapper.ps1 script contains a call to run user.ps1 as well as basic error handling. This allows PDQ Deploy to properly display any errors that happen during a PowerShell deployment.

Without basic error handling, PowerShell will return a value of 0 to PDQ Deploy when a PowerShell step is run on a target. This is because PowerShell only determines whether or not the script was able to run rather than what errors or exceptions happen during a deployment.

If you explicitly add an exit code to your PowerShell step or if you call a PowerShell script that contains an exit code, it will be returned as $lastexitcode after user.ps1 is called.

Native PowerShell cmdlets do not normally generate exit codes. Instead, any errors or exceptions are recorded in PowerShell's global variable $error (see about Automatic Variables for more information). When deploying a PowerShell step, PDQ Deploy looks at the contents of $error for any entry that has a property and value of writeErrorSteam = $true. If any entries are found, targets with PowerShell 3 or higher will return with exit code -37104. PowerShell 2 targets will return with exit code 37105.

Error Handling Examples:

I. Explicitly adding an exit code:
In a PowerShell step, we used the following code:

Try {
Get-ChildItem C:\NonExistentFolder -ErrorAction Stop
}
Catch {
$_.Exception
exit 777
}

This will return a value of 777 if there is an error or exception that occurs

II. Adding exit codes to a script and then calling the script:
In a PowerShell script, we used the following code and saved it as MyScript.ps1:

Try {
Get-ChildItem C:\NonExistentFolder -ErrorAction Stop
}
Catch {
$_.Exception
exit 777
}

This will return a value of 777  if there is an error or exception that occurs when the script is called and the step is deployed to a target:

Native PowerShell cmdlet errors:

You will need to handle any exceptions within your PowerShell code to account for these errors.


See Also:

Admin Arsenal Live! : PDQ Deploy 9

About Automatic Variables (Microsoft))

An Introduction to Error Handling in PowerShell

Still have a question or want to share what you have learned? Visit our Community to get help and collaborate with others.