Customize Default ASP.NET Exception Handling

asp:feature companion

LANGUAGES: VB .NET

TECHNOLOGIES: Exception Handling

Customize Default ASP.NET Exception Handling

ASP.NET has a default exception-handling system, but itain't pretty - unless you take the time to customize it.

By Don Kiely

Like pretty much every development environment in thehistory of computing, ASP.NET has a default exception handling system, which isunlikely to be acceptable for any production application. Suppose you have thiscode in a Page's Load event procedure:

Dim x As Integer = 44

Dim y As Integer = 31

Dim z As Double

Dim zi As Double

z = x / y

zi = x y

lblResult.Text = "When x is " & x.ToString _

   & " and y is" & y.ToString _

   & ", x / y is" & z.ToString _

   & ", and x yis " & zi.ToString & "."

Now suppose somehow the variable y in the previous code is0 instead of 31. Interestingly, the result of the floating-point divisionassigned to z is a special value of infinity, so the line z = x / y doesn'tthrow an error. But the line zi = x / y does throw an exception, which is nothandled in this procedure or anywhere else in the application. So the ASP.NETdefault behavior kicks in.

What the user sees depends on where the application isrunning. If the browser is running on the same machine as the application, whichis a common scenario during development, the user sees Figure 1. In many cases,this provides enough information to find what went wrong so you can fix theproblem.

Figure 1. With the defaultconfiguration out of the box, a user running an application with an unhandledexception gets a fair bit of information about what caused the problem,including a stack trace.

If the browser is running on a remote machine, such aswhen an application goes into testing or production and real users are hittingthe server, the same error will present the user with Figure 2.

Figure 2. Still using the defaultASP.NET configuration, a remote user will get this less-than-useful page.Unless you hate your users, decide right now that no one will ever see this inan application of yours.

I don't know about you, but I'll work awfully hard to keepmy users from seeing a message that seems to imply that whatever idiot set upthis application didn't configure it right. That's not the message I want toconvey, no matter how wrong (or right) it might be!

This default behavior is affected by the customErrorselement in web.config. The default behavior is equivalent to this line in the section of web.config:

This tells ASP.NET that when an unhandled exceptionoccurs, it should present remote users with the "bad configuration" page, andlocal users should get the detailed debugging information. Because this is thedefault, the lack of a element - or even no web.configfile at all - gives you this behavior.

The mode attribute has two other settings: On and Off. On simply means all users get thesomewhat useless "bad configuration" page; Offmeans all users get the detailed debugging page. (In the sampleapplication, set Default.aspx as the start page and see the instructions therefor modifying web.config to explore these behaviors.)

You can customize this default behavior further by usingthe defaultRedirect attribute of :

mode="On" />   Now when an unhandled exception occurs, the user ispresented with whatever content you provide in the static GenericError.htmpage, such as the one I've set up in Figure 3. Note that the mode attributeaffects behavior in the same way described above, so On means every user seesGenericError.htm, Off means no one does, and RemoteOnly means only remote userssee it while local users get debugging information.  
Figure 3. By redirecting users to acustom error page, you can soften the blow a bit when something goes wrong.   This is a bit better because it presents the user withsomething consistent with the visual design of the application. You can controlwhat the page says, and everyone feels better (hopefully).   Notice in the address bar in Figure 3 that ASP.NETincludes a querystring parameter, aspxerrorpath, which includes the path of theoffending aspx page. If you want, you could incorporate this in the error pageusing an aspx page instead of static HTML:     This results in the error pageshown in Figure 4, which includes a new middle paragraph.  
Figure 4. Because ASP.NET includesthe aspxerrorpath querystring attribute, you can include information about whichpage caused the error.   This simple example uses inline code to display the querystring information. You can, of course, write whatever complex code you need topresent whatever makes sense in a particular application:   <% If Not Request.QueryString("aspxerrorpath") IsNothing %>        In case you didn'tknow, the error arose from<%=HttpUtility.HtmlEncode(Request.QueryString("aspxerrorpath"))%>   .     

<% End If %>

Another configuration option with isto include different error pages, either static HTML or dynamic aspx pages, inresponse to different kinds of errors.

In the element below, HTTP errors 404(page not found) and 500 (internal server error) are redirected to their owncustom error pages (Error404.htm and Error500.htm in this case), while allother errors still go to GenericError.aspx.

One thing to be careful of here is that HTTP status code500 acts as a sort of catch-all for most run-time code errors. So in the sampleapplication, the divide-by-zero error is redirected to Error500.htm rather thanGenericError.aspx.

With this technique, you also can define custom errors inIIS and hook into them with custom error pages. You aren't limited to thepredefined HTTP errors.

Don Kiely is seniorinformation architect for Information Insights, a business and technologyconsultancy in Fairbanks, Alaska. E-mail him at mailto:[email protected].