Click here to Skip to main content
Click here to Skip to main content

User Friendly Exception Handling

, 17 Aug 2004
Rate this:
Please Sign up or sign in to vote.
A flexible framework for user-friendly .NET exception handling, and automatically notifying developers of problems before users do

Sample Image - ExceptionHandling.gif


In Visal Basic 6, there was no way to globally handle all of the errors in your application. You could simulate one by wrapping every sub or function in an On Error statement, but that was rather painful.

One of the great features of .NET is the very powerful thread and application level exception handling mechanisms that make developing a global error handler practical. One of the first things I set out to do when starting with .NET was finally implement all those great global error handling ideas I had considered, but had to abandon in the last 5 years of working with VB5 and VB6. I found an excellent article on Code Project documenting the basic techniques of unhandled exception handling in .NET, so armed with that, I set out to implement my "dream" error handling system.

At the time of the unhandled exception, my UnhandledExceptionHandler class will:

  • Display a user-friendly message
  • Capture a screenshot of the user's desktop
  • Build a string containing all the diagnostic information possible
  • Notify the developers via SMTP e-mail, and include the screenshot
  • Write an event to the event log
  • Write a text log in the application folder

About Unhandled Exceptions

The great thing about a good global exception handler is that it makes the rest of your code easier to read. Rather than cluttering up your code with Try..Catch blocks for every possible error condition, no matter how rare, you can simply rely on the solid, built-in global handler to deal with those oddball scenarios-- and to notify you when they happen!

So then the natural question that most developers ask is, "When should I catch exceptions"? And it's a very good question. Here are some guidelines that I have found useful.

  1. Unless you have a very good reason to catch an exception, DON'T. Exceptions are supposed to be exceptional, just like the dictionary meaning: uncommon, unusual. When in doubt, let the calling routine, or the global exception handler, deal with it. This is the golden rule. The hardest kinds of exceptions to troubleshoot are the ones that don't even exist, because a developer upstream of you decided to consume it.
  2. If you can correct the problem implied by the exception. For example, if you try to write to a file and it is read-only, try removing the read-only flag from the file. In this case you handled the exception and fixed the problem, so you should eat the exception. It doesn't exist, because you fixed it.
  3. If you can provide additional information about the exception. For example, if you fail to connect via HTTP to a remote website, you can provide details about why the connection failed: was the DNS invalid? Did it time out? Was the connection closed? Did the site return 401 unauthorized, which implies that credentials are needed? In this case you want to catch the exception, and re-throw it as an inner exception with more information. This is a very good reason to catch an exception, but note that we are still re-throwing it!
  4. Always try to catch specific exceptions. Avoid catching System.Exception whenever possible; try to catch just the specific errors that are specific to that block of code. Catch System.IO.FileNotFound instead.
There are, of course, times when you'll want to violate these rules for completely legitimate reasons-- but at least consider them before you do.


This approach leverages two specific exception handlers. The Application.ThreadExceptionHandler, which works for the main application thread of a Windows Forms application:
AddHandler Application.ThreadException, AddressOf ThreadExceptionHandler

And the AppDomain.CurrentDomain.UnhandledException handler, which works for Console applications:

AddHandler System.AppDomain.CurrentDomain.UnhandledException, _
                                      AddressOf UnhandledExceptionHandler

This leaves out one large class of .NET applications: web apps. I've experimented with this, and I do not believe it is desirable to handle web exceptions using the exact same classes that you use to handle Console and WinForms exceptions. They have different needs. I do have a variant of this class I use in server-side Web Services and ASP.NET applications, but it's significantly different. This article will only cover exception handling techniques appropriate for Console or Windows Forms executables.

The other thing we need to be aware of is multi-threaded applications. The default exception handling only covers the main application thread. If you are spawning additional threads in your application, you must remember to set up the unhandled exception handler for each new thread you spawn.

Using UnhandledExceptionManager

Setting up the unhandled exception handler is very easy, but it must be done as soon as possible at application startup by calling UnhandledExceptionManager.AddHandler()

For Windows Forms applications:

    Public Sub Main()
        Dim frm As New Form1
    End Sub

