Debugging Monad Scripts, Part 1: Teminating vs. Non-Terminating, ErrorRecord
Did your command or script fail and/or report an error? We hope to have a proper script debugger in a future version, but until then, MSH has some handy features to help you figure out what went wrong. In this series of blog entries, I will present some of those features. Thanks to Jim Truher [MSFT], Bruce Payette [MSFT], and Jeff Jones [MSFT] for their help in putting this together.
See the Windows “Monad” Shell Beta 2 Documentation Pack (http://www.microsoft.com/downloads/details.aspx?FamilyID=8a3c71d1-18e5-49d7-952a-c55d694ecee3&displaylang=en) for general information about Monad.
The following is a tentative table of contents for this series of blog entries:
- Terminating vs. Non-Terminating Errors
- Set-Mshdebug [-Trace 0..2] [-Step] [-Off]
- Preferences and Commandline Options
- Breakpoint Script
- How Traps Work
Terminating vs. Non-Terminating Errors
Before we start in with debugging, let’s do a quick refresher on how MSH reports errors. Errors are fundamentally divided into “terminating” and “non-terminating”, where terminating errors terminate the command (and sometimes the entire script), while non-terminating errors are generally just reported. In either case, there are ways you can configure how errors are managed. In general, operational errors (e.g. insufficient permissions to delete a file) are usually non-terminating, while most script bugs (e.g. syntax errors) are usually terminating.
Errors are represented by a System.Management.Automation.ErrorRecord object. The ErrorRecord object contains an Exception, plus other handy information for understanding the error and the context in which it occurred. The properties of ErrorRecord are:
Exception: This is the error which occurred.
TargetObject: This may be null. TargetObject is the object which was being operated on (file, service etc.) when the error occurred.
CategoryInfo: This divides all errors into a few dozen broad categories.
FullyQualifiedErrorId: This identifies the error condition more specifically than either the ErrorCategory or the Exception. Use FullyQualifiedErrorId to filter highly specific error conditions.
ErrorDetails: This may be null. If present, ErrorDetails can specify additional information, most importantly ErrorDetails.Message which (if present) is a more exact description and should be displayed instead of Exception.Message.
InvocationInfo: This may be null. InvocationInfo tells you about the context in which the error occurred — the cmdlet name, script line number etc.
[Edit: Monad has now been renamed to Windows PowerShell. This script or discussion may require slight adjustments before it applies directly to newer builds.]