Chapter 11. Finding and Avoiding Errors

The more complex your commands, pipelines, functions, or scripts become, the more often that errors can creep in. PowerShell has its own remedies for finding and correcting errors at various levels of complexity.

In simple cases, use "what-if" scenarios to check whether a command or a pipeline is really doing what you expect it to do. With the help of such scenarios, you can simulate the result of commands without actually executing the commands. You can permit commands to do their work only after you're convinced that the commands will function flawlessly.

If you've written your own functions or scripts, PowerShell can also step through the code and halt its execution at locations called breakpoints, which allow you to examine functions or scripts more closely at these locations. You can verify whether variables actually do contain an expected result. Moreover, PowerShell offers you the option of integrating debugging messages into functions or scripts. This enables your code to output progress reports to you at key locations when your code is in the development stage.

Topics Covered:

• "What-if" Scenarios
  • Dry Runs: Simulating Operations
  • Stepped Confirmation: Separate Queries
    • Table 11.1: Selection options in stepped confirmation
    • Automatic Confirmation of Dangerous Actions
• Defining Fault tolerance
  • Table 11.2: Setting options for ErrorAction and $ErrorActionPreference
• Recognizing and Responding to Errors
  • Error Status in $?
  • Using Traps
    • Traps Require Unhandled Exceptions
    • Using Break and Continue to Determine What Happens after an Error
    • Finding Out Error Details
• Error Records: Error Details
  • Error Record by Redirection
    • Table 11.3: Properties of an error record
  • Error Record(s) Through the -ErrorVariable Parameter
  • Error Records Through $Error
  • Error Record Through Traps
• Understanding Exceptions
  • Handling Particular Exceptions
  • Throwing Your Own Exceptions
• Catching Errors in Functions and Scripts
• Stepping Through Code: Breakpoints
  • Table 11.4: Settings for $DebugPreference
  • Table 11.5: Fine adjustments of the PowerShell console
  • Tracing: Displaying Executed Statements
  • Stepping: Executing Code Step-by-Step
• Summary

"What-if" Scenarios

Automation is enormously convenient, but it you can also automate errors into the process that can wreak total havoc. That's why PowerShell has some mechanisms t to check and protect against potentially dangerous processes: these mechanisms are simulation and stepped confirmation.

Dry Runs: Simulating Operations

If you'd like to first find out what effects a particular command could have when you use it, try simulation. PowerShell will make no changes to your system but show you what would happen if you were to run a command without simulation. Use the -whatif parameter, which many cmdlets support, to turn on simulation.

Of course, your own functions and scripts will support simulation only if you integrate them. Do this by simply defining a switch parameter called whatif:

Stepped Confirmation: Separate Queries

As you've seen, PowerShell commands, mainly by using wildcards like "*", are capable of carrying out several tasks at once. To prevent unintentional operations from running, you can give the command the task of asking for confirmation before carrying out every single operation. In contrast to simulation, stepped confirmation gives you the option of actually carrying out operations one at a time, or all at once. Use the -Confirm parameter to turn on stepping:

The confirming procedure offers you six options for each action that can be selected by pressing a button.

Automatic Confirmation of Dangerous Actions

Because some operations are more critical than others, developers of PowerShell cmdlets have assigned a risk evaluation to each command. There are three settings to choose from: Low, Medium, and High.

The Stop-Process cmdlet, which is used to stop running processes and programs, is set to Medium because while it is somewhat risky to stop processes, you normally shouldn't expect any irreversible damage. The Exchange cmdlet, used to remove a user mailbox, is categorized as High because when a mailbox is deleted all of its contents are lost as well.

You may not change this risk assessment, but you can respond to it. PowerShell's default setting requires that it check with you automatically about operations in the High risk category even if you haven't specified the -Confirm parameter. This standard setting is stored in the $ConfirmPreference variable so you can respond by making the default less or more rigorous. If you set $ConfirmPreference to "Low"(and use quotation marks), PowerShell will automatically question all actions. But if you set $ConfirmPreference to "None", PowerShell will no longer automatically question any actions, even if cmdlets are set to High.

Two consequences result from this:

• High-risk environment: If you are uncertain, or working in an environment in which the slightest error can have far-reaching consequences, set $ConfirmPreference to "Low" so that you will be queried even for actions that aren't so hazardous.
• Unintentional execution:If actions run unintentionally, then no interactive queries should appear, not even for risky actions. In such cases, turn off querying by using the -Confirm:$false parameter for a single command. Alternatively, turn off automatic querying in general by setting $ConfirmPreference="None". If you'd like to turn off automatic querying for scripts only but still keep the console in interactive mode, then set $script:ConfirmPreference="None" inside your script.