For Console applications:

    Sub Main()
        Console.WriteLine("Hello World!")
    End Sub

This is a "set it and forget it" operation. Once you've hooked up the handler, everything else is automatic from this point on. The only difference between the two initialization routines is the single optional Boolean parameter blnConsoleApp. Unfortunately I couldn't determine any way to distinguish between a Console and a Windows Forms app at runtime; the distinction is important for reasons I'll cover later.

The UnhandledExceptionManager class can be explicitly configured at initialization time through its parameters, or it can be configured passively through ambient App.Config settings. The App.Config settings are all optional, but look like this (I chose all defaults):

  <add key="UnhandledExceptionManager/EmailTo" 
             value="" />
  <add key="UnhandledExceptionManager/ContactInfo" 
             value="Jeff Atwood at 123-555-1212" />
  <add key="UnhandledExceptionManager/IgnoreDebug" value="True" />
  <add key="UnhandledExceptionManager/SendEmail" value="True" />
  <add key="UnhandledExceptionManager/LogToFile" value="True" />
  <add key="UnhandledExceptionManager/LogToEventLog" value="False" />
  <add key="UnhandledExceptionManager/TakeScreenshot" value="True" />
  <add key="UnhandledExceptionManager/DisplayDialog" value="True" />
  <add key="UnhandledExceptionManager/EmailScreenshot" value="True" />
  <add key="UnhandledExceptionManager/KillAppOnException" value="True" />

The most important setting is DisplayDialog, which defaults to True. For a Windows Forms app, when an Unhandled Exception occurs, we generate a user-friendly error dialog based on the GUI design laid out by Alan Cooper in his book About Face: The Essentials of User Interface Design, in the chapter titled The End of Errors.

screenshot of unhandled exception UI in a winforms app

To protect the end user from "geek speak", the Exception dialog hides most of the detailed diagnostic information until the "More >>" button is clicked. The animated screenshot at the top of this article demonstrates the use of this button.

Of course in a console app, we can't throw up a traditional WinForms dialog, so we simply dump the text to the console, like so:

screenshot of unhandled exception UI in a console app

But the really cool thing about the UnhandledExceptionHandler class is that, in addition to putting a friendly UI 'face' on our exceptions, it also does a lot of things for us behind the scenes. First of all, it takes a screenshot of the exception and logs the exception to a text file. These files are stored in the same path as the executable. Note that, for Smart Client apps which have a remote URL for a path, these files are named with filesafe versions of the URL and stored in the root folder of the hard drive.

screenshot of files created in the bin folder

By default, UnhandledExceptionHandler bundles up the text log and the screenshot into an exception email. This information is emailed to the address(es) of your choice via the built in, native SMTP class SimpleMail, assuming you've configured it with a valid SMTP server address. The email contains:

  • User and Machine identification
  • Application information
  • Exception summary
  • Custom stack trace
  • .PNG desktop screenshot

screenshot of automatic exception email

As you can see, the screenshot that was captured to the .PNG file is attached directly to the email. The screenshot is taken immediately after the Unhandled Exception, but before any UI appears; this way we capture the "scene of the crime", and hopefully have some idea what the user was doing to trigger the exception (damn users!). This provides additional valuable information that sometimes isn't reflected in the stack trace.

Also note that the email from: address, pictured above, defaults to, a naming scheme I'm arrived at after a few years of standard email notifications; this way you know "who" mailed you (what application), and where it is coming from (what computer).

But wait-- there's more! I don't frequently enable this in my apps, but the code can also write the same detailed exception information to the Application Event Log, if you'd like to see them there.

screenshot of application event log

Two final observations on Unhandled Exceptions before we close our discussion.

  1. For some reason, using an Unhandled Exception Handler can block termination of your WinForms app. In other words, after the Unhandled Exception is processed, your application.. keeps running. I'm not clear exactly why this happens, and I'm not even sure if this is a desirable "feature", as you can get into some very strange execution states when the application partially fails, but keeps running. To control this, I added the UnhandledExceptionManager.KillAppOnException property, which defaults to True. Set it to taste, it works either way.
  2. Bear in mind that you cannot have exceptions in the Unhandled Exception Handler. This is a special case handler, the "handler of last resort", and exceptions in this code are just not supported-- they will cause the code to terminate with no warning whatsoever, as if you put in an arbitrary Return right smack dab in the middle of your function. Beware!

