How to Return Errors from an ASMX Web Service?

Question

My web service method returns a collection object, this will serialize nicely, thanks to the way C# web services work!

But if my code throws an uncaught exception, I want to instead return a custom error object.

Is this possible using C# ASP.NET v2?

For example,

Normal Operation should return:

<Books>
    <book>Sample</book>
    <book>Sample</book>
</Books>

But on error I want

  <error>
      <errorMessage></errorMessage>
  </error>

Countryman

Note that ASMX web services do not properly support SOAP Faults. The generated WSDL will not define the faults, causing some clients to ignore them or return fatal errors when they are received. Use WCF instead to avoid this problem. – Upbeat

Answer 1

Yes, this is possible.

What you'll need to look into is the SoapException class, and specifically the Detail property of the SoapException class.

The SoapException class will effectively render a "Soap Fault", which is the standards-compliant mechanism for returning error information to clients/consumers from a web service method.

The "Detail" property of the SoapException class is of type XmlNode and can thus contain either a single node/element or a hierarchy of child nodes. The Detail node could therefore easily contain and act as the "parent" for the serialized representation of your own custom error object.

From MSDN:

The Detail property is intended for supplying application specific error details related to the Body element of the SOAP request. According to the SOAP specification, if an an error occurrs because the client request could not be processed due to the Body element of the SOAP request, the Detail property must be set. If an error occured in the header entries of the SOAP request, you must throw a SoapHeaderException, so that the error details are returned in the SOAP header. If the error did not occur, due to the processing of the Body element, then the Detail property must not be set.

In building an XmlNode for the Detail property, the Name and Namespace properties of DetailElementName can be used to ensure consistancy [sic] with the SOAP specification.

All immediate child elements of the detail element are called detail entries and each detail entry is encoded as an independent element within the detail element.

Note that if you wish to remain correctly SOAP compliant with your web service responses, you'll need to return a SoapHeaderException rather than a SoapException if the error occurs within the client's header section of the original XML request (this can often be the case when using custom SOAP headers for e.g. security credentials) as detailed above.

Leucopenia

Could you please provide an example? – Countryman

@JL - The SoapException class link in my answer (first link) contains example code in both VB and C# to throw a "custom" error message. Admittedly, it creates the Detail property by manually creating and adding an XmlNode object, but this could be replaced by a some Xml that is created from serializing your own object, perhaps using the System.Xml.Serialization.XmlSerializer class. See here: support.microsoft.com/kb/815813 – Leucopenia

Absolutely perfect answer! Thanks Craig... I would highly recommend anyone trying to return a custom error object to rather go with the standard SOAP exception. Its standardized, so its easy to justify taking such action. – Countryman