PowerShell has long been known for its cryptic error messages. Some of the most popular articles that I have written have been geared toward deciphering PowerShell error messages. When it comes to PowerShell errors, though, where the error occurs can make a big difference in the overall experience. It’s one thing to build a script and have that script to produce an error message while you are testing it. It’s quite another thing to write and test a script, give it to a user, and have them receive an error message when they try to run it.
Thankfully, there is a way to build custom error messages into a PowerShell script. By doing so, you can make it easier to figure out what is going on when a script produces an unexpected error.
There are two commands that you will need to be familiar with to build custom error messages into your script — try and catch. The try command tests a block of code to see if it produces an error. If an error does occur, then the catch command can be used to tell PowerShell how to handle the error.
Try and catch
To show you how try and catch work, let’s start with a really simple example. Any time that you enter a command that PowerShell does not recognize, it produces an error stating that the term is not recognized. If you look at the figure below, for instance, you can see that I entered “ABCDE” into PowerShell. Since ABCDE is not a valid command, PowerShell returned the “term is not recognized” error.
In this case, I entered the ABCDE command directly into PowerShell, but if I had included this invalid command in a PowerShell script, it would have done the same thing. You can see what happens when I run such a script in the screenshot below.
So rather than having PowerShell generate a generic term not recognized error, let’s create a custom error message. The way that we can do that is by using the try command and then surrounding the command that we want to evaluate in brackets. This command might look like this:
try {ABCDE}
This command evaluates the ABCDE command to see whether or not it produces an error message. Keep in mind that even though I am using a command that normally produces a term not recognized error, the try command is able to detect any error condition regardless of its cause.
Now speaking of errors, if you use the try {ABCDE} command that I showed you a moment ago by itself, you will get an error message. That’s because the Try command isn’t designed to work by itself. It must be paired with either a catch command or a finally command. For the purposes of this article, I am going to focus on the catch command. In case you are wondering though, the finally command terminates the script and releases its resources.
As previously noted, the catch command tells PowerShell what to do if the try command detects an error message. In this case, I used the try command to evaluate ABCDE, which isn’t a real command. So, let’s take a look at how to make the catch command display an error message stating that ABCDE isn’t a real command. Here is what such a command might look like.
catch {Write-Host ‘ABCDE is not a valid PowerShell command. You might try using a different command’}
Here is what happens when I run a script containing this catch command.
As you look at the image above, you can see that PowerShell did not display its signature red error message. Instead, it displayed the more helpful and less threatening message that I defined by way of the catch command.
So, you might be wondering what happens if PowerShell evaluates the code within the try block and does not encounter an error condition. To show you how PowerShell deals with this, I am going to change the ABCDE command that I used earlier into Write-Host ‘ABCDE’. This is a valid PowerShell command that should simply display “ABCDE.” You can see the command’s normal behavior below.
So with that in mind, check out the next screen capture. As you can see, the try command is now evaluating a command that does not produce an error. Since no error was detected, PowerShell executes the command in the usual way, as if the try and catch commands did not even exist.
Try and try again
If you write a script, you are probably going to test it before you hand the script to an end-user. As such, it makes no sense to create a custom PowerShell error message telling the user that the command that you just used is completely invalid and that they would not have received the error if you had just taken five minutes to test the script. As such, the type of error trapping that I just showed you makes no sense in the real world.
But keep in mind what I said earlier. The try command only checks to see if an error condition has occurred. It doesn’t care what caused the error. That means that you can strategically place Try commands in your scripts in an effort to gain a bit of insight when things go wrong. For instance, if a PowerShell script has to download a file, you could use the try command to detect a failed download and display an appropriate message in response to the failure. You might do something similar if a PowerShell script fails to load a module that is required in order for the script to run. There are many different ways that you can use the try and catch commands to create a better overall end-user experience.
Featured image: Designed by Gstudioimagen / Freepik
