Tweaking Your Web Methods

You can tweak your Web methods by directly altering them using properties of the WebMethod attribute or of related attributes or by altering the WSDL document produced by the Web service. By altering the WSDL document, you alter the definition of the service and therefore the service itself.

WSDL and Web Methods

We’ll start by reexamining the relationship between the WSDL document and our Web methods and then move on to how we can alter the WSDL document to interact with and use the Web service meaningfully. We discussed the workings of WSDL in detail in Chapter 3, but we need to revisit some details and investigate them in greater depth.

When you assign something in a WebService or WebMethod attribute, a corresponding entry is created in the WSDL document. If we look at the lengthy WSDL document created for our GetBio Web method, we can isolate some specific points. We’ll go through the WSDL document that is automatically created when you browse the Web service and add a ?wsdl query string to the end of it.

The document begins with the initial namespace definitions:

<?xml version="1.0" encoding="utf-8" ?>  <definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"   xmlns:s="http://www.w3.org/2001/XMLSchema"   xmlns:s0="http://www.notashop.com/wscr"   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"   xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"   xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"   targetNamespace="http://www.notashop.com/wscr"   xmlns="http://schemas.xmlsoap.org/wsdl/">

The targetNamespace attribute is set to the namespace that was defined in the WebService attribute in the class. Under the namespace definitions is the <types> element. As you saw in Chapter 3, the <types> element contains the schema. By default, this is an XML schema, but you can use other type systems. Here is the schema that contains the rules for serializing the data contained in our two Web methods:

<types>   <s:schema elementFormDefault="qualified"      targetNamespace="http://www.notashop.com/wscr">     <s:element name="GetBio">       <s:complexType>         <s:sequence>           <s:element minOccurs="0" maxOccurs="1" name="Id"              type="s:string" />          </s:sequence>       </s:complexType>     </s:element>     <s:element name="GetBioResponse">       <s:complexType>         <s:sequence>           <s:element minOccurs="0" maxOccurs="1" name="GetBioResult"              type="s:string" />           </s:sequence>       </s:complexType>     </s:element>     <s:element name="GetPic">       <s:complexType>         <s:sequence>           <s:element minOccurs="0" maxOccurs="1" name="Id"                 type="s:string" />          </s:sequence>       </s:complexType>     </s:element>     <s:element name="GetPicResponse">       <s:complexType>         <s:sequence>           <s:element minOccurs="0" maxOccurs="1" name="GetPicResult"              type="s:base64Binary" />          </s:sequence>       </s:complexType>     </s:element>     <s:element name="string" nillable="true" type="s:string" />      <s:element name="base64Binary" nillable="true" type="s:base64Binary" />   </s:schema> </types>

The GetBio Web method takes a string and returns a string. The string is named Id in the Web method, and you can see quite clearly that this is reflected in the <s:element> element. It returns the result via a <s:element> named GetBioResult. Both of these elements are strings, which again reflects the makeup of our Web method.

The second of our two Web methods, GetPic, takes a string and returns a byte array. GetPic has the same RPC-style structure as GetBio and does little different other than return its data, a byte array, in a different format.

Next in the WSDL document is the <message> element. This element contains a definition of all the types that the Web service is capable of receiving. We haven’t amended the defaults in any way (this is done via the .NET .config files, which we will look at shortly). In .NET version 1.1, our Web service can receive only SOAP responses because only the SOAP protocol is enabled in machine.config—in .NET 1.0, you might well see extra code with sections for HTTP-POST and HTTP-GET as well:

<message name="GetBioSoapIn">   <part name="parameters" element="s0:GetBio" />  </message> <message name="GetBioSoapOut">   <part name="parameters" element="s0:GetBioResponse" />  </message> <message name="GetPicSoapIn">   <part name="parameters" element="s0:GetPic" />  </message> <message name="GetPicSoapOut">   <part name="parameters" element="s0:GetPicResponse" />  </message>

For each format the Web service can receive and send information in, there is a <message> element that contains a part <element> that contains the type of data and the corresponding schema element that is being returned.

Next up is the <portType> element, which groups the different operations. It creates an abstract definition that combines each of our Web method names (GetBio and GetPic) with each type of operation:

<portType name="RecordStoreWebServiceSoap">   <operation name="GetBio">     <documentation>Gets the Artist's associated Biography</documentation>      <input message="s0:GetBioSoapIn" />      <output message="s0:GetBioSoapOut" />    </operation>   <operation name="GetPic">     <documentation>       Gets the Artist's or CD's Associated Picture     </documentation>      <input message="s0:GetPicSoapIn" />      <output message="s0:GetPicSoapOut" />    </operation> </portType>

Notice that a documentation element is created for each <operation> element, and that this documentation element contains whatever we put in the Description attribute of our Web method.

The <binding> element describes information about the transport protocols and message formatting. The definitions also contain the number of communications across the network needed to make a correspondence. Each operation makes only one request and requires one response. If you are using another protocol, such as SMTP, more than one operation is required. The <binding> element contains extension elements that define the method of transport and supply the namespace defined within the Web method as part of the SOAP transfer:

<binding name="RecordStoreWebServiceSoap"    type="s0:RecordStoreWebServiceSoap">   <soap:binding transport="http://schemas.xmlsoap.org/soap/http"      style="document" />    <operation name="GetBio">     <soap:operation soapAction="http://www.notashop.com/wscr/GetBio"        style="document" />      <input>       <soap:body use="literal" />      </input>     <output>       <soap:body use="literal" />      </output>   </operation>   <operation name="GetPic">     <soap:operation soapAction="http://www.notashop.com/wscr/GetPic"        style="document" />      <input>       <soap:body use="literal" />      </input>     <output>       <soap:body use="literal" />      </output>   </operation> </binding>

The final part of the WSDL document is the <service> element. This element contains a <port> element that defines the address via which the Web service can be invoked. Details are given for invocation via the SOAP method only in .NET 1.1:

  <service name="RecordStoreWebService">     <documentation>A Web service which exposes the details about an LP        and its cover     </documentation>      <port name="RecordStoreWebServiceSoap"        binding="s0:RecordStoreWebServiceSoap">       <soap:address location="http://localhost/StoreService/Service1.asmx" />     </port>   </service> </definitions>

So we’ve got our Web methods, and you’ve seen how what we put in them is reflected in the WSDL document. However, plenty of other attributes are available for altering the content of our WSDL document.

Doc-Lit vs. RPC Encoding

In Chapter 2, we looked at the two styles of formatting SOAP messages. You can set the style of the formatting using the [SoapDocumentService] or the [SoapRpcService] attribute. We also looked at the difference between straight document-literal-style messages, in which the aim is to exchange document-oriented messages between client and server, and RPC encoding, which enables a procedure/method call type of functionality. Many Web services (including our example in this chapter) rely on a request/response scenario, but the document-literal style is fast becoming commonplace because it is more straightforward to use and can do everything that the RPC encoding style can do.

You can supply [SoapDocumentService] and [SoapRpcService] attributes after the [WebService] attribute. These attributes alter the information supplied in the WSDL information under the <binding> element. By default, the [SoapDocumentService] attribute is used, but we can add a [SoapRpcService] attribute to our example code to alter the WSDL in the following way:

<binding name="RecordStoreWebServiceSoap"    type="tns:RecordStoreWebServiceSoap">   <soap:binding transport="http://schemas.xmlsoap.org/soap/http"      style="rpc" />    <operation name="GetBio">     <soap:operation soapAction="http://www.notashop.com/wscr/GetBio"        style="rpc" />      <input>       <soap:body use="encoded" namespace="http://www.notashop.com/wscr"          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />      </input>     <output>       <soap:body use="encoded" namespace="http://www.notashop.com/wscr"          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />      </output>   </operation>   <operation name="GetPic">     <soap:operation soapAction="http://www.notashop.com/wscr/GetPic"        style="rpc" />      <input>       <soap:body use="encoded" namespace="http://www.notashop.com/wscr"          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />      </input>     <output>       <soap:body use="encoded" namespace="http://www.notashop.com/wscr"          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />      </output>   </operation> </binding>

Little changes in the WSDL for our example application if we do this and the number of operations remains the same. However, extra information about using the RPC- encoded style is added into the <soap:body> statement.

If you don’t want these styles to apply to the whole Web service, you can use the [SoapDocumentMethod] and [SoapRpcMethod] attributes instead; for a method, these are specified after the [WebMethod] attribute. They can be used to override the values set up with the [WebService] attribute.

We won’t dig too much farther into the WSDL here—we’ve covered it previously, and we simply want to demonstrate how our Web methods affect and alter the contents of the WSDL document.