Using HandledExceptionManager

That pretty much covers Unhandled Exceptions, which is great, but.. what about exceptions that we want to handle? In other words, situations that we know can happen, and we want to specifically protect the user from-- without terminating our application? For that, I included HandledExceptionManager, which leverages the same UI. It's like a MessageBox specifically designed for exceptions, that supports an optional email notification.

screenshot of handled exception UI

The syntax is very similar to MessageBox, in fact:

Public Overloads Shared Function ShowDialog(ByVal strWhatHappened As String, _
        ByVal strHowUserAffected As String, _
        ByVal strWhatUserCanDo As String, _
        ByVal objException As System.Exception, _
        Optional ByVal Buttons As MessageBoxButtons = MessageBoxButtons.OK, _
        Optional ByVal Icon As MessageBoxIcon = MessageBoxIcon.Warning, _
        Optional ByVal DefaultButton _
                As UserErrorDefaultButton = UserErrorDefaultButton.Default) _
                As DialogResult

But it can also be called using an even simpler overloaded method.

Public Overloads Shared Function ShowDialog(ByVal strWhatHappened As String, _
        ByVal strHowUserAffected As String, _
        ByVal strWhatUserCanDo As String) As DialogResult
The sample solution includes an interactive demonstration of all the different parameters you can use to call the HandledExceptionManager.ShowDialog method.


I think that wraps it up. I've used these classes on a few different projects now with great results, and I hope they work well for you too. My last article was criticized for not being detailed enough, so I tried to go into greater depth for this one. That said, there are still a bunch of things in the source I either didn't have space to cover, or that didn't neatly fit within the scope of exception handling. There are many more details and comments in the source code provided at the top of the article, so check it out. And please don't hesitate to provide feedback, good or bad!


  • Tuesday, June 22, 2004 - Published.
  • Monday, August 16, 2004 - Updated demo code
    1. Added exception class to the titles of the exception emails; instead of just the generic "Unhandled Exception", you get "Unhandled Exception - System.IO.FileNotFoundException" and so forth
    2. Removed my email as the default destination for the demo emails (doh!)
    3. Converted labels to RichTextBoxes. We get clickable http: and mailto: support, and scroll bars when the text exceeds the available size. (Thanks elp?)
    4. Added support for outgoing SMTP authentication (thanks Chuck Peper)
    5. Removed embedded icon resources in favor of standard .NET icons available in the Drawing namespace (thanks Chuck Peper)
    6. Many other small improvements


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Web Developer
United States United States
My name is Jeff Atwood. I live in Berkeley, CA with my wife, two cats, and far more computers than I care to mention. My first computer was the Texas Instruments TI-99/4a. I've been a Microsoft Windows developer since 1992; primarily in VB. I am particularly interested in best practices and human factors in software development, as represented in my recommended developer reading list. I also have a coding and human factors related blog at

Comments and Discussions

