CodeIdol - Thinking about C# Cookbook, 2nd Edition - Exception Handling

None of the built-in exceptions in the .NET Framework provide the implementation details that you require for an exception that you need to throw. You need to create your own exception class that operates seamlessly with your application, as well as other applications. Whenever an application receives this new exception, it can inform the user that a specific error occurred in a specific component. This report will greatly reduce the time required to debug the problem.

Solution

Create your own exception class. To illustrate, let's create a custom exception class, RemoteComponentException, that will inform a client application that an error has occurred in a remote server assembly.

Discussion

The exception hierarchy starts with the Exception class; from this are derived two classes: ApplicationException and SystemException. The SystemException class and any classes derived from it are reserved for the developers of the FCL. Most of the common exceptions, such as the NullReferenceException or the OverflowException, are derived from SystemException. The FCL developers created the ApplicationException class for other developers using the .NET languages to derive their own exceptions from. This partitioning allows for a clear distinction between user-defined exceptions and the built-in system exceptions. However, Microsoft now recommends deriving directly from Exception, rather than ApplicationException. Nothing actively prevents you from deriving a class from either SystemException or ApplicationException. But it is better to be consistent and use the convention of always deriving from the Exception class for userdefined exceptions.

You should follow the naming convention for exceptions when determining the name of your exception. The convention is very simple. Whatever you decide on for the exception's name, add the word Exception to the end of the name (e.g., use UnknownException as the exception name instead of just Unknown). Every user-defined exception should include at least three constructors, described next. This is not a requirement, but it makes your exception classes operate similarly to every other exception class in the FCL and minimizes the learning curve for other developers using your new exception. These three constructors are:

If this exception will be caught in unmanaged code, such as a COM object, you can also set the hrESULT value for this exception. An exception caught in unmanaged code becomes an hrESULT value. If the exception does not alter the hrESULT value, it defaults to the hrESULT of the base class exception, which, in the case of a user-defined exception object that inherits from ApplicationException, is COR_E_ APPLICATION (0x80131600). To change the default hrESULT value, simply set the value of this field in the constructor. The following code demonstrates this technique:

Now the hresult that the COM object will see is the value 0x80040321. See Table 7-2 in Recipe 7.8 for more information on the mapping of hrESULT values to their equivalent managed exception classes.

It is usually a good idea to override the Message property in order to incorporate any new fields into the exception's message text. Always remember to include the base class's message text along with any additional text you add to this property.

Fields and their accessors should be created to hold data specific to the exception. Since this exception will be thrown as a result of an error that occurs in a remote server assembly, you will add a private field to contain the name of the server or service. In addition, you will add a public read-only property to access this field. Since you're adding this new field, you should add two constructors that accept an extra parameter used to set the value of the serverName field.

If necessary, override any base class members whose behavior is inherited by the custom exception class. For example, since you have added a new field, you need to determine whether it will need to be added to the default contents of the Message field for this exception. If it does, you must override the Message property.

Notice that the Message property in the base class is displayed on the first line and your additional text is displayed on the next line. This organization takes into account that a user might modify the message that will appear in the Message property by using one of the overloaded constructors that takes a message string as a parameter.

In certain cases (such as remoting), your exception object should be serializable and deserializable. This involves performing the following two additional steps:

Add the Serializable attribute to the class definition. This attribute specifies that this class can be serialized or deserialized. A SerializationException is thrown if this attribute does not exist on this class and an attempt is made to serialize this class.
The class should implement the ISerializable interface if you want control over how serialization and deserialization are performed, and it should provide an implementation for its single member, GetObjectData. Here you implement it because the base class implements it, which means that you have no choice but to reimplement it if you want the fields you added (e.g., serverName) to get serialized.

In addition, a new overridden constructor is needed that accepts information to deserialize this object:

Even though it is not required, you should make all user-defined exception classes serializable and deserializable. That way, the exceptions can be propagated properly over remoting and appdomain boundaries.

At this point, the RemoteComponentException class contains everything you need for a complete user-defined exception class. You could stop at this point, but let's continue a bit farther and override some default functionality that deals with the hash code, equality, and inequality.

Overriding the GetHashCode method

Since you have overridden the Equals method, you should override the GetHashCode method, which overrides the hash code generation algorithm:

Overriding the == and != operators

