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.

Part 1: http://blogs.msdn.com/monad/archive/2005/11/04/489138.aspx (Terminating vs. Non-Terminating Errors, ErrorRecord)
Part 2: http://blogs.msdn.com/monad/archive/2005/11/08/490130.aspx ($error)
Part 3: http://blogs.msdn.com/monad/archive/2005/11/09/490625.aspx (write-host)
Part 4: http://blogs.msdn.com/monad/archive/2005/11/09/491035.aspx (set-mshdebug)

Jon Newman [MSFT]

 

Preferences and Commandline Options (Debug, Verbose etc.)

Where set-mshdebug enables script tracing and step-step, Debug and Verbose output allow you to trace and suspend/restart individual cmdlets. Many cmdlets contain verbose and debug information which they will only print if you explicitly request it; you can also call write-debug, write-verbose, and write-warning (also write-object, write-error and write-progress) in your script.

MSH C:\temp> $VerbosePreference
SilentlyContinue
MSH C:\temp> write-verbose test
MSH C:\temp> $VerbosePreference = "Continue"
MSH C:\temp> write-verbose test
VERBOSE: test
MSH C:\temp> $VerbosePreference = "Stop"
MSH C:\temp> write-verbose test
VERBOSE: test
Write-verbose : Command execution stopped because the shell variable "VerbosePreference" is set to Stop.
At line:1 char:14
+ write-verbose <<<< test
MSH C:\temp> $VerbosePreference = "Inquire"
MSH C:\temp> write-verbose test
VERBOSE: test
Confirm
Continue with this operation?
[Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): y
MSH C:\temp>

You can configure the behavior of debug, verbose and errors with both command-line options and preference variables. The following command-line options are available on every cmdlet, and can be configured separately for each cmdlet:

  • -Verbose: Print verbose output
  • -Confirm: Inquire whether to continue before the cmdlet makes a change
  • -Debug: Inquire whether to continue whenever any of the following occur: debug output, verbose output, warning output, non-terminating error, cmdlet makes a change
  • -ErrorAction <ActionPreference> : Request the "SilentlyContinue", "Continue", "Stop" or "Inquire" behavior when a non-terminating error occurs.

Your preference choices are:

  • "SilentlyContinue": Ignore and continue
  • "Continue": Print and continue
  • "Stop": Halt the command or script
  • "Inquire": Ask the user what to do

You can also set preference variables which set the default behavior where the above command-line options are not specified. The actions which you can configure are:

  • $VerbosePreference: for verbose output only
  • $ConfirmPreference: what to do before the cmdlet makes a change
  • $DebugPreference: for debug output only
  • $WarningPreference: for warning output only (default is to print warning output)
  • $ProgressPreference: for progress output only
  • $ErrorActionPreference: what to do when a non-terminating error occurs

Regardless of the ErrorAction settings, $error is always populated (whether you see a message or not):

MSH C:\temp> get-process -ErrorAction SilentlyContinue doesnotexist
MSH C:\temp> $error[0]
get-process : No process with process name 'doesnotexist' was found.
At line:1 char:12
+ get-process  <<<< -ErrorAction SilentlyContinue doesnotexist
MSH C:\temp>

[Edit: Monad has now been renamed to Windows PowerShell. This script or discussion may require slight adjustments before it applies directly to newer builds.]