Error Handling: Part1 - $Error Objects
Error handling is one thing that is not discussed as much as it should be. It is one the most important parts of working with any scripting language and in this case the interactive nature of Powershell. We have had much discussion in the IRC channel over the last couple of weeks, discussing this exact topic. So I thought I should do my best to post what I have gleaned from the discussion.
This is one of at least a two part (maybe Three) series.
* Error Handling: Part1 - $Error Objects
* Error Handling: Part2 - Throw “A word about Trapping”
* Error Handling: Part3 - The Power of Set-PSDebug
Ask anyone that writes scripts. The ratio for Error correction in code is INSANE. Its almost 2/1. A 10 line script soon becomes 30 and a simple script becomes insanely complicated add to this the interactive nature of Powershell and you have the potential for many headaches. While Error handling in Powershell is far superior than anything to date… it still has some qwerks. I will do my best to cover some of these. Before we proceed from here, It is VERY important that you understand scope. I started to write this up, but to be honest, I think the Powershell team did a great job here. Please take some time to read the about file for scope.
PS> get-help about_Scope
Now, lets start off with some of the basics:
There are several built-in objects in powershell that control and provide information about Errors
$Error
> This is a object that stores an array of RICH Error objects
> Type: System.Management.Automation.ErrorRecord
$MaximumErrorCount:
> Total number of ErrorRecord objects that will be saved in $error
$LASTEXITCODE
> Exit Code of the Last script or native command than ran (i.e. ping.exe)
> This does NOT include cmdlets
$?
> Boolean Value that is $false if an error occured on the last command.
$ErrorActionPreference
> Determines the Default action if error is thrown
> Type System.Management.Automation.ActionPreference
> Continue: Outputs error, but keeps processing
> SilentlyContinue: No output and it keeps going
> Inquire: Prompt user for action
> Stop: Outputs error and halts processing
$ErrorView
> This is how the error will output to the screen
> This truly is a variable and can contain anything, but will use NormalView if anything other than CategoryView is the value
> NormalView: Default. Outputs semi-verbose description,Line Number, and character
> CategoryView: Only displayes the category the error is in.
Now that we have an overview of the objects that make up the error environment in Powershell lets deep dive into a couple of the more important ones.
$Error: This is by far the object with the most amount of data… it really does contain pretty much everything you could possibly want to know about an error. It is important to realize that this is truly an object. It has properties, methods, and even a Type just as all the other objects have. You can see this by piping $error to get-member
TypeName: System.Management.Automation.ErrorRecord
Name MemberType Definition
==== ======== ========
Equals Method System.Boolean Equals(Object obj)
GetHashCode Method System.Int32 GetHashCode()
GetObjectData Method System.Void GetObjectData(SerializationInfo info, StreamingContext context)
GetType Method System.Type GetType()
get_CategoryInfo Method System.Management.Automation.ErrorCategoryInfo get_CategoryInfo()
get_ErrorDetails Method System.Management.Automation.ErrorDetails get_ErrorDetails()
get_Exception Method System.Exception get_Exception()
get_FullyQualifiedErrorId Method System.String get_FullyQualifiedErrorId()
get_InvocationInfo Method System.Management.Automation.InvocationInfo get_InvocationInfo()
get_TargetObject Method System.Object get_TargetObject()
set_ErrorDetails Method System.Void set_ErrorDetails(ErrorDetails value)
ToString Method System.String ToString()
CategoryInfo Property System.Management.Automation.ErrorCategoryInfo CategoryInfo {get;}
ErrorDetails Property System.Management.Automation.ErrorDetails ErrorDetails {get;set;}
Exception Property System.Exception Exception {get;}
FullyQualifiedErrorId Property System.String FullyQualifiedErrorId {get;}
InvocationInfo Property System.Management.Automation.InvocationInfo InvocationInfo {get;}
TargetObject Property System.Object TargetObject {get;}
Note: Because $error is an array it inherits from [System.Array] and its methods. Clear() is the most notable.
I could probably do a whole post on just $error, but that is beyond the scope of this one so I want just cover a few properties and one method
ErrorDetails
> This provides the Details of the Error. I wanted to note this is often blank
Exception
> This is the actual exception that was thrown
> This is an object so it will have properties and methods of its own.
TargetObject
> This is the object that operation was being performed when the error occured.
InvocationInfo
> This contains detail information about the command that was run (i.e. Line Number, CMDlet, and Position)
Clear()
> This method clears the $error array.
More Info: http://msdn2.microsoft.com/en-us/library/system.management.automation.errorrecord.aspx
$ErrorActionPreference: I would say this is the second most important object for error handling. I have personally seen this question posted at least 10 times on the News Groups, “What is the powershell equivalent to “On Error Resume Next.” The answer lies in this object more specifically by setting $ErrorActionPreference to “SilentlyContinue.” One thing I would like to point out about this particular object is that it is scope specific. This is very important to understand. Learning to control error action at the lowest level is key to writing good scripts and knowing the state of this object can save you a ton of heartache. I cant tell you how many times I beat my head against the wall trying to figure out why I wasnt getting any error information… hmmm, $erroractionpreference set to “SilentlyContinue,” maybe that is the problem.
More Info Here: http://msdn2.microsoft.com/en-us/library/system.management.automation.actionpreference.aspx
In Summary, I think this a good overview of the Error Variables/Objects that you have access to, but it really only scratches the surface. I would suggest spending some time on MSDN looking through system.management.automation Namespace and get a good idea of all the information there.
tshell :: Oct.10.2007 :: .NET, ErrorHandling, HowTo, Powershell, Scripting :: No Comments »
[...] The first thing you need to know about trapping is that you don’t always have to do it. The $ErrorActionPreference can be set to “Continue” when an error is thrown (or even “SilentlyContinue”) which is basically the equivalent of VB (Visual Basic)’s ON ERROR RESUME NEXT and doesn’t require any specific error handling code. If you’re sure of where errors might occur, you can set that to SilentlyContinue at the top of your script, and then after any line where you might have an exception, just check for an error like this: if(-not $?) { #handle $Error … The $Error Object is fairly well documented, so I’ll just leave the rest to your experimentation. [...]
[...] Read the rest of this great post here [...]