Creating Custom Exceptions in .NET - Real World Scenarios

Here's an article I've written about custom exceptions. It's not only about custom exceptions per se, it's also about using them when you have interfaces.

Enjoy

Table of Contents

• Introduction
• Our first custom exception
• Our final custom exception (properly serialized, of course)
• Throwing it
• Catching it
• Brief recap
• Conclusion

Introduction

The other day I was creating and documenting one of my library and a situation came by where I needed a custom exception. It was not clear at first but it became evident when I started the implementation of my interfaces. Why at the implementation stage? Let me show you a case where a custom exception would make sense, and why you would discover it at implementation time. Let's suppose we have an interface and two subclasses like:

Let's say IReader is a general interface to read some data from a file of an unknown format. You're designing your interface which has only one method:

public interface IReader
{
    void Load(string uri);
}

Then, because you're a conscientious programmer, you decide to document the interface (for the subclasses to know when they should throw an exception while implementing the interface methods):

public interface IReader
{
    /// <summary>
    /// Loads and parse a file
    /// </summary>
    /// <exception name="ArgumentNullException">uri is null</exception>
    /// <exception name="ArgumentException">uri is not a valid uri</exception>
    /// <exception name="FileNotFoundException">file at uri is not found</exception>
    void Load(string uri);
}

You would think that's pretty it. But when imlementing the XmlReader subclass, a problem become evident. Loading an XML file can throw the following exceptions: SecurityException, FileNotFoundException or a XmlException whether or not the client have the rigths to make the loading call, whether or not the XML file exists or finally if the file is not a valid XML file. We can't let the Load method throw these because they're not related to any of the others implementations or more importantly to the interface. Remember, the client will most likely have an instance of the IReader interface so he won't know anthing about the way he's reading the file. So how can he do efficient exception handling?

A general rule is to avoid creating custom exceptions when we can use a system one. Another rule is to keep the custom exceptions count to a minimum. I recently learned those rules when I was having a talk on StackOverflow regarding the documentation of interfaces, which got me thinking of writing this article. Anyways back to our case, following those rules I think it's a good idea to create a custom exception to cover everything that could happen on the subclasses in a homogeneous way.

Instead of creating a ReaderSecurityException and a ReaderFileNotFoundException and such, let's just create a single exception ReaderException. The ReaderException will have a public member Reason to further explain the cause of the exception, eliminating the need for multiple exceptions.

Our first custom exception

public enum eReason
{
    CouldNotAccess,
    ParseError
    // [...]
}

public class ReaderException
{
    public eReason Reason { get; private set; }
}

Before completing the implementation of our exception, let's update the IReader interface documentation. We can now be generic enough to cover all implementations thanks to our custom exception:

public interface IReader
{
    /// <summary>
    /// Loads and parse a file
    /// </summary>
    /// <exception name="ArgumentNullException">uri is null</exception>
    /// <exception name="ArgumentException">uri is not a valid uri</exception>
    /// <exception name="FileNotFoundException">file at uri is not found</exception>
    /// <exception name="ReaderException">
    ///     <para>-or-</para>
    ///     the content of the file represented by uri is in an unknown format
    ///     <para>-or-</para>
    ///     the access to the file represented by uri is restricted
    /// </exception>
    void Load(string uri);
}

As you can see, we added an exception that can be thrown for two possible reasons. For example, when the file is not in an XML format, the XmlReader would throw a ReaderException with the reason being: Reason.ParseError. Alternatively, when the FlatFileReader encounter an invalid flat file format, it would throw the same. Pretty cool. Now let's see the proper way to create a custom exception.

Our final custom exception (properly serialized, of course)

I'm skipping the "how I did it" part on this one because I think the code is self explaining (the last constructor and the GetObjectData method are for serialization, you should serialize your extra members if you add any). Also I think you should focus your efforts on deciding whether or not to use a custom exception. A quick note however, never derive your custom exception from ApplicationException (see recap).

public enum eReason
{
    CouldNotAccess,
    ParseError
    // [...]
}

[Serializable]
public class ReaderException : Exception, ISerializable
{
    public eReason Reason { get; private set; }

    private ReaderException()
    {
    }

    public ReaderException(eReason reason)
            : base()
    {
        Reason = reason;
    }

    public ReaderException(eReason reason, string message)
            : base(message)
    {
        Reason = reason;
    }

    public ReaderException(eReason reason, string message, Exception inner)
            : base(message, inner)
    {
        Reason = reason;
    }

    protected ReaderException(SerializationInfo info, StreamingContext context)
    {
        if (info == null)
                throw new System.ArgumentNullException("info");

        Reason = (eReason)info.GetValue("Reason", typeof(eReason));
    }

    [SecurityPermission(SecurityAction.LinkDemand, Flags = SecurityPermissionFlag.SerializationFormatter)]
    void ISerializable.GetObjectData(SerializationInfo info, StreamingContext context)
    {
        if (info == null)
                throw new System.ArgumentNullException("info");

        info.AddValue("Reason", Reason, typeof(eReason));
    }
}

Throwing it

According to our examples above, we can now throw our custom exception like this in our XmlReader::Load method:

// [...]
try
{
    XDocument file = XDocument.Load(uri);
    // [...]
}
catch (SecurityException e)
{
    throw new ReaderException(eReason.CouldNotAccess, "Some pertinent comment", e);
}
catch (XmlException e)
{
    throw new ReaderException(eReason.ParseError, "Some pertinent comment", e);
}
// [...]

Catching it

Catching this exception is no different than any other exception, except that you now have your Reason property you can refer to. So according to the interface we should catch like this:

private void Test(IReader reader, string file)
{
    try
    {
        // We're assuming reader is not null
        reader.Load(file);
    }
    catch(ArgumentNullException e)
    {
        // [...]
    }
    catch(ArgumentException e)
    {
        // [...]
    }
    catch(FileNotFoundException e)
    {
        // [...]
    }
    catch(ReaderException e)
    {
        eReason r = e.Reason;
        // [...]
    }
}

That's it folks, we've made the loop! Hope you followed... if not, drop me a comment. But read on my summary and my conclusion to wrap things up.

Brief recap

• Always try to use already available exceptions (ArgumentException, ArgumentNullException, InvalidOperationException, ArgumentOutOfRangeException, etc)
• Never derive your exception from ApplicationException like I've seen it to much on other websites
• Keep your custom exceptions count to a minimum
• Use my template as a starting template :)
• To back my claims on all of the above, refer to Best Practices for Handling Exceptions on msdn.

Conclusion

I think the article could have been much shorter. But I tried to elaborate a case to show you where and why it might be pertinent to create a custom exception. I didn't wanted to give you the code to properly create a custom exception right away.

I'm putting time and effort on this blog and having you here is my reward. Make me feel better and better everyday by spreading the love with the buttons below! Also, don't hesitate to leave a comment. Thanks for reading!

See ya