Basic Error Reporting Tutorial

This tutorial aims to teach you how to use the error reporting functionality found in the DigitallyCreated.Utilities.ErrorReporting assembly. It assumes you know C# and understand basic concepts in ASP.NET such as Global.asax and Web.Config.

DigitallyCreated contains some simple error reporting code that allows you to easily catch exceptions and email them to a specific email address in a pretty, easily readable format:

DCU Error Reporting.gif

It's great for when you need a quick and easy way of getting notified when something goes wrong with your application/website. In this tutorial we will focus on using Error Reporter in an ASP.NET web application, but it would be possible to use Error Reporting in a desktop .NET application as well.

The Error Reporting doesn't just take exceptions as input, it also is able to take any object and email that. In addition, it will use reflection to break the object down recursively and will effectively output a deep object dump for the object:

DCU Error Reporting with POCOs.gif

Error Reporting comes with default type renderers (ITypeRenderer; a type of object that is able to render a specific type, usually a basic type like a string, int, IDictionary, etc) and detail providers (IDetailProvider; a type of object that is able to break down an object into subobjects, for example, a Person object down into a string (first name), another string (last name), and an int (age)). However, you are free to add your own or replace the originals with your own. However, this is not covered in this tutorial.

Hooking into Global.asax

Global.asax (or more specifically, the Application subclass you define in there) enables you to be notified when an unhandled exception occurs in your web application. So we will write some code in this class to deliver these unhandled exceptions to Error Reporting so it can email them.

Firstly, you'll need an instance of the {ErrorReporter} class, so we'll create one in a static variable (it's thread-safe, so we don't need more than one instance) and initialise it in the Application class's static constructor:

/// <summary>
/// The Error Reporter
/// </summary>
public static readonly ErrorReporter ErrorReporter;

/// <summary>
/// Static constructor
/// </summary>
static MyApplication()
{
    ErrorReporter = new ErrorReporter();
    ErrorReporter.IgnoreRules.Add(e => e is HttpException && ((HttpException)e).GetHttpCode() == 404);
}

You'll notice that we're adding an "Ignore Rule" to ErrorReporter right after creating it. Ignore Rules allow you to tell error reporter to drop particular errors that are handed to it. The rule we've added drops the HttpExceptions that ASP.NET throws when a 404 (file not found) exception occurs. They happen very regularly on a website, and you don't really care about them, so this ignore rule just suppresses them.

We now need to wire up the delivery of errors to ErrorReporter. We will do this by implementing the Application_Error method in your Application class in Global.asax. This method is called when unhandled exceptions occur.

/// <summary>
/// Run when an unhandled exception occurs
/// </summary>
/// <param name="sender"></param>
/// <param name="args"></param>
protected void Application_Error(object sender, EventArgs args)
{
    IDictionary<string, object> extraDetails = new Dictionary<string, object>();
    extraDetails.Add("Requested URL", HttpContext.Current.Request.Url.ToString());

    ErrorReporter.ReportError(Server.GetLastError(), ErrorSeverity.Fatal, "Unhandled Exception", 
        "Unhandled Exception. Application_Error in Global.asax triggered.", extraDetails);
}

What we do in that method is make a call to ReportError on ErrorReporter, pass in the exception that occurred as the error object (the first parameter), set the error's severity to Fatal (the second parameter), set the title of the error to "Unhandled Exception" (the third parameter; see the first error email example picture to see where that's used), set the programmer's message to "Unhandled Exception. Application_Error in Global.asax triggered." (the fourth parameter; see the email example again), and pass in some "extra details" (fifth parameter). These extra details are simply extra things we'd like included in the email. In this case we're adding in the requested URL that caused the exception (see the above error email example picture and see how this is included). You aren't restricted to just using a string for an extra detail, you can use any object just like you can for the error object.

There are other, shorter, overloads of ReportError that you may want to use, but I'll let you look at the class's code documentation to find what those are (basically just cut down versions of the method used above)

Configure Error Reporting

Now that we've got errors being delivered to the ErrorReporter class, we need to configure how it emails those errors. We do this in our web.config file.

Firstly, we add the errorReporting section to our web.config file. We declare it as a section under the configuration\configSections tag, then use it under the configuration tag:

<configuration>
    <configSections>
        <section name="errorReporting" 
                 type="DigitallyCreated.Utilities.ErrorReporting.Configuration.ErrorReportingConfigurationSection, DigitallyCreated.Utilities.ErrorReporting"
                 />
        ... your other config section declarations here ....
    </configSections>
 
    <errorReporting enabled="true">
        <sendFrom address="website@mywebsite.com" displayName="MyWebsite Error Reporting" />
        <sendTo address="developers@mywebsite.com" displayName="Developers" />
    </errorReporting>

    ... your other config sections here ...
</configuration>

As you can see, the errorReporting section allows you to configure the email address to send from, the address to send to and whether error reporting is off or on. Disabling error reporting is useful when you're developing since otherwise every crash gets emailed to you!

Error Reporting will use the default SMTP server you set up for .NET in the system.net/mailSettings/smtp section. Here's an example:

<configuration>
    ...
    
    <system.net>
        <mailSettings>
            <smtp deliveryMethod="Network">
                <network defaultCredentials="true" host="mail.mywebsite.com" port="25" />
            </smtp>
        </mailSettings>
    </system.net>
</configuration>

And that's it! Now, any error that causes your global.asax Application class's Application_Error method to be called will be emailed to the email address you configured!

Last edited Mar 17, 2010 at 3:01 PM by dchambers, version 4

Comments

No comments yet.