When overriding the Equals method, both the == and != operators should be overloaded as well. Notice that both operators ultimately use the Equals method to determine equality. Therefore, they are simple to write.

As a final note, it is generally a good idea to place all user-defined exceptions in a separate assembly, which allows for easier reuse of these exceptions in other applications and, more importantly, allows other application domains and remotely executing code to both throw and handle these exceptions correctly no matter where they are thrown. The assembly that holds these exceptions should be signed with a strong name and added to the Global Assembly Cache (GAC), so that any code that uses or handles these exceptions can find the assembly that defines them. See Recipe 17.10 for more information on how to do this.

If you are sure that the exceptions being defined won't ever be thrown or handled outside of your assembly, then you can leave the exception definitions there. But if for some reason an exception that you throw finds its way out of your assembly, the code that ultimately catches it will not be able to resolve it.

The complete source code for the RemoteComponentException class is shown in Example 7-4.

Example 7-4. RemoteComponentException class

using System;
using System.IO;
using System.Runtime.Serialization;
using System.Runtime.Serialization.Formatters.Binary;

[SerializableAttribute]
public class RemoteComponentException :
  Exception, ISerializable
{
    // New exception field
    private string serverName = "";

    // Normal exception ctors
    public RemoteComponentException( ) : base( )
    {
    }

    public RemoteComponentException(string message) : base(message)
    {
    }

    public RemoteComponentException(string message,
      Exception innerException)
        : base(message, innerException)
    {
    }

    // Exception ctors that accept the new ServerName parameter
    public RemoteComponentException(string message,
      string serverName) : base(message)
    {
        this.serverName = serverName;
    }

    public RemoteComponentException(string message,
      Exception innerException, string serverName)
            : base(message, innerException)
    {
        this.serverName = serverName;
    }

    // Serialization ctor
    public RemoteComponentException(SerializationInfo exceptionInfo,
            StreamingContext exceptionContext)
            : base(exceptionInfo, exceptionContext)
    {
        this.serverName = exceptionInfo.GetString("ServerName");
    }

    // Read-only property
    public string ServerName
    {
        get{return (serverName.Trim( ));}
    }

    public override string Message
    {
        get
        {
            if (this.ServerName.Length == 0)
                return (base.Message + Environment.NewLine +
                        "An unnamed server has encountered an error.");
            else
                return (base.Message + Environment.NewLine +
                        "The server " + this.ServerName +
                        " has encountered an error.");
        }
    }

    // Overridden methods
    // ToString method
    public override string ToString( )
    {
        string errorString = "An error has occured in a server " +
            "component of this client.";
        errorString += Environment.NewLine + "Server Name: " +
          this.ServerName;
        if (this.InnerException == null)
        {
            errorString += Environment.NewLine +
                "Server component failed to provide an " +
                "underlying exception!";
        }
        else
        {
            string indent = "\t";
            Exception ie = this;
            while(ie.InnerException != null)
            {
                ie = ie.InnerException;
                errorString += Environment.NewLine + indent +
                  "inner exception type thrown by server component: " +
                  ie.GetType( ).Name.ToString( );
                errorString += Environment.NewLine + indent + "Message: "
                  + ie.Message;
                errorString += Environment.NewLine + indent +
                  "StackTrace: " + ie.StackTrace;

                indent += "\t";
            }
        }
        errorString += Environment.NewLine + "StackTrace of client " +
                       "component: " + this.StackTrace;
        return (errorString);
    }

    // Call base.ToString method.
    public string ToBaseString( )
    {
        return (base.ToString( ));
    }

    // GetHashCode
    public override int GetHashCode( )
    {
        return (ServerName.GetHashCode( ));
    }

    // Equals
    public override bool Equals(object obj)
    {
        bool isEqual = false;
        if (obj == null || (this.GetType( ) != obj.GetType( )))
        {
            isEqual = false;
        }
        else
        {
            RemoteComponentException se = (RemoteComponentException)obj;
            if ((this.ServerName.Length == 0)
              && (se.ServerName.Length == 0))
                isEqual = false;
            else
                isEqual = (this.ServerName == se.ServerName);
        }

        return (isEqual);
    }

    // == operator
    public static bool operator ==(RemoteComponentException v1,
        RemoteComponentException v2)
    {
        return (v1.Equals(v2));
    }

    // != operator
    public static bool operator !=(RemoteComponentException v1,
      RemoteComponentException v2)
    {
        return (!(v1 == v2));
    }

    // Used during serialization to capture information about extra fields
    public override void GetObjectData(SerializationInfo exceptionInfo,
                                       StreamingContext exceptionContext)
    {
        base.GetObjectData(exceptionInfo, exceptionContext);
        exceptionInfo.AddValue("ServerName", this.ServerName);
    }
}