GeneralQuestion about KillAppOnException Pinmemberginacresse8-Jan-08 17:12 
QuestionC# Conversion Available Pinmemberkjward29-Nov-07 7:46 
GeneralRe: C# Conversion Available PinmemberMember 38445253-Dec-07 10:50 
AnswerRe: C# Conversion Available Pinmembercrazy_turist10-Dec-07 22:30 
GeneralRe: C# Conversion Available Pinmemberxmmike8-Apr-08 11:30 
GeneralRe: C# Conversion Available PinmemberAvinash_Mauje9-Apr-08 0:53 
GeneralRe: C# Conversion Available Pinmemberxmmike9-Apr-08 6:43 
QuestionRe: C# Conversion Available Pinmemberpashleb17-Apr-08 10:23 
AnswerRe: C# Conversion Available PinmemberMember 312580316-Mar-09 8:41 
GeneralRe: C# Conversion Available PinmemberDeborah Blackwell17-Mar-09 9:17 
QuestionRe: C# Conversion Available PinmemberAKDM18-Mar-09 3:32 
GeneralRe: C# Conversion Available PinmemberMember 471399315-Apr-09 2:54 
GeneralRe: C# Conversion Available PinmemberMember 286454417-Dec-09 7:41 
AnswerRe: C# Conversion Available PinmemberElCaito17-Jan-10 16:01 
QuestionLicence? Pinmembersvefasz46u20ayf8-Nov-07 21:10 
AnswerRe: Licence? Pinmemberdwriter7112-Nov-07 3:02 
QuestionLegality? PinmemberMikie27-Sep-07 3:17 
AnswerRe: Legality? PinmemberMarkBrock8-Jun-08 17:46 
AnswerRe: Legality? PinmemberShane Story7-Oct-08 5:01 
GeneralTransparent Windows Pinmemberbrad-j10-Sep-07 6:54 
QuestionAny thoughts on dll projects? Pinmemberdarin higgins5-Sep-07 5:47 
QuestionIntegrating with existing project PinmemberRyn Bodde1-May-07 5:56 
GeneralLooking for VS2005 code PinmemberGlimmerMan26-Mar-07 6:28 
QuestionHow to retrofit a sub main into my existing app? PinmemberDrJaymz25-Feb-07 22:02 
AnswerRe: How to retrofit a sub main into my existing app? Pinmemberkwikkiwi1-May-07 9:06 
GeneralCapture a screenshot of the user's desktop Pinmemberbdsoko2-Feb-07 11:36 
GeneralRe: Capture a screenshot of the user's desktop PinmemberOliverKurowski12-Apr-07 22:48 
GeneralFixed to use in VB.NET 2005! PinmemberFlukes29-Oct-06 12:17 
GeneralRe: Fixed to use in VB.NET 2005! PinmemberCOK_Jwang20-Nov-06 7:45 
GeneralRe: Fixed to use in VB.NET 2005! Pinmemberjust a day job31-Jan-07 10:40 
GeneralIssue whoth threading.threadabortexception Pinmembersilvansaid20-Jul-06 6:34 
GeneralRe: Issue whoth threading.threadabortexception Pinmemberbjansson4-Jan-07 23:20 
GeneralRe: Issue whoth threading.threadabortexception Pinmemberbalazs_hideghety22-Mar-09 4:52 
Generalfor checking console app PinmemberBaiju Nagori5-Jul-06 11:10 
QuestionC# option? PinmemberLiamD13-Jun-06 22:07 
AnswerRe: C# option? PinmemberColin Angus Mackay13-Jun-06 22:50 
AnswerRe: C# option? Pinmemberajmastrean31-Jul-07 7:08 
GeneralProblem in framework V2.0 PinmemberbdSGIIMS12-Jun-06 6:37 
GeneralRe: Problem in framework V2.0 PinmemberBested12-Jun-06 23:04 
GeneralRe: Problem in framework V2.0 Pinmemberjan3z6-Sep-06 22:09 
AnswerRe: Problem in framework V2.0 23:05 
GeneralStrange charset in emails PinmemberJavier Gutierrez7-Jun-06 3:42 
GeneralRe: Strange charset in emails Pinmemberpieter c10-Jul-06 23:48 
GeneralRe: Strange charset in emails Pinmemberpieter c11-Jul-06 0:34 
GeneralHandledExceptionManager Pinmember[ICR]6-Mar-06 11:06 
QuestionLove it but also small issue and change Pinmembercwesty2-Mar-06 0:35 
GeneralTwo problems encountered PinmemberbdSGIIMS2-Feb-06 9:24 
GeneralRe: Two problems encountered PinmemberBugsBunny20046-Aug-07 13:04 
QuestionCan't get code to work PinmemberBradm7711-Jan-06 8:59 
GeneralSpiffy Pinmemberredfish3414-Dec-05 22:45 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.141015.1 | Last Updated 18 Aug 2004
Article Copyright 2004 by wumpus1
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid