Debugging Monad Scripts, Part 1: Teminating vs. Non-Terminating, ErrorRecord

  • Article

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 (https://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
  • ErrorRecord
  • $error
  • Write-Host
  • Set-Mshdebug [-Trace 0..2] [-Step] [-Off]
  • Preferences and Commandline Options
  • Trace-Expression
  • 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.

 

ErrorRecord

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.