Mark Wilson I am the creator of TopXML. I am available for international and local (Australia) contracts. I am a Solution Architect/Business Analyst. I have worked in IT in several countries (NZ, Australia, South Africa, UK) building and training teams for government and very large non-governmental organizations. I am ex-Microsoft Consulting Services. I wrote the first book on Microsoft XML published in 2000 called XML Programming with VB and ASP. Most recently I have been building tools for the SEO industry. Ask me for a 37 point SEO health-checkup for your website.
First posted :
03/24/2008
Times viewed :
4399
SoapFault Class
The SOAP standard not only defines the format for the response of
a successful method execution. It also describes what the response in case of
an error has to look like. An error response also features the regular SOAP
elements envelope and body, but the body carries a special element named <Fault>.
The standard also defines four possible child elements for the
fault element to convey details about the error condition: <faultcode>,
<faultsting>,
<faultactor>
and <detail>.
A <Fault>
must always contain a <faultcode>
and a <faultstring>
to provide details about the error that occurred. The faultcode classifies
errors into the four classes shown:
Table Fault values defined by the SOAP spec
Name
Description
VersionMismatch
The SOAP version of the message is not supported by the
receiver.
MustUnderstand
The receiver was unable to process a required header entry,
i.e. a header with a mustUnderstand attribute of “1”.
Client
An error related to the content of the message occurred,
e.g. the server was unable to authenticate the message or a method parameter
was missing for an RPC call.
Server
An error occurred due to a condition on the server, not due
to the content of the message, e.g. another server did not respond timely or
an unexpected exception occurred.
We can further qualify an error by appending a subclass
identifier separated from with a “.”, for example a database error could result
in a faultcode element like this:
<faultcode>Server.Database</faultcode>
The second mandatory element in a fault message is the <faultstring>.
It should contain free form text to provide a human-readable explanation about
the error to assist with troubleshooting the error condition.
The other two fault subelements are only required on a
case-by-case basis. The <faultactor>
element identifies the source of the error and has to be present for if the
fault describes an error while processing a header entry addressed to a certain
actor. Its value is the URI of the actor that encountered the error, but since
the SoapFormatter
does not support the whole actor concept, any further discussion is moot.
The last subelement of the <Fault> defined is the <detail>
element. It carries a detailed error desription of all errors related to
processing the <Body>.
The <detail>
element must not communicate errors occurring while processing a header entry.
The <detail> element can contain text or structured data.
The .NET Framework supports creating fault messages through the SoapFault class
in the System.Runtime.Serialization.Formatters
namespace. This class exposes a property for each of the children of a fault
(table 13.10). When the SoapFormatter
serializes a SoapFault
object it creates a properly formatted <Fault> element in the message
body. Likewise, deserializing a message containing a <Fault> will return a SoapFault
object.
Table The properties of the SoapFault class correspond to
the subelements of a fault.
Property
Type
Access
Description
FaultCode
string
read/write
Describes the A fault code compliant with the SOAP
standard. Every SoapFault must specify a fault code.
FaultString
string
read/write
Describes the error condition in human-readable format.
Every SoapFault must specify a fault code.
FaultActor
string
read/write
Identifies the SOAP processor where the error occurred.
Detail
object
read/write
Contains detailed information about the error condition.
The Detail element has to be present for all <Body> related errors. It
may not appear for <Header> related errors.
We can assign these properties either individually or specify
them to the SoapFault’s
constructor. The SoapFormatter
serializes the properties into the corresponding fault subelement. Now, we have
to be careful what we assign to the Detail property since it can hold any
object type. Since the SoapFormatter
serializes the SoapFault
(almost) like any other object we must only assign [Serializable] objects to the Detail property
or serializing the SoapFault
object will cause an exception. Also, the SoapFormatter serializes all non-primitive
types assigned to Detail
as it would serialize any other object: With type information encoded into the
namespace declaration as we have discussed in the previous chapter. Once again,
this means that only a SoapFormatter
will know how to correctly deserialize the fault message, but the receiver
needs the assembly with the class of the object we assigned to the Detail property.
Hence we should only assign primitive objects to Detail if we design for
interoperability.
