Creating Fault Messages

In the final step to complete our example we add the capability to detect exceptions and return fault messages to the receiver class. First, we add a try-catch block around the lines processing the received message in the Receive() method from the listing.

For every exception we catch, we create a SoapFault object and serialize it to send a fault message to the response queue. The <detail> of the fault is populated from a ServerFault containing specifics about the exception we caught. To send the SoapFault back to the caller we re-use the SoapObjectSender class from the last chapter (listing 13.1), not the SoapRPCMessageSender, because the SoapFault class does not implement the ISoapMessage interface.

Listing

public void Receive( int timeout )

{

  Message queueMessage;

  try

  {

    queueMessage = _Queue.Receive(

      new TimeSpan( 0, 0, 0, timeout, 0 ) );

    try

    {

      SoapMessage responseMsg =

        ProcessSoapStream( queueMessage.BodyStream );

      if( ( null != queueMessage.ResponseQueue )

          && ( null != responseMsg ) )

      {

         SoapRPCMessageSender sender =

           new SoapRPCMessageSender(queueMessage.ResponseQueue.Path);

         sender.Send( responseMsg );

      }

    }

    catch( Exception ex )                                      |#1

    {                                                          |

       SoapObjectSender sender =

         new SoapObjectSender(queueMessage.ResponseQueue.Path);

       sender.SendObject(new SoapFault( "Server", //faultcode    |#2

         "An exception occured",                  //faultstring  |

         "",                                      //faultactor   |

         new ServerFault(                         //details      |

           ex.GetType().Name, ex.Message, ex.StackTrace ) ) );   |

    }

  }

  catch (MessageQueueException ex)

  {

    // Handle no message arriving in the queue.

    if ( MessageQueueErrorCode.IOTimeout

      != ex.MessageQueueErrorCode )

    {

      Console.WriteLine( ex.Message );

    }         

  }

} // Receive()

(annotation) <#1 All exceptions occuring while the message is processed result in a fault response.>

(annotation) <#2 The SoapFault and the ServerFault classes assist in creating properly formatted fault elements. >

Technically, always setting the faultcode to “Server”, as we do in the listing above, is not appropriate for all the exception types we can catch with this exception handler. The faultcode is intended for a server related fault only, e.g. an application configuration is incorrect, a server could not be reached, etc. Faults due to content of the message should result in a faultcode “Client”. In a real world scenario we would implement multiple exception handlers, for example one handler for a HeaderException, another handler for a content related exception and a third one for an application exception. Each handler can set the appropriate faultcode for the response message. But hey, this is only an example and we are trying to keep it simple.

After all this talk about a fault messages it is really time to see what one looks like. Listing shows a fault message returned by the class above.

Listing

<SOAP-ENV:Envelope

  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

  xmlns:xsd="http://www.w3.org/2001/XMLSchema"

  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"

  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

  xmlns:clr="http://schemas.microsoft.com/soap/encoding/clr/1.0"

  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

  <SOAP-ENV:Body>

    <SOAP-ENV:Fault id="ref-1">

      <faultcode id="ref-2">SOAP-ENV:Server</faultcode>

      <faultstring id="ref-3">An exception occurred.</faultstring>

      <detail xsi:type="a1:ServerFault"

        xmlns:a1=

"http://schemas.microsoft.com/clr/ns/System.Runtime.Serialization.Formatters">

        <exceptionType

          id="ref-4">DatabaseException</exceptionType>

        <message id="ref-5">Database did not respond.</message>

        <stackTrace id="ref-6">   at Christoph.SoapSerialization.UserManagementApp.InsertNewUser( User newUser ) in d:\christoph\c#\soapformatter\UserManagementApp\app.cs:line 37</stackTrace>

        <exception xsi:null="1"/>

      </detail>

    </SOAP-ENV:Fault>

  </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Did you notice how the content of the <Body> element yet again looks slightly different from the message formats we have seen in this chapter? The SoapFormatter does not serialize a SoapFault object like a regular object. It knows that the SoapFault corresponds to the Fault element defined by the SOAP standard. Thus it creates the correct namespace qualifiers for the <Fault> tag and the faultcode value. This message also shows how the SoapFormatter creates a well structured <detail> section from our ServerFault object. Even a non-.NET receiver could easily parse and process this detail section.