Defining Fault tolerance

PowerShell is very tolerant when errors occur: it simply continues execution—and that is often exactly the mode you want. For example, imagine if you started a file copying action that takes several hours. Returning to your system some time later, you wouldn't be pleased to find out that the operation had already been halted after the fifth data file because of an error. PowerShell default settings take this into account and carry out your tasks to the greatest possible extent rather than stopping them because of errors.

If an error fails to cause PowerShell to halt an entire task, you can end up with undesired consequences. Although PowerShell can't locate the file in the previous example and can't delete it for this reason, the subsequent command is executed anyway, and PowerShell concludes its work with a cheerful "Done!".

To determine how PowerShell handles errors, use ErrorAction, which specifies whether an error may terminate or may not terminate an operation. The default setting is "Continue", meaning that PowerShell will report an error but continue. Set ErrorAction to "Stop" so that PowerShell doesn't just go on processing the next statement but stops if a terminating error crops up. This setting will be in effect for all subsequent commands or only for a particular one as the case may be.

If the setting is supposed to apply to one particular command, use the -ErrorAction parameter of the command to set ErrorAction. Then the next command will halt the action and will no longer output any messages that the action was successful:

On the other hand, if you want the setting to apply universally as a new default to all commands, then assign it to the $ErrorActionPreference variable. Take the example of a script: type this statement at the beginning of your script if you prefer actions in general to be stopped when errors occur:

Recognizing and Responding to Errors

If you want to react to errors yourself so you can output your own, more readable error messages, you'll need two things: first, a way to suppress the built-in error message; second, a mechanism telling you whether an error has arisen or not. You already know how to suppress error messages because you have, once again, dealt with by ErrorAction. If you set it to "SilentlyContinue", then PowerShell will no longer output any error messages. You've already taken the first step:

Error Status in $?

Evaluate the $? variable as well to give the user feedback about whether an action was successful or not. . It will tell you whether an error has occurred. If one has, the variable will contain the value $false. This should give you enough to write a little evaluation script:

If you're now wondering about the peculiarity of the conglomeration "(!$?)", here's a brief refresher: "!" stands for the logical "Not" operator. The condition is met if the $? variable doesn't contain the $true value (meaning that an error has occurred). Break ensures that the string doesn't keep on running. The result is that the text "Everything's okay!" will be output only if an error hasn't occurred.

If you'd like to find out just what sort of error came up, inspect the element 0 in the $error array. PowerShell keeps a record of all errors in $error. The most recent one is in the element 0:

Using Traps

Alternatively, you can use so-called "traps". If you know that a particular command may not execute successfully under runtime conditions, then note in front of it what should happen if an error occurs:

This shows that the Trap statement specifies PowerShell code that is meant to run as soon as an error occurs that cannot be handled in any other way.

Traps Require Unhandled Exceptions

To get this to work, an error really does have to occur or, to be precise, an unhandled exception has to come up. In the next example, you'll see that this is not always the case because the code after Trap is not executed, even though an error message pops up:

The reason: the 1/0 statement consists exclusively of constant values; that's why PowerShell evaluates it even as it is being compiled. The parser that performs this task recognizes entirely on its own that the statement is an invalid numerical value and handles the error itself. So, it isn't even reported to Trap. Very much the same thing happens with most cmdlets because when a cmdlet triggers an error, the error is likewise processed internally by the cmdlet and is not reported to Trap:

Surely, it must be possible to catch an error inside a cmdlet? Yes, but only if you set the ErrorAction of the cmdlet to "Stop", which ensures that the error does in fact get reported back to the caller and that the cmdlet doesn't snare it internally:

Using Break and Continue to Determine What Happens after an Error

After Trap has processed the error by executing the code you specified after Trap, it continues execution. That means that PowerShell will output the error message about the current error and continue execution with the next command just as if nothing at all had happened. That's why in the next example your own error message is output first, then PowerShell's, and finally all further commands, which in this case means the text "Hello":

If you would like a different response, use the keyword Break or Continue in the Trap statement. If you specify Continue, Trap will behave to a certain extent like the ErrorAction "SilentlyContinue" and will suppress the integrated PowerShell error message:

Trap continues execution with the next statement, which is in the same block as Trap itself. That might seem to be hedged in with too many clauses, but that doesn't play any role in this example because there's only one area. A little later on, you'll see that such a subtlety is actually very crucial.

