Using the WSDL Utility to Generate Proxy Code

Summary

ASP.NET provides a robust, feature-rich platform for easily creating and consuming Web services. For a V1 product, it is remarkably feature complete.

An ASP.NET Web service is represented by an .asmx file hosted within an IIS Web application. The implementation of the Web service can be contained within the .asmx file or within a compiled DLL. If the code appears inline within the .asmx file, the ASP.NET runtime will automatically compile it the first time it is accessed.

A Web service is defined by a standard public class declaration. Public methods defined within the class can be exposed by the Web service if you decorate the method with the WebMethod attribute. This attribute exposes properties that can be optionally set to control the behavior of the ASP.NET runtime. The class can also be decorated with the WebService attribute.

All ASP.NET Web services expose a SOAP interface over HTTP. Depending on the complexity of the Web service's interface, an ASP.NET Web service might also support HTTP GET and HTTP POST. The ASP.NET runtime will automatically map data contained within requests from the client and their corresponding responses to their corresponding .NET datatypes.

The ASP.NET platform will automatically generate documentation for the Web service. A human-readable HTML version of the documentation can be obtained by calling the .asmx file with no parameters. A programmatic WSDL version of the documentation can be obtained by appending &wsdl to the URL that addresses the .asmx file.

ASP.NET supports two distinct encoding styles, Document and RPC. Document is the default and is used primarily for document-based message exchanges between the client and the server. RPC is used primarily for procedure-based communication between the client and the server. You can select RPC by using the SoapRpcService or SoapRpcMethod attribute.

You should be careful when you pass value types as parameters because the ASP.NET platform has some inconsistencies when identity is maintained. The identities of built-in value types such as int and double are never maintained, even when passed by reference. The identity of a custom value type when passed by reference is maintained when the encoding style is set to RPC. However, the identity of custom value types passed by value is improperly maintained when the encoding style is set to RPC.

Regardless of the style of encoding, SOAP formally defines how errors returned to the client should be encoded within a SOAP message. The ASP.NET runtime will automatically map .NET exceptions into a well-formed SOAP Fault element. You can also formally raise a fault by throwing an exception of type SoapException.

You can facilitate interface inheritance by referencing a port type or a binding definition from an external namespace. Of the two, ASP.NET supports referencing transport-specific binding definitions. You first reference the remote binding definition with the WebServiceBinding attribute, and then you associate the reference to the binding with a particular Web method via the Binding property of the SoapRpcMethod or SoapDocumentMethod attribute.

ASP.NET also provides a fairly robust state management system. It supports three configurations: In Process, Out of Process, and SQL Server. Of the three, In Process is the most performant configuration. You should consider Out of Process and SQL Server only if the Web service will be deployed on a Web farm. Regardless of which model you use, the programming model is exactly the same.

The ASP.NET platform also has good support for defining and consuming SOAP headers. A SOAP header is defined by deriving from the SoapHeader class. You then use the SoapHeader attribute to associate the header with a particular Web method. ASP.NET automatically deserializes any headers received from the client and serializes any headers sent from the Web server.

Finally, the ASP.NET framework provides an interception mechanism called SOAP extensions. The SOAP extensions framework lets you examine and, if necessary, modify the contents of the SOAP messages exchanged between the client and the server.

I didn't cover a couple of key topics related to ASP.NET Web services because they deserve chapters of their own. In Chapter 7, I will discuss how to control how individual parameters passed by a Web service or its client are encoded within a SOAP message. In Chapter 9, I will also cover the security services provided by ASP.NET.