Example 7-5. Testing the RemoteComponentException class

public void TestSpecializedException( )
{
    // Generic inner exception used to test the
    // RemoteComponentException's inner exception.
    Exception inner = new Exception("The inner Exception");

    // Test each ctor.
    Console.WriteLine(Environment.NewLine + Environment.NewLine +
      "TEST EACH CTOR");
    RemoteComponentException se1 = new RemoteComponentException ( );
    RemoteComponentException se2 =
      new RemoteComponentException ("A Test Message for se2");
    RemoteComponentException se3 =
      new RemoteComponentException ("A Test Message for se3", inner);
    RemoteComponentException se4 =
      new RemoteComponentException ("A Test Message for se4",
                                     "MyServer");
    RemoteComponentException se5 =
      new RemoteComponentException ("A Test Message for se5", inner,
                                      "MyServer");

    // Test new ServerName property.
    Console.WriteLine(Environment.NewLine +
      "TEST NEW SERVERNAME PROPERTY");
    Console.WriteLine("se1.ServerName == " + se1.ServerName);
    Console.WriteLine("se2.ServerName == " + se2.ServerName);
    Console.WriteLine("se3.ServerName == " + se3.ServerName);
    Console.WriteLine("se4.ServerName == " + se4.ServerName);
    Console.WriteLine("se5.ServerName == " + se5.ServerName);

    // Test overridden Message property.
    Console.WriteLine(Environment.NewLine +
      "TEST -OVERRIDDEN- MESSAGE PROPERTY");
    Console.WriteLine("se1.Message == " + se1.Message);
    Console.WriteLine("se2.Message == " + se2.Message);
    Console.WriteLine("se3.Message == " + se3.Message);
    Console.WriteLine("se4.Message == " + se4.Message);
    Console.WriteLine("se5.Message == " + se5.Message);

    // Test -overridden- ToString method.
    Console.WriteLine(Environment.NewLine +
      "TEST -OVERRIDDEN- TOSTRING METHOD");
    Console.WriteLine("se1.ToString( ) == " + se1.ToString( ));
    Console.WriteLine("se2.ToString( ) == " + se2.ToString( ));
    Console.WriteLine("se3.ToString( ) == " + se3.ToString( ));
    Console.WriteLine("se4.ToString( ) == " + se4.ToString( ));
    Console.WriteLine("se5.ToString( ) == " + se5.ToString( ));

    // Test ToBaseString method.
    Console.WriteLine(Environment.NewLine +
      "TEST TOBASESTRING METHOD");
    Console.WriteLine("se1.ToBaseString( ) == " + se1.ToBaseString( ));
    Console.WriteLine("se2.ToBaseString( ) == " + se2.ToBaseString( ));
    Console.WriteLine("se3.ToBaseString( ) == " + se3.ToBaseString( ));
    Console.WriteLine("se4.ToBaseString( ) == " + se4.ToBaseString( ));
    Console.WriteLine("se5.ToBaseString( ) == " + se5.ToBaseString( ));

    // Test -overridden- == operator.
    Console.WriteLine(Environment.NewLine +
      "TEST -OVERRIDDEN- == OPERATOR");
    Console.WriteLine("se1 == se1 == " + (se1 == se1));
    Console.WriteLine("se2 == se1 == " + (se2 == se1));
    Console.WriteLine("se3 == se1 == " + (se3 == se1));
    Console.WriteLine("se4 == se1 == " + (se4 == se1));
    Console.WriteLine("se5 == se1 == " + (se5 == se1));
    Console.WriteLine("se5 == se4 == " + (se5 == se4));

    // Test -overridden- != operator.
    Console.WriteLine(Environment.NewLine +
      "TEST -OVERRIDDEN- != OPERATOR");
    Console.WriteLine("se1 != se1 == " + (se1 != se1));
    Console.WriteLine("se2 != se1 == " + (se2 != se1));
    Console.WriteLine("se3 != se1 == " + (se3 != se1));
    Console.WriteLine("se4 != se1 == " + (se4 != se1));
    Console.WriteLine("se5 != se1 == " + (se5 != se1));
    Console.WriteLine("se5 != se4 == " + (se5 != se4));

    // Test -overridden- GetBaseException method.
    Console.WriteLine(Environment.NewLine +
      "TEST -OVERRIDDEN- GETBASEEXCEPTION METHOD");
    Console.WriteLine("se1.GetBaseException( ) == " + se1.GetBaseException( ));
    Console.WriteLine("se2.GetBaseException( ) == " + se2.GetBaseException( ));
    Console.WriteLine("se3.GetBaseException( ) == " + se3.GetBaseException( ));
    Console.WriteLine("se4.GetBaseException( ) == " + se4.GetBaseException( ));
    Console.WriteLine("se5.GetBaseException( ) == " + se5.GetBaseException( ));

    // Test -overridden- GetHashCode method.
    Console.WriteLine(Environment.NewLine +
      "TEST -OVERRIDDEN- GETHASHCODE METHOD");
    Console.WriteLine("se1.GetHashCode( ) == " + se1.GetHashCode( ));
    Console.WriteLine("se2.GetHashCode( ) == " + se2.GetHashCode( ));
    Console.WriteLine("se3.GetHashCode( ) == " + se3.GetHashCode( ));
    Console.WriteLine("se4.GetHashCode( ) == " + se4.GetHashCode( ));
    Console.WriteLine("se5.GetHashCode( ) == " + se5.GetHashCode( ));

    // Test serialization.
    Console.WriteLine(Environment.NewLine +
      "TEST SERIALIZATION/DESERIALIZATION");
    BinaryFormatter binaryWrite = new BinaryFormatter( );
    Stream ObjectFile = File.Create("se1.object");
    binaryWrite.Serialize(ObjectFile, se1);
    ObjectFile.Close( );
    ObjectFile = File.Create("se2.object");
    binaryWrite.Serialize(ObjectFile, se2);
    ObjectFile.Close( );
    ObjectFile = File.Create("se3.object");
    binaryWrite.Serialize(ObjectFile, se3);
    ObjectFile.Close( );
    ObjectFile = File.Create("se4.object");
    binaryWrite.Serialize(ObjectFile, se4);
    ObjectFile.Close( );
    ObjectFile = File.Create("se5.object");
    binaryWrite.Serialize(ObjectFile, se5);
    ObjectFile.Close( );

    BinaryFormatter binaryRead = new BinaryFormatter( );
    ObjectFile = File.OpenRead("se1.object");
    object Data = binaryRead.Deserialize(ObjectFile);
    Console.WriteLine("----------" + Environment.NewLine + Data);
    ObjectFile.Close( );
    ObjectFile = File.OpenRead("se2.object");
    Data = binaryRead.Deserialize(ObjectFile);
    Console.WriteLine("----------" + Environment.NewLine + Data);
    ObjectFile.Close( );
    ObjectFile = File.OpenRead("se3.object");
    Data = binaryRead.Deserialize(ObjectFile);
    Console.WriteLine("----------" + Environment.NewLine + Data);
    ObjectFile.Close( );
    ObjectFile = File.OpenRead("se4.object");
    Data = binaryRead.Deserialize(ObjectFile);
    Console.WriteLine("----------" + Environment.NewLine + Data);
    ObjectFile.Close( );
    ObjectFile = File.OpenRead("se5.object");
    Data = binaryRead.Deserialize(ObjectFile);
    Console.WriteLine("----------" + Environment.NewLine +
      Data + Environment.NewLine + "----------");
    ObjectFile.Close( );

    Console.WriteLine(Environment.NewLine + "END TEST" + Environment.NewLine);
}

