The CORRECT Way to Code a Custom Exception Class

There is a lot of advice out there on how to go about building your own custom exception classes.  A lot of these sources are at least partially correct. Some are totally wrong.  Some even advocate abandoning the base System.Exception class altogether, but that’s throwing the baby out with the bathwater, in my opinion.  None that I've seen show how to serialize/deserialize your custom exception class should it have additional data in it's subclass. It’s enough to make one despair of ever finding the “right” way to build an exception class. 

A lot of the confusion around exceptions comes about if you’ve ever actually tried to serialize an exception using an Xml-based serializer.  You are testing the code you write, correct? When attempting to serialize your nice new exception class with something like XmlSerializer, the serializer will simply choke, stating that it can’t serialize any class that has an IDictionary member.  And System.Exception has an IDictionary in it.  Yet every piece of literature coming out of Microsoft says that we should build custom exceptions (sub-typed from Exception, and not ApplicationException) and mark them as [Serializable].  What gives?  Well, there are more serializers in the world than just the XML-based serializers, and that’s when it’s important to serialize exceptions.  The System.Runtime.Serialization.Formatters.Binary.BinaryFormatter, for example, serializes exceptions just fine.

So, how do you derive from Exception correctly, particularly if you’ve got additional information in your custom exception class?  I thought you’d never ask.

     [Serializable]
    public class AuthorizationRequiredException : Exception
    {
        public string ResourceReferenceProperty { get; set; }
 
        public AuthorizationRequiredException()
        {
        }
 
        public AuthorizationRequiredException(string message)
            : base(message)
        {
        }
 
        public AuthorizationRequiredException(string message, Exception inner)
            : base(message, inner)
        {
        }
 
        protected AuthorizationRequiredException(SerializationInfo info, StreamingContext context)
            : base(info, context)
        {
            ResourceReferenceProperty = info.GetString("ResourceReferenceProperty");
        }
 
        [SecurityPermission(SecurityAction.Demand, SerializationFormatter = true)]
        public override void GetObjectData(SerializationInfo info, StreamingContext context)
        {
            if (info == null)
                throw new ArgumentNullException("info");
            info.AddValue("ResourceReferenceProperty", ResourceReferenceProperty);
            base.GetObjectData(info, context);
        }
 
    }

   And here are the tests that drive it to completion (updated to show better testing methods):

     [TestClass]
    public class AuthorizationRequiredExceptionTests
    {
        [TestMethod]
        public void AuthorizationRequiredException_default_ctor()
        {
            // Arrange
            const string expectedMessage = "Exception of type 'MyApp.Exceptions.AuthorizationRequiredException' was thrown.";
 
            // Act
            var sut = new AuthorizationRequiredException();
 
            // Assert
            Assert.IsNull(sut.ResourceReferenceProperty);
            Assert.IsNull(sut.InnerException);
            Assert.AreEqual(expectedMessage, sut.Message);
        }
 
        [TestMethod]
        public void AuthorizationRequiredException_ctor_string()
        {
            // Arrange
            const string expectedMessage = "message";
 
            // Act
            var sut = new AuthorizationRequiredException(expectedMessage);
 
            // Assert
            Assert.IsNull(sut.ResourceReferenceProperty);
            Assert.IsNull(sut.InnerException);
            Assert.AreEqual(expectedMessage, sut.Message);
        }
 
        [TestMethod]
        public void AuthorizationRequiredException_ctor_string_ex()
        {
            // Arrange
            const string expectedMessage = "message";
            var innerEx = new Exception("foo");
 
            // Act
            var sut = new AuthorizationRequiredException(expectedMessage, innerEx);
 
            // Assert
            Assert.IsNull(sut.ResourceReferenceProperty);
            Assert.AreEqual(innerEx, sut.InnerException);
            Assert.AreEqual(expectedMessage, sut.Message);
        }
 
        [TestMethod]
        public void AuthorizationRequiredException_serialization_deserialization_test()
        {
            // Arrange
            var innerEx = new Exception("foo");
            var originalException = new AuthorizationRequiredException("message", innerEx) { ResourceReferenceProperty = "MyReferenceProperty" };
            var buffer = new byte[4096];
            var ms = new MemoryStream(buffer);
            var ms2 = new MemoryStream(buffer);
            var formatter = new BinaryFormatter();
 
            // Act
            formatter.Serialize(ms, originalException);
            var deserializedException = (AuthorizationRequiredException)formatter.Deserialize(ms2);
 
            // Assert
            Assert.AreEqual(originalException.ResourceReferenceProperty, deserializedException.ResourceReferenceProperty);
            Assert.AreEqual(originalException.InnerException.Message, deserializedException.InnerException.Message);
            Assert.AreEqual(originalException.Message, deserializedException.Message);
        }
 
        [TestMethod]
        [ExpectedException(typeof(ArgumentNullException))]
        public void AuthorizationRequiredException_GetObjectData_throws_exception_when_info_null()
        {
            // Arrange
            var sut = new AuthorizationRequiredException("message") { ResourceReferenceProperty = "MyReferenceProperty" };
 
            // Act
            // ReSharper disable AssignNullToNotNullAttribute
            sut.GetObjectData(null, new StreamingContext());
            // ReSharper restore AssignNullToNotNullAttribute
 
            // Assert
            // [ExpectedException(typeof(ArgumentNullException))]
        }
    }

If you use this code as a template for creating your custom exceptions, you won’t go too far wrong, I think.

As far as XML-based serializers goes, I hope that the Base Class Library team will take some time and just fix the "chokes on IDictionary" issue.  Frankly, it's quite embarrassing.