17.3 Providing Web Method Descriptions

You want to add a descriptive statement to a method defined in a Web Service.

Technique

The WebMethod attribute contains several different parameters, allowing you to specify additional information about the method as well as control how memory buffers and caching is utilized. To add a statement reflecting the functionality of a Web method, add the Description parameter to the WebMethod attribute:

 [WebMethod( Description="Generates a random number within a range",   MessageName="GenerateNumberInRange" )] public int GenerateNumber( int Min, int Max ) {     Random rand = new Random( DateTime.Now.Millisecond );     return rand.Next( Min, Max ); } 

Comments

One of the nice things about using Web Services within Visual Studio .NET is the hands-off approach, freeing you from burying yourself in all the different XML file formats. Purists say that you'll never learn how things work, but even if you're not sure how a car engine works, you can still start one to get from point A to point B. Of course, we're not saying that you shouldn't learn how Web Services work because eventually you'll get to the point where something doesn't quite perform as expected and you must investigate the data that is generated for you.

If you look at the generated WSDL file, which is available by clicking on the Service Description link, you see that a lot more data is being generated now that a Web method is added. When the Web Service was initially created with no methods , the types element in the WSDL document was empty. Now you can see type information for both the inputs to the Web method as well as the type for the output specified using XML schema definitions. Each message element contains information about each message, broken into its constituent request and response parts with a link to the schema definition of each message's parameters. The portType element starts to make the bridge from concrete to abstract as it combines the request and response portions of a method into an abstract entity. It is within this element that you see the description of the method that was generated when you applied the Description parameter to the WebMethod attribute. The last element to discuss, because the previous recipe discussed the service element recipe, is the binding element. This node describes the document format and the protocols that the Web Service utilizes in its exchange with a client. In the WSDL document in Listing 17.4, you can see that the Web service uses Simple Object Access Protocol (SOAP) over HTTP.

Listing 17.4 Lottery Web Service WSDL File

 <?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://samspublishing/1_LotteryService"     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://samspublishing/1_LotteryService"     xmlns="http://schemas.xmlsoap.org/wsdl/">   <types>     <s:schema elementFormDefault="qualified"         targetNamespace="http://samspublishing/1_LotteryService">       <s:element name="GenerateNumberInRange">         <s:complexType>           <s:sequence>             <s:element minOccurs="1" maxOccurs="1" name="Min" type="s:int" />             <s:element minOccurs="1" maxOccurs="1" name="Max" type="s:int" />           </s:sequence>         </s:complexType>       </s:element>       <s:element name="GenerateNumberInRangeResponse">         <s:complexType>           <s:sequence>             <s:element minOccurs="1" maxOccurs="1"                 name="GenerateNumberInRangeResult" type="s:int" />           </s:sequence>         </s:complexType>       </s:element>     </s:schema>   </types>   <message name="GenerateNumberInRangeSoapIn">     <part name="parameters" element="s0:GenerateNumberInRange" />   </message>   <message name="GenerateNumberInRangeSoapOut">     <part name="parameters" element="s0:GenerateNumberInRangeResponse" />   </message>   <portType name="Lottery_x0020_Web_x0020_ServiceSoap">     <operation name="GenerateNumber">       <documentation>Generates a random number within a range</documentation>       <input name="GenerateNumberInRange"         message="s0:GenerateNumberInRangeSoapIn" />       <output name="GenerateNumberInRange"         message="s0:GenerateNumberInRangeSoapOut" />     </operation>   </portType>   <binding name="Lottery_x0020_Web_x0020_ServiceSoap"       type="s0:Lottery_x0020_Web_x0020_ServiceSoap">     <soap:binding transport="http://schemas.xmlsoap.org/soap/http"       style="document" />     <operation name="GenerateNumber">       <soap:operation soapAction="http://samspublishing/1_LotteryService/GenerateNumberInRange"         style="document" />       <input name="GenerateNumberInRange">         <soap:body use="literal" />       </input>       <output name="GenerateNumberInRange">         <soap:body use="literal" />       </output>     </operation>   </binding>   <service name="Lottery_x0020_Web_x0020_Service">     <documentation>Provides the ability to generate a set of         random numbers</documentation>     <port name="Lottery_x0020_Web_x0020_ServiceSoap"         binding="s0:Lottery_x0020_Web_x0020_ServiceSoap">       <soap:address location="http://localhost/TestService/Service1.asmx" />     </port>   </service> </definitions>