Example 7-6. Output displayed by the RemoteComponentException class

TEST EACH CTOR

TEST NEW SERVERNAME PROPERTY
se1.ServerName ==
se2.ServerName ==
se3.ServerName ==
se4.ServerName == MyServer
se5.ServerName == MyServer

TEST -OVERRIDDEN- MESSAGE PROPERTY
se1.Message == Error in the application.
An unnamed server has encountered an error.
se2.Message == A Test Message for se2
An unnamed server has encountered an error.
se3.Message == A Test Message for se3
An unnamed server has encountered an error.
se4.Message == A Test Message for se4
The server MyServer has encountered an error.
se5.Message == A Test Message for se5
The server MyServer has encountered an error.
TEST -OVERRIDDEN- TOSTRING METHOD
se1.ToString( ) == An error has occurred in a server component of this client.
Server Name:
Server component failed to notify of the underlying exception!
StackTrace of client component:
se2.ToString( ) == An error has occured in a server component of this client.
Server Name:
Server component failed to notify of the underlying exception!
StackTrace of client component:
se3.ToString( ) == An error has occurred in a server component of this client.
Server Name:
    Inner exception type thrown by server component: Exception
    Message: The Inner Exception
    StackTrace:
StackTrace of client component:
se4.ToString( ) == An error has occured in a server component of this client.
Server Name: MyServer
Server component failed to notify of the underlying exception!
StackTrace of client component:
se5.ToString( ) == An error has occurred in a server component of this client.
Server Name: MyServer
    Inner exception type thrown by server component: Exception
    Message: The Inner Exception
    StackTrace:
