Web Service Documentation

Raising Errors

Recall that the InstantQuote Web method exposed by the Securities Web service returns the price of a particular security. However, there is one problem with its current implementation. If the Web method does not recognize a symbol, a price of zero will be returned to the client. This is obviously a problem, especially because the current implementation supports only three symbols. To avoid striking panic in the hearts of investors, we need a way to raise an error stating that an invalid symbol was passed.

An error of type SoapException can be thrown when an error is encountered within the Securities Web service. If a SoapException error is thrown by a Web method, the ASP.NET runtime will serialize the information into a SOAP Fault message that will be sent back to the client.

As you learned in Chapter 3, a well-formed Fault element must contain at least two child elements, faultstring and faultcode. The constructor for the SoapException class takes a minimum of two parameters to set the value of these elements. Once an instance of the SoapException object has been created, the values can be accessed by the Message and Code properties.

The Code property is of type XmlQualifiedName. For convenience, the SoapException class defines static fields for each of the base fault codes defined by the SOAP specification. The following extended version of the Securities Web service throws an exception resulting from an error on the server:

using System; using System.Web.Services; using System.Web.Services.Protocols; namespace BrokerageFirm {     [WebService(Description="This Web service provides services      related to securities.")]     public class Securities : WebService     {         [WebMethod(Description="Used to obtain a real-time quote          for a given security.")]         public double InstantQuote(string symbol)         {             double price = 0;             switch(symbol.ToUpper())             {                 case "MSFT":                     price = 197.75;                     break;                 case "SUNW":                     price = 2.50;                     break;                 case "ORCL":                     price = 2.25;                     break;                 default:                     throw new SoapException("Invalid symbol.",                      SoapException.ClientFaultCode);             }             return price;         }     } }

As I explained in Chapter 3, you can define more-specific fault codes. These developer-defined codes can be appended to the base fault code delimited by a period. The following throws an exception that contains a more-specific fault code:

XmlQualifiedName invalidSymbolsFaultCode =      new XmlQualifiedName("Client.InvalidSymbol",      "http://schemas.xmlsoap.org/soap/envelope/"); throw new SoapException("Invalid symbol.", invalidSymbolsFaultCode);

Recall that additional elements can also appear within the Fault element. The SoapException class exposes a number of read-only properties to access this information. Because the properties are read-only, the SoapException class has numerous overloaded constructors that enable the properties to be set. Table 6-3 lists the properties that can be set via an overloaded constructor.

Table 6-3  Properties of the SoapException Class

Property	Description
Actor	Specifies the value of the faultactor element
Code	Specifies the value of the faultcode element
Detail	Specifies the contents of the faultdetail element
Message	Specifies the value of the faultstring element
InnerException	Specifies the value of the inner exception
OtherElements	Used to access any other child elements that might be present within the Fault element

Both the Detail and the OtherElements properties can contain an arbitrary hierarchy of data. The Detail property is of type XmlNode and can contain more-detailed information about the Fault element. The OtherElements property contains an array of type XmlNode and is used to contain other child elements that might reside within the Fault elements.

If an exception is thrown by the Web method that is not of type SoapException, the ASP.NET runtime will serialize it into the body of the SOAP Fault element. The faultcode element will be set to Server, and the faultstring element will be set to the output of the ToString method of the exception object. The output usually contains the call stack and other information that would be useful for the Web service developer but not the client. Therefore, ensuring that a client-friendly SoapException class will be thrown from the Web method is recommended.