If you use the Break statement instead of Continue, Trap will respond to a certain extent like the ErrorAction "Stop" and will generate its built-in error message. Subsequent statements will no longer be executed.

Finding Out Error Details

Inside the code after Trap, PowerShell automatically inserts the $_ variable, which includes all details about the current error. Your "universal" Trap might look like this if you want to catch an error and output details:

Error Records: Error Details

You have just output details about the error using the $error automatic variable and $_ inside the Trap block. Let's take a closer look at what is actually stored in these variables and how an Error Record looks. Error Records are precisely what the name says, namely what you normally see when an error occurs in PowerShell: the actual error message, which PowerShell displays in red:

However, this is only how Error Records look when you output the records in the console because PowerShell, as always, reduces the object with its wealth of information to text. Just how do you access the actual Error Record object? There are four approaches:

• Redirection: Redirect the error stream to a variable.
• The -ErrorVariable parameter: The error record will be stored in this variable if you use the -ErrorVariable parameter to specify a variable name.

• $error: All errors will be stored as an error record in the $error variable. As a result, the last error is in $error[0].
• Traps and $_:Inside the Trap statement, the current error record is provided in $_.

Error Record by Redirection

If you want to redirect a command result, use the redirection operator ">":

Unfortunately, that won't help if the command outputs an error, because errors are not written in the standard stream but in the Error stream. If you want to redirect it, the redirection operator must be "2>":

It works: the error message—the Error Record—was in fact redirected and written in a file that Get-Content subsequently reads. However, Error Record is actually not text at all but, like nearly everything else in PowerShell, an object containing much more information than its plain text representation. When you redirect Error Record to a file, much of the data contained in Error Record gets lost in the process. The clever method is this:

The central point of this example is the redirection to &1, a character combination that stands for the output pipeline. Think about this for a moment: If you had passed a valid directory name to the Dir command, the command would have retrieved the directory listing, and you could have stored the result in a variable without any difficulty. Nobody would have wondered:

By using the "2>&1" redirection operator, you can simply send just the error information— Error Record—over the same route, and that's why you can directly allocate Error Record to a variable and evaluate it afterwards. The properties of Error Record listed in Table 11.3 are available to you.

But note that you are given these properties only if the error record was actually output visibly without redirection. The following statement returns "null":

Error Record(s) Through the -ErrorVariable Parameter

Redirection isn't always necessary. Most cmdlets support the -ErrorVariable parameter after you specify the name of a variable. The Error Record will then be stored in this variable independently of the current ErrorAction:

However, what is now present in $myError isn't quite identical to what redirection stored in $myError. In the redirection process, exactly one Error Record was stored—namely the one that would have otherwise been visibly displayed as an error message. The -ErrorVariable parameter always returns an array. The array has only one element, but if you want to evaluate the Error Record and its manifold properties, you will have to specifically access this array element:

And why is Error Record stored in an array? Isn't that totally superfluous when, after all, there's only one Error Record? Several Error Records can in fact exist. In the next example, the directory listings will be retrieved from three different directories where none exists. The result is three Error Records:

You can also collect the Error Records of several statements in your variable to document entire sequences of errors. Just type a "+" in front of the variable name for the -ErrorVariable parameter.

Error Records Through $Error

There's still another way to get to Error Records. PowerShell keeps exacting records of all errors and stores these records in the $Error variable. So, even if you've forgotten to redirect the Error Record in time or to specify the -ErrorVariable parameter, you can still get to the Error Record of an error.

$Error is an array, too. The most current error always ends up as the first entry (with the index 0) and all other errors move up their position once. The number of errors stored is limited to ensure enough storage space when many errors are recorded. The maximum number is set in $MaximumErrorCount.

Error Record Through Traps

Finally, the Trap statement also offers a way to get to the current Error Record. Access is gained through the $_ variable inside the Trap statement, and you could use Trap to generate your own error messages very easily:

Understanding Exceptions

"Exceptions" are not everyday occurrences. In the contemporary IT world, the terms "errors" or "bugs" tend to be avoided. Instead, a more elegant word, "exception," is used. When an error occurs, an exception is thrown and has to be "remedied." Either the command responsible for the error rectifies the error or the exception escalates and it has to be remedied at the next-highest level. If nobody tackles the error, it will end up highlighted in red in the PowerShell console.

Because there are different types of exceptions, it is interesting to examine the exception type of an error more closely. This is a way for you to initiate different actions according to the approximate cause of an error. Take a look at how you can flush the exception of an error out into the open:

Both examples presuppose that errors were actually listed previously, because otherwise $error would be null.

Handling Particular Exceptions

