PowerShell Step Deployments and Error Handling

Purpose

You receive an error when running a PowerShell script and want to understand how PowerShell returns errors, or you want to learn how the PowerShell step in PDQ Deploy executes scripts and handles errors.
 

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 the 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.

 

By default, a PowerShell step returns exit code 0 to PDQ Deploy even if the script hits an error, unless you add explicit error handling.

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 | Microsoft 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 writeErrorStream = $true. If any entries are found, PowerShell will return with exit code -37104.

Error Handling Example

Explicitly adding an exit code

The following example returns an exit code of 777 when an error or exception occurs:
 
Try {
  Get-ChildItem C:\NonExistentFolder -ErrorAction Stop
}
Catch {
  $_.Exception
  exit 777
}

You can use this code in either of the following ways:

  • Paste it directly into a PowerShell step.
  • Save it as a .ps1 script and call the script from a deployment step.

In both cases, PDQ Deploy receives the exit code returned by the PowerShell process. If an exception occurs, the step returns 777, which can then be handled using Success Codes in the deployment step. See PDQ Deploy - PowerShell Step Properties for more information.

PDQ Deploy PowerShell step showing exit 777 in a catch block and 777 added to the Success Codes field.

Native PowerShell cmdlet errors

Native PowerShell cmdlets (like Get-ChildItem or Remove-Item) don't generate exit codes on their own, so PDQ Deploy has no automatic way to detect when one of them fails. You need to add your own error handling, such as a try/catch block with an explicit exit code, so these errors get reported correctly.

Brigg Angus
Updated
Was this article helpful?

Related articles