StackTrace of client component:

TEST TOBASESTRING METHOD
se1.ToBaseString( ) == CSharpRecipes.ExceptionHandling+RemoteComponentException: Error in
the application.
An unnamed server has encountered an error.
se2.ToBaseString( ) == CSharpRecipes.ExceptionHandling+RemoteComponentException: A Test
Message for se2
An unnamed server has encountered an error.
se3.ToBaseString( ) == CSharpRecipes.ExceptionHandling+RemoteComponentException: A Test
Message for se3
An unnamed server has encountered an error. ---> System.Exception: The Inner Exception
   --- End of inner exception stack trace ---
se4.ToBaseString( ) == CSharpRecipes.ExceptionHandling+RemoteComponentException: A Test
Message for se4
The server MyServer has encountered an error.
se5.ToBaseString( ) == CSharpRecipes.ExceptionHandling+RemoteComponentException: A Test
Message for se5
The server MyServer has encountered an error. ---> System.Exception: The Inner Exception
    --- End of inner exception stack trace ---

TEST -OVERRIDDEN- == OPERATOR
se1 == se1 == False
se2 == se1 == False
se3 == se1 == False
se4 == se1 == False
se5 == se1 == False
se5 == se4 == True
TEST -OVERRIDDEN- != OPERATOR
se1 != se1 == True
se2 != se1 == True
se3 != se1 == True
se4 != se1 == True
se5 != se1 == True
se5 != se4 == False

TEST -OVERRIDDEN- GETBASEEXCEPTION METHOD
se1.GetBaseException() == An error has occurred in a server component of this client.
Server Name:
Server component failed to notify of the underlying exception!
StackTrace of client component:
se2.GetBaseException() == An error has occurred in a server component of this client.
Server Name:
Server component failed to notify of the underlying exception!
StackTrace of client component:
se3.GetBaseException() == System.Exception: The Inner Exception
se4.GetBaseException() == An error has occurred in a server component of this client.
Server Name: MyServer
Server component failed to notify of the underlying exception!
StackTrace of client component:
se5.GetBaseException() == System.Exception: The Inner Exception

TEST -OVERRIDDEN- GETHASHCODE METHOD
se1.GetHashCode() == 757602046
se2.GetHashCode() == 757602046
se3.GetHashCode() == 757602046
se4.GetHashCode() == -1303092675
se5.GetHashCode() == -1303092675

TEST SERIALIZATION/DESERIALIZATION
----------
An error has occurred in a server component of this client.
Server Name:
Server component failed to notify of the underlying exception!
StackTrace of client component:
----------
An error has occurred in a server component of this client.
Server Name:
Server component failed to notify of the underlying exception!
StackTrace of client component:
----------
An error has occurred in a server component of this client.
Server Name:
    Inner exception type thrown by server component: Exception
    Message: The Inner Exception
    StackTrace:
StackTrace of client component:
----------
An error has occurred in a server component of this client.
Server Name: MyServer
Server component failed to notify of the underlying exception!
StackTrace of client component:
----------
An error has occurred in a server component of this client.
Server Name: MyServer
    Inner exception type thrown by server component: Exception
    Message: The Inner Exception
    StackTrace:
StackTrace of client component:
----------

END TEST

Recipe 7.13. Creating a New Exception Type

Problem