The code set by Trap is normally executed for any exception. As you've just seen, there are exception groups, and if you'd prefer to use one or several groups of different error handlers, go ahead. Just write several Trap statements and specify for each the type of exception for which the statement is responsible:

Throwing Your Own Exceptions

If you're writing your own functions or scripts, sooner or later you'll want to output your own error messages in them. You should never output unchangeable error messages to enable your functions and scripts to be inserted like building blocks in PowerShell just like all the previous cmdlets and functions you've already seen.,. Instead, it would be better to use Throw to throw exceptions and to leave it up to the system to handle your exception.

Of course, you already know from your reading of Chapter 9 that it's best for you to define error messages about the arguments of a function as default values. The previous example was supposed to be just a general demonstration of how exceptions are thrown inside a function. If the objective is merely to validate the correct arguments, the function can be simplified considerably:

But the main thing is that your function should not output its own error messages in the event of a fault, but instead throw an exception. That leaves it up to the user of the function to decide what to do with the exception you have thrown:

Catching Errors in Functions and Scripts

Error handling basically works in your own functions or scripts just as it does in the console. Use traps if you want to catch errors. In this connection, it isn't important where you exactly situate the Trap statement. No matter if you put the statement at the beginning or at the end, as soon as an error occurs inside the function, the Trap statement code will be executed. This means that the following two functions would behave in exactly the same way:

The result of the function example is interesting and confusing at the same time. The first statement inside the function doesn't cause an error. That's why the code after Trap is executed and returns the error message "An error occurred". PowerShell's error message follows afterwards because ErrorAction is not set to SilentlyContinue. The remaining two faulty commands are also executed. To be precise, they are executed this time without renewed execution of the Trap block.

You already know the reason why: Trap can only capture errors that it can see. Cmdlets use the standard setting Continue as ErrorAction. In this setting, cmdlets do not report errors to the caller but handle errors themselves. If you'd like your trap to deal with such errors, you must reset ErrorAction to Stop:

Now, the function works the way it was expected to originally. The trap is called for every single error. However, internal PowerShell error messages are still generated subsequently. Error messages will no longer appear if you use Continue to instruct your trap to keep on going after the error. Your trap should return an explanatory comment so that you can also find out which error actually occurred.

If you would prefer that the function stops when the first error occurs, you should use the Break statement inside Trap: instead of Continue.

Now the function is stopped when the first error occurs, but the internal PowerShell message turns up again after your own error message. Break does stop execution in the current area, but does this by throwing the original error again and letting PowerShell handle it. This means that when you use Break you'll always get the PowerShell error message.

If you would prefer that a function stops after the first error without PowerShell adding its own error message, you must do without Break and understand a little better what the Continue statement is actually doing. Continue carries on execution after an error with the next statement that is in the same area as Trap. So, if the Trap statement is inside your function, and if an error occurs, then Continue would carry on with the next command inside the function. However, you must move Trap to the parent area since you want the function to stop after the first faulty command. You could call the function from within a second function:

Now the sequence of operations functions as requested. Trap recognizes the first error in the Malfunction function and because of Continue carries on execution with the next statement: not with the next statement in Malfunction but with the next statement in Caller, because that's where Trap was defined.

Of course, this type of call is little peculiar. Do you really have to bother about a second separate caller function just so you can stop a function when the first error occurs and take care of the error yourself? You don't. You just need to make sure that the Trap statement is in another area than the one in which the rest of the function is located. For example, you could define an additional one inside your function and then call it:

In the next chapter, you'll find out in detail how PowerShell really implements functions. You'll learn more about scriptblocks. You don't necessarily have to create your own nested subfunctions. It suffices for you to put critical instruction lines in their own scriptblock and to use the call operator "&" to execute the block:

Stepping Through Code: Breakpoints

You can stop PowerShell code inside your functions and scripts at any point to see whether everything is working the way it should. To do so, use breakpoints, which are nothing more than commands. In less complicated cases, you can input the breakpoint command right in the PowerShell console:

Surprisingly, this command appears to have no effect whatsoever. Nothing happens. The reason is that the $DebugPreference variable is set as default for the "SilentlyContinue" variable. "SilentlyContinue" corresponds exactly to what you've already seen it do: output nothing, continue. As long as $DebugPreference is set to this value, debugging is turned off. If you want to turn it on, set $DebugPreference to another one of the values listed in Table 11.4.

There you have the tools you need for a little debugging kit:

• Installing breakpoints: Use Write-Debug at all locations inside a function or a script that you want to monitor more closely and have Write-Debug output useful comments.
• Simple debugging: Switch $DebugPreference to "Continue" so that Write-Debug will output its comments, allowing you to follow the sequence of code operations.
• Extended debugging: Switch $DebugPreference to "Inquire" so that Write-Debug works like a real breakpoint. Execution is then stopped for every Write-Debug, and you can use the suspend option to get back to a prompt and from there use customary PowerShell commands, such as to verify the contents of variables. Execution will be continued as soon as you type the exit command.
• Turning off debugging again: If you would like to stop debugging again, simply set $DebugPreference to the initial value "SilentlyContinue". All Write-Debug statements will immediately be ignored so that you won't need to remove these statements. Perhaps you would like to debug the code later again. As long as $DebugPreference is set to "SilentlyContinue", these statements will have no effect.

The following loop shows how your breakpoints will respond to different settings for $DebugPreference. If you use the default for execution, 10 numbers will be output:

If you turn on simple debugging, the Write-Debug comments will be highlighted in yellow:

By using extended debugging, you can convert Write-Debug statements into genuine breakpoints. You could also interrupt execution, inspect variables, and even make changes. As soon as you enter the Exit command, execution will continue:

Aside from the automatic variable $DebugPreference, which you can use to determine whether and how debugging messages are output, there are a number of additional automatic variables that work in a similar way and define how PowerShell should respond if you make no further specifications (Table 11.5).

Tracing: Displaying Executed Statements

You don't necessarily have to insert debugging statements into your code since sometimes it's not your code that is even being executed. .However, you do have the option to enable tracing. This allows PowerShell to output each statement automatically as a debugging message. The cmdlet Set-PSDebug manages tracing.

Here, PowerShell lists the PowerShell code of the ScriptProperty Mode, which is executed when you output a directory listing.

Simple tracing will show you only PowerShell statements executed in the current context. If you invoke a function or a script, only the invocation will be shown but not the code of the function or script. If you would like to see the code, turn on detailed traced by using the -trace 2 parameter.

If you would like to turn off tracing again, select 0:

Stepping: Executing Code Step-by-Step

You don't even need your own breakpoints to run PowerShell code one step at a time. Just turn on automatic stepping:

From then on, PowerShell will ask you when every single statement is displayed whether you want to execute the statement, skip it, or temporarily suspend the code.

If you choose Suspend by pressing "H", you will end up in a nested prompt, which you will recognize by the ">>" sign at the prompt. The code will then be interrupted so you could analyze the system in the console or check variable contents. As soon as you enter Exit, execution of the code will continue. Just select the "A" operation for "Yes to All" in order to turn off the stepping mode.

By the way, you can also create your own breakpoints by using nested prompts: call $host.EnterNestedPrompt() inside a script or a function.

Summary

By using "what-if" scenarios, you can validate the consequences of commands in safe dry runs. One option is to specify the -whatif parameter if you'd like to see what a command might do. The other option is to specify the -Confirm parameter if you would like to confirm every single operation manually before execution (Table 11.1). Most cmdlets support both parameters so you can reproduce this functionality in your own functions or scripts by using self-defined switch parameters.

Code in functions and scripts can be provided with debugging messages and breakpoints for diagnostic purposes. Insert Write-Debug statements into the code and use $DebugPreference to determine whether Write-Debug outputs a message or is actually supposed to suspend the code at the location (Table 11.4). If the code is suspended, you can make a detailed examination of the variables of your function or script in the console. Type Exit when you end the breakpoint and want to continue execution of code.

PowerShell includes other automatic variables that enable you to determine whether and when commands have to be confirmed and how detailed error reports should be (Table 11.5). Among these variables is $ErrorActionPreference, which you can use to specify whether PowerShell should continue execution even if errors occur, or stop execution. The default setting does not stop execution when errors occur unexpectedly.

You can evaluate a number of variables if you prefer responding to errors yourself. The $? variable contains $false if the last command caused an error. PowerShell lists error details in the $error array, in which every error is stored as an Error Record.

You can gain more control over errors by using traps, which are statements executed when an error occurs. So that traps work, the error really must throw an exception and may not be caught by the command that caused it. For this reason, traps can react to errors only if you have previously switched ErrorAction from Continue to Stop.

Within the code after Trap, you'll be provided with all the details on the current error in the $_ variable, which contains the Error Record of the error. Your Trap statement can also use the Break and Continue statements to determine what will happen next. If you specify Break, then execution will be ended in the code block where Trap is defined. PowerShell will output the error message of the current error. If you specify Continue, PowerShell will continue execution with the next statement in the same block where Trap is defined. PowerShell will not output any error message.