Coding Differences Between the Handler API and the Web Method API

Using variations on the code shown thus far, your handler-cum-service should now be parsing requests and generating responses without a problem. The question is what to do with the message after it has been parsed. Any further code you write inside your handler should be identical to the code written at the Web method level because you’re past the serialization stage that the built-in handler takes cares of for you in normal use, shouldn’t it?

Yes and no. The Web method API still has a few “weaknesses” that you can fix by using the handler API instead. Two of the weaknesses are in the interchange between client proxy class and service:

• As Scott Short demonstrates in his book Building XML Web Services for the .NET Platform (Microsoft Press, 2002), ASP.NET is “somewhat inconsistent when handling parameters passed by reference to a Web method through a proxy class. Web methods can lose both the identities and the values of parameters passed by reference before they are passed back to the client.”

• Only the return parameter can be passed back to the client. ASP.NET doesn’t support encoding in/out or out parameters within the message returned to the client as a result of an HTTP GET or POST request.

You should also be aware of some differences when you work with the HttpContext object for the current request. When you work with the Web method API, having your class inherit from System.Web.WebServices.WebService usually gives you access to the standard ASP.NET objects that you already have access to in the handler API via the context object passed through to the ProcessRequest method. Likewise, you can usually access the context object using the static HttpContext.Current property as well. However, any methods marked as OneWay by the [SoapRpcMethod] or [SoapDocumentMethod] attributes do not get access to the HttpContext object at all. Furthermore, the Web method API never gains access to the Request or Response property of the HttpContext object, as the handler API does.

There’s also the small issue of creating the WSDL file and some documentation for your service. At 62 KB, the Web method API’s defaultwsdlgenerator.aspx is one of the most involved pages you’ll come across—imitating it probably isn’t worth it. Instead, roll your own WSDL and documentation for each service or group of methods.

Taking Care with Session State

Last but not least are a couple of provisos when you want to make use of session state variables within your services or handlers. A page request from a browser to a server includes the Session ID in either the URI if it’s a GET request or in an HTTP header if it’s a POST request. Logically, it follows that you should be able to parallel this and keep the Session ID either in the URI or in the SOAP header to keep track of the session associated with the request, but neither method is supported by the Web method API.

Of course, if you use a custom client and handler, you can roll our own state management solution, using whichever implementation suits the situation best. On the server side, session and application-level variables are accessed just as they are on a standard ASP.NET page. The only trick to be aware of is to mark your class as needing access to those variables. This you can do by implementing one of two interfaces:

• IReadOnlySessionState, which denotes that your class doesn’t need to alter session state variables but does need to read them

• IRequiresSessionState, which denotes that your class requires both read and write access to the Web application’s session state variables

Neither interface contains any methods.