Recently I posted the following to the Microsoft.Public.Windows.PowerShell newsgroup (which you should participate in if you are not yet) 

Below is a function that I encourage you to add to your Profile files and
then use when reporting an error or ask a question about a exception you are
seeing.  This function provides all the information we have about the error
message making it easier to diagnose what is actually going on.

function Resolve-Error ($ErrorRecord=$Error[0])
{
   $ErrorRecord | Format-List * -Force
   $ErrorRecord.InvocationInfo |Format-List *
   $Exception = $ErrorRecord.Exception
   for ($i = 0; $Exception; $i++, ($Exception = $Exception.InnerException))
   {   “$i” * 80
       $Exception |Format-List * -Force
   }
}
Set-Alias rver Resolve-Error

This brings up a couple of questions I thought I would respond to.

1. Why did we have to use -FORCE with Format-List?

Errors generate ErrorRecords:

[596:0]PS> $error[0] |gm -MemberType Property

   TypeName: System.Management.Automation.ErrorRecord

Name                  MemberType Definition
—-                  ———- ———-
CategoryInfo          Property   System.Management.Automation.ErrorCateg…
ErrorDetails          Property   System.Management.Automation.ErrorDetai…
Exception             Property   System.Exception Exception {get;}
FullyQualifiedErrorId Property   System.String FullyQualifiedErrorId {get;}
InvocationInfo        Property   System.Management.Automation.Invocation…
TargetObject          Property   System.Object TargetObject {get;}

These ErrorRecords get passed to the Output Stream just as the results of a command do.  The formatting commands are hardwired to recognize these objects and treat them specially. They will treat them specially UNLESS you tell them not to with -FORCE.  Let me show you:

[596:0]PS> cd NoSuchDir
Set-Location : Cannot find path ‘C:\jps\NoSuchDir’ because it does not exis
t.
At line:1 char:3
+ cd  <<<< NoSuchDir
[596:0]PS> $error[0] |Format-List CategoryInfo,TargetObject
Set-Location : Cannot find path ‘C:\jps\NoSuchDir’ because it does not exis
t.
At line:1 char:3
+ cd  <<<< NoSuchDir
[596:0]PS> $error[0] |Format-List CategoryInfo,TargetObject -Force

CategoryInfo : ObjectNotFound: (C:\jps\NoSuchDir:String) [Set-Location], It
               emNotFoundException
TargetObject : C:\jps\NoSuchDir

2. Why use the verb RESOLVE

Verb names are designed to be simultaneously specific and vague.  They need to be specific enough that people can learn the meanings and have them stick and be used as the basis for guessing about what to do.  They need to be vague enough so that they cover a wide range of things so we don’t end up with zillions of “precise” terms (“oh well you see, ‘kill’ is different than ‘stop'”.  “actually we ‘terminate'”, “my product ‘ceases’ operations, ” ‘quit’ is a bit more accurate, – you can almost see the conversations in you head).

Here is a pointer to the VerbNames and their meanings: http://msdn2.microsoft.com/en-us/library/ms714428.aspx

“Resolve” is a diagnostic verb.  It is used to”map a shorthand name to a long name”.   What we are doing is mapping a digested “short” version of an error object to a fully articulated “long” version of that object for diagnostic purposes (to find out what is really going on).   A reasonable person could have said that “Dump-Error” would be a better name but (AND THIS IS THE POINT) if we start argeeing to reasonable people about naming, we are going to end up with a zillion reasonable names. 

Local Optimization leads to global incoherence.

Yes Resolve-Error may not be the most intuitive name right now.  That’s because you haven’t being using Resolve-X, Resolve-Y, and Resolve-Z for the last couple of years.  We (that’s us and you) need to be really hard-core about naming for the first couple of years or we’ll end up with world filled with “AWK”s. 

For those of you who don’t already know this, AWK is the first letters of the 3 guys that worked on it (Aho, Weinberger, and Kerrigan).  I love those guys and the fabulous work that they did.  So here is the lesson – if you want to honor or remember someone – build a statue, don’t screw up the command naming.  🙂

Apologies for all the tangents today.
Enjoy!

Jeffrey Snover [MSFT]
Windows PowerShell/Aspen Architect
Visit the Windows PowerShell Team blog at:    http://blogs.msdn.com/PowerShell
Visit the Windows PowerShell ScriptCenter at:  http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx