Getting Started - Error Handling
Welcome to my Getting Started with Windows PowerShell series!
In case you missed the earlier posts, you can check them out here:
We will be exploring:
Why Handle Errors?
Error handling may take some extra time to create, however, it can really save you time in the long run. Let's say you have a script that performs the following tasks:
Takes information from a database / file and stores it in $userAccounts
Uses a loop to perform processing on each $user in $userAccounts
Update a user's AD information if the user is in the list
Disable any accounts that are not in the list
The script runs, and seems to be working great for a few weeks. Then, all of a sudden, the database server goes down, and $userAccounts is empty. The script runs, doesn't see any users, and what likely happens next is all user accounts are deleted. While this example is a little extreme, it is something that can happen. There are also a lot of in-between cases that can make error handling worth it. It's a good mindset to have when you're writing scripts as you can write to incorporate it off the bat.
Errors in PowerShell
Errors in PowerShell are stored in the automatic variable $error. You can see how many errors you've encountered in your session by using:
$error.count
This is essentially an array of errors, to access the first value you can use:
$error[0]
Let's take a look at $error[0] more closely, via:
$error[0] | Get-Member
We can view information on the command that raised the error via:
$error[0].InvocationInfo
It looks like the line property contains the full command we used when the error was encountered.
$error[0].InvocationInfo.Line
The exception that raised the error can be accessed via:
$error[0].Exception
We can also get more information about the exception via:
$error[0].Exception | Get-Member
Here you can see the TypeName: [System.UnauthorizedAccessException], and the various methods and properties of the exception. The exception TypeName is used later when we catch specific errors.
Looks like to get the exception's message in string format we'd use:
$error[0].Exception.Message
Now that we've dug into the automatic variable $error, let's move on to the different types of errors we can encounter.
Terminating Errors
Terminating errors in PowerShell mean that the script can no longer continue to run with the information it has encountered, or has been given. If you do not have a way to catch the error, it will likely display the nasty red error text you've likely seen before. Terminating errors halt anything running in the pipeline. This terminates output, aside from the error message of the terminating error.
Here's an example of a terminating error that was caused by calling a command that does not exist:
Get-TerminatingError
Non-Terminating Errors
Non-terminating errors in PowerShell do not stop the pipeline from executing. These errors are handled internally by the Cmdlet, and are not able to be captured via error handling. There are ways, however, to make PowerShell treat non-terminating errors like terminating errors. That way we can use error handling to capture what's going on.
Here's an example of a non-terminating error (access denied to a subfolder), when attempting to list all folders and subfolders in "C:\Windows\appcompat\".
Get-ChildItem -Path 'C:\Windows\appcompat' -Recurse
Force Non-Terminating Errors to Terminate
You can force non-terminating errors to become terminating errors in PowerShell. There are a couple ways you can do this. Why would you want to do this, you ask? Since non-terminating errors cannot be handled by us, we need to force them to terminate, and gain the functionality of handling the error ourselves. This is not always needed, but it is good to know that you can do it if you come across a use case for yourself.
$errorActionPreference
You can do it at a global way for the session via the $ErrorActionPreference variable. This is a special variable in PowerShell that allows you to control what happens when a non-terminating error is encountered.
Here are the values for $ErrorActionPreference.
Stop
Display error, and stop execution.
Inquire
Display error, and ask to continue.
Continue (Default)
This is the default setting. Display error, then continue execution.
Suspend
This one is for workflows. A workflow job is suspended to investigate what happened, then the workflow can be resumed.
SilentlyContinue
No error is displayed, execution is continued.
Let's see this in action.
Get-ChildItem -Path 'C:\Windows\appcompat' -Recurse;Write-Host 'Test'
As you can see, with a non-terminating error, the next command in the sequence is executed. Therefore we see 'Test'. Let's set the $errorActionPreference automatic variable to Stop, and re-run the same command.
$ErrorActionPreference = 'Stop'
Get-ChildItem -Path 'C:\Windows\appcompat' -Recurse;Write-Host 'Test'
It worked! This would also let us use error handling with this error in PowerShell now. As you can see, we do not see the output of the next command, as it never ran.
Use the Command's -ErrorAction Parameter
Cmdlet's and functions/scripts/modules that use [cmdletbinding()] enable utilization of the -ErrorAction common parameter. This parameter allows you to specify different actions to take when an error is encountered.
Stop
Display error, and stop execution.
Inquire
Display error, and ask to continue.
Continue (Default)
This is the default setting. Display error, then continue execution.
Suspend
This one is for workflows. A workflow job is suspended to investigate what happened, then the workflow can be resumed.
SilentlyContinue
No error is displayed, execution is continued.
Ignore
The same as SilentlyContinue, but as SilentlyContinue still adds the message to the $error automatic variable, Ignore does not do this.
Let's set our $errorActionPreference to Continue, and then look at using the Cmdlet Get-ChildItem's -ErrorAction parameter.
We're setting $errorActionPreference back to Continue as earlier we set it to Stop for our other example. Continue is the default value.
$ErrorActionPreference = 'Continue'
Get-ChildItem -Path 'C:\Windows\appcompat' -Recurse -ErrorAction Stop;Write-Host 'Test'
Error Handling
There are a few different ways to to handle errors in PowerShell. The best way of course, is to never let them happen in the first place! To do that, it is good to have some data validation in place via an if statement, or whichever method suites your needs.
If a terminating error occurs, we can use Try/Catch/Finally blocks to perform different actions. If it is non-terminating, we can force it to become a terminating error, and then choose how to continue.
Validation
The simplest method of validation is the if statement.
If you'd like to run these examples yourself, go ahead and fire up the PowerShell ISE. Save a file in C:\PowerShell as part11.ps1.
An if statement is constructed as follows:
if (condition -eq $true) {
Do-Stuff
} else {
Do-Other-Stuff
}The condition can be anything that resolves to a true value. That includes running a command that output (other than and error) occurs! Check this out:
if (Get-ChildItem Z:\ -ErrorAction SilentlyContinue) { Write-Host 'I can list the contents of Z:!' } else { Write-Host 'I cannot list the contents of Z:!' }
This does not return true, as expected, and thus we see the message from the code in the else portion of the if statement. We use the -ErrorAction common parameter with the value SilentlyContinue to suppress the error from being displayed to the end user of the script. No need in this case, as we're simply using the command for validation.
You can also use variables with the if statement to see if they are blank.
$myVariable = $null if ($myVariable) { Write-Host "We have information! Let's do stuff." } else { Write-Host "`$myVariable is empty :(" }
The variable is empty, so the code in the else portion of the if statement is executed.
Try/Catch/Finally
The Try, Catch, and Finally blocks in PowerShell allow us to capture terminating errors.
The Try block contains the code you'd like to execute, and catch any potential errors that happen.
The Catch block contains the code you'd like to execute after a terminating error has occurred. The current error will be accessible via the automatic variable $_.
The Finally block contains the code you'd like to run after the event has occurred. This is good for cleanup tasks.
It is worth noting that finally block is not required.
Here is an example using Try/Catch/Finally:
Try { $command = 'Invoke-FakeCommand' Write-Host "Attempting to run: [Invoke-Expression -Command $command]"`n Invoke-Expression -Command $command } Catch { Write-Host $_.Exception.Message`n } Finally { Write-Host "Clean up: `$commmand = `$null"`n $commmand = $null }
The code in the Try block executes and we see the output of Write-Host. We then see the error message that occurs, as our Catch block is writing out $_.Exception.Message. As we learned earlier, that is the string value of the exception that raised the error.
We then see the output from the Write-Host command in our Finally block. We use the finally block to free up the $command variable.
This version of Try/Catch will catch any terminating errors that are raised. To capture specific exceptions, you'll want to use the exception's TypeName.
Catch Specific Errors
Let's take a look at the following:
Try { Get-ThisWontWork } Catch [System.Management.Automation.CommandNotFoundException] { Write-Host "Command not found!"`n -ForegroundColor Red Write-Host "Message: [$($_.Exception.Message)"] -ForegroundColor Red -BackgroundColor DarkBlue }
The exception was caught, and the code in the Catch block was executed.
Now let's try this...
Try { Get-ChildItem -Path Z:\ -ErrorAction Stop Get-ThisWontWork } Catch [System.Management.Automation.CommandNotFoundException] { Write-Host "Command not found!"`n -ForegroundColor Red Write-Host "Message: [$($_.Exception.Message)"] -ForegroundColor Red -BackgroundColor DarkBlue }
Ahh! An error that wasn't handled! Luckily we can add multiple catch blocks.
Let's add another Catch block.
Catch {
Write-Host $_.Exception.Message
}Try { Get-ChildItem -Path Z:\ -ErrorAction Stop Get-ThisWontWork } Catch [System.Management.Automation.CommandNotFoundException] { Write-Host "Command not found!"`n -ForegroundColor Red Write-Host "Message: [$($_.Exception.Message)"] -ForegroundColor Red -BackgroundColor DarkBlue } Catch { Write-Host $_.Exception.Message }
Now the exception from Get-ChildItem command is caught since the catch-all Catch block code is executed.
Getting Error Information
It can be handy to have a shortcut that shows you error information, which you can use to create specific Catch blocks. To do this, I created a function that I call in the Catch block which utilizes some validation itself! Here is the function:
function Get-ErrorInformation { [cmdletbinding()] param($incomingError) if ($incomingError -and (($incomingError| Get-Member | Select-Object -ExpandProperty TypeName -Unique) -eq 'System.Management.Automation.ErrorRecord')) { Write-Host `n"Error information:"`n Write-Host `t"Exception type for catch: [$($IncomingError.Exception | Get-Member | Select-Object -ExpandProperty TypeName -Unique)]"`n if ($incomingError.InvocationInfo.Line) { Write-Host `t"Command : [$($incomingError.InvocationInfo.Line.Trim())]" } else { Write-Host `t"Unable to get command information! Multiple catch blocks can do this :("`n } Write-Host `t"Exception : [$($incomingError.Exception.Message)]"`n Write-Host `t"Target Object : [$($incomingError.TargetObject)]"`n } Else { Write-Host "Please include a valid error record when using this function!" -ForegroundColor Red -BackgroundColor DarkBlue } }
Here is the full code I'll be running for this example:
function Get-ErrorInformation { [cmdletbinding()] param($incomingError) if ($incomingError -and (($incomingError| Get-Member | Select-Object -ExpandProperty TypeName -Unique) -eq 'System.Management.Automation.ErrorRecord')) { Write-Host `n"Error information:"`n Write-Host `t"Exception type for catch: [$($IncomingError.Exception | Get-Member | Select-Object -ExpandProperty TypeName -Unique)]"`n if ($incomingError.InvocationInfo.Line) { Write-Host `t"Command : [$($incomingError.InvocationInfo.Line.Trim())]" } else { Write-Host `t"Unable to get command information! Multiple catch blocks can do this :("`n } Write-Host `t"Exception : [$($incomingError.Exception.Message)]"`n Write-Host `t"Target Object : [$($incomingError.TargetObject)]"`n } Else { Write-Host "Please include a valid error record when using this function!" -ForegroundColor Red -BackgroundColor DarkBlue } } Try { Get-ChildItem -Path Z:\ -ErrorAction Stop Get-ThisWontWork } Catch [System.Management.Automation.CommandNotFoundException] { Write-Host 'Command not found Catch block executed!' } Catch { Get-ErrorInformation -incomingError $_ }
So now, if we wanted to catch this exception on it's own, we would need to add a catch block for [System.Management.Automation.DriveNotFoundException].
Catch [System.Management.Automation.CommandNotFoundException] {
Write-Host 'Command not found Catch block executed!'
}Let's add that to our code and run the following:
function Get-ErrorInformation { [cmdletbinding()] param($incomingError) if ($incomingError -and (($incomingError| Get-Member | Select-Object -ExpandProperty TypeName -Unique) -eq 'System.Management.Automation.ErrorRecord')) { Write-Host `n"Error information:"`n Write-Host `t"Exception type for catch: [$($IncomingError.Exception | Get-Member | Select-Object -ExpandProperty TypeName -Unique)]"`n if ($incomingError.InvocationInfo.Line) { Write-Host `t"Command : [$($incomingError.InvocationInfo.Line.Trim())]" } else { Write-Host `t"Unable to get command information! Multiple catch blocks can do this :("`n } Write-Host `t"Exception : [$($incomingError.Exception.Message)]"`n Write-Host `t"Target Object : [$($incomingError.TargetObject)]"`n } Else { Write-Host "Please include a valid error record when using this function!" -ForegroundColor Red -BackgroundColor DarkBlue } } Try { Get-ChildItem -Path Z:\ -ErrorAction Stop Get-ThisWontWork } Catch [System.Management.Automation.CommandNotFoundException] { Write-Host 'Command not found Catch block executed!' } Catch [System.Management.Automation.DriveNotFoundException] { Write-Host 'Get-ChildItem drive not found Catch block executed!' } Catch { Get-ErrorInformation -incomingError $_ }
There we go! Now all our errors are handled, minus the ones we don't know about yet.
Homework
Figure out why when multiple Catch blocks are used, it doesn't pass along the execution information (unable to get command/line).
Let me know why this is!
Where else could I have added error handling in any of these examples?
I hope you've enjoyed the series so far! As always, leave a comment if you have any feedback or questions!
-Ginger Ninja