For the next few examples, imagine that your Web service enjoys extremely high traffic and you are therefore very concerned about efficiency. In reviewing the service offerings, you find that some of the Web methods really do not require a response envelope to the client. In other words, these could be “fire and forget” requests. This is not quite as scary as it may sound; the client won’t simply send the message out on the wire and then stop listening (okay, so it’s not really “fire and forget”). In fact, the server holds the HTTP connection open while it loads and parses the request message, but it immediately returns an HTTP 202 response indicating that it has begun working on the request. So the client can at least be comfortable in the knowledge that everything was received and that the server considers the request message to be intelligible and well-formed.
The net effect is that the HTTP connection is freed up faster and the server will not have to expend processing power to create and send a response envelope. All of this magic can be accomplished by decorating a method that returns void with one of the following System.Web.Services.Protocols namespace attributes:
- [SoapDocumentMethod(OneWay=true)]
- [SoapRpcMethod(OneWay=true)]
Choose between the two based on whether you use Remote Procedure Call (RPC) formatting for the message. The default for all messages, in the absence of one of these two attributes, is the “document” style of formatting. So if you haven’t been using RPC for all of your other Web methods in the class, you will probably want to remain consistent and choose [SoapDocumentMethod].
With efficiency in mind, you might also decide to work on shortening the request and response messages; every byte counts! As in the earlier example with the overloaded methods, let’s assume you like following your normal programming practices and don’t wish to develop a different style simply for Web services. So you name methods and parameters with the same verbosity as you would for any other class. This keeps the code looking the way you want for purposes of documentation and reflection.
But this doesn’t mean you can’t change how things are called in SOAP messages. For instance, the earlier GetEmployeeInfo example methods contained nice and verbose parameter names such as nEmployeeID, sFirstName, and sLastName. To keep those parameter names while instructing ASP.NET to serialise them differently into WSDL and SOAP, decorate them with the [XmlElement] attribute of the System.Xml.Serialization namespace.
Listing C does this with sLastName and sFirstName by shortening them to ln and fn for SOAP. The same decoration attribute shortens the SOAP names for the public fields of the AuthenticationHeader class that was created earlier. Basically, each of those [XmlElement] attributes tells .NET, “If you ever serialize the following parameter as an element in XML, call it such-and-such.” Since ASP.NET uses XML serialization to create WSDL and SOAP messages, this is precisely what happens.
More description properties
While cutting corners with slightly cryptic parameter names, you might also want to be nice to your clients and put more verbose description properties inside the [WebMethod] attribute, as Listing C shows for the GetEmployeeInfo method. This makes the WSDL files larger, but, more importantly, the SOAP envelopes smaller; this is a nice trade-off.
Keep a few hints in mind as you explore the .NET Framework documentation for other ways to manipulate your SOAP and WSDL output. First, notice that there are attributes to play with in three different namespaces:
- System.Web.Services
- System.Web.Services.Protocols
- System.Xml.Serialization
This means you can manipulate events at different stages of a Web service lifetime, which can be important when looking for a particular solution. For example, you may find that there is no SOAP-related attribute class to accomplish something, but you can turn to the XML serialization attributes to see if you can reach your goal by manipulating at that level. As you peruse these namespaces, look out especially for classes whose names end in “Attribute”. Each bracketed attribute corresponds to one of these classes; this is the case not only for attributes related to Web services, but also for all decoration attributes. For example, the [WebMethod] decoration attribute is really the System.Web.Services.WebMethodAttribute class. The public properties that you see in the class documentation can also be put inside the parentheses of the matching decoration attribute.
A touch of elegance
As I have shown, you can mold the WSDL and SOAP to your liking without having to resort to the brute force approach, which would be to perform the serialization directly in your code, perhaps using the XmlWriter class. The examples have made frequent use of bracketed decoration attributes, which provide an especially elegant way to direct ASP.NET in its creation of these messages. With attributes at your disposal, you can keep your standard program code the way you like it, while at the same time presenting the public interface to the outside world in a manner that is tailored specifically to Web services.
