Understanding the Web Service Description Language (WSDL)

Each time you create a .NET program that uses a web service, you must add a web reference to the program using the Add Web Reference dialog box, within which you specify the WSDL file that describes the service, as shown in Figure 4.3.

Figure 4.3: Using the Add Web Reference dialog box to specify a WSDL file

If you examine the contents of the Add Web Reference dialog box, you will find XML entries that describe the web service.

WSDL is an acronym for Web Service Description Language. In general, WSDL is an XML-based markup language used to describe a web service. Within the WSDL document, you will find entries that describe each of the service’s methods, the parameters a program must pass to the method, and the type of value the method returns.

To better understand the WSDL file’s purpose and content, create the DateService web service that supports the following methods:

string DateString() string TimeString() integer DayOfWeek()

To create the DateService web service, perform these steps:

1. Within Visual Studio .NET, select the File menu New Project option. Visual Studio .NET will display the New Project dialog box.

2. Within the New Project dialog box Project Types list, click Visual Basic Projects. Then, within the Templates field, click ASP.NET Web Service. Finally, within the Location field, specify the folder within which you want to store the program and the program name DateService. Select OK. Visual Studio .NET will display a page onto which you can drag and drop the service’s components.

3. Select the View menu Code option. Visual Studio .NET will display the program’s source code. Within the source code add the following program statements:

   <WebMethod()> Public Function DateString() As String     DateString = Now.Date.ToShortDateString End Function <WebMethod()> Public Function TimeString() As String     TimeString = Now.TimeOfDay.ToTimeString() End Function <WebMethod()> Public Function DayOfWeek() As Integer     DayOfWeek = Now.Date.DayOfWeek End Function

Next, use the Build menu Build DateService option to create the web service. Then, using your web browser, view the contents of the service’s WSDL file within your browser using the address http://localhost/DateService/Service1.asmx?wsdl, as shown in Figure 4.4.

Figure 4.4: Displaying the DateService web service WSDL entries

The content of the WSDL document is quite complex. However, near the top of the document, you will find entries that describe the DateString, TimeString, and DayOfWeek methods, as shown in Listing 4.5.

Listing 4.5 Entries within the DateTime Service WSDL File

<s:element name="DateString">   <s:complexType /> </s:element> <s:element name="DateStringResponse"> <s:complexType> <s:sequence>    <s:element minOccurs="0" maxOccurs="1" name="DateStringResult" Ä   type="s:string" /> </s:sequence>   </s:complexType> </s:element> <s:element name="TimeString">   <s:complexType /> </s:element> <s:element name="TimeStringResponse"> <s:complexType> <s:sequence>    <s:element minOccurs="0" maxOccurs="1" name="TimeStringResult" Ä   type="s:string" /> </s:sequence>    </s:complexType> </s:element> <s:element name="DayOfWeek">   <s:complexType /> </s:element> <s:element name="DayOfWeekResponse"> <s:complexType> <s:sequence>    <s:element minOccurs="1" maxOccurs="1" name="DayOfWeekResult" Ä   type="s:int" /> </s:sequence> </s:complexType> </s:element>

If you examine the entries for the DateStringResult, TimeStringResult, and DayOfWeekResult, you will find that the first two methods return the type string and that the DayOfWeek method returns the type int (integer).

In a similar way, if you examine the WSDL document for the DetermineAge web service that you created in Chapter 2, you will find entries that describe the method’s parameter types and return values as shown in Figure 4.5.

Figure 4.5: Displaying WSDL-based method information for the DetermineAge web service

In Chapter 1, you used the GeoPhone web service that returns the owner of a specific telephone number. The service returns a value of type PhoneInfo. Within the PhoneInfo structure, the Contacts field contains an array of owners that correspond to the number. A phone number, for example, might have no owner, one owner, or two or more owners. If you examine the SOAP entry for the GeoPhone web service, you will find the following entries for the Contacts field:

<s:complexType name="Contacts"> <s:sequence> <s:element minOccurs="0" maxOccurs="unbounded" name="Contact" Ä  type="s0:Contact" /> </s:sequence> </s:complexType>

As you can see, the entry uses the minOccurs and maxOccurs attributes to indicate to a calling program that the method may return 0 or more contacts. Take time now to view several WSDL files. By examining each method’s attributes, you can determine the number and type of parameters the method requires as well as the type of value the method returns.

Understanding http://tempuri.org/

Across the Web, each web service must have a unique namespace that differentiates the service from others on the Web. In Chapter 6, when you learn how to make your services available to others on the Web, you will learn how to assign a unique namespace to your service. Assume, for example, that you and I each create a web service named CalcMortgage and place the service onto the Web for others to use. Because each service has a unique namespace, programs will not confuse your service with mine.

As you examine various program listings within this and other chapters, you will see references to http://tempuri.org. When you create .NET web services, Visual Studio .NET assigns the default namespace http://tempuri.org. Although you can use this namespace as you test your web services, you should change the namespace before you release the service for use on the Web.

If you examine a WSDL document closely, you will find that the document describes a web service using a series of entries that contain the elements described in Table 4.1. As you examine a web service’s WSDL document, take time to look for these various components. Then, think about how the proxy class uses the entries to generate the messages it must send to call the web service methods. As you examine advanced topics throughout this book’s remaining chapters, you will take a closer look at the contents of the WSDL document and you will better understand each entry’s use.

Table 4.1:  Entries within the WSDL Document

WSDL Component	Purpose
Binding	Defines the message format and protocol details for a web service. A binding consists of two attributes—a name and a type. The type attribute corresponds to a port.
Messages	Defines the structure of a message sent to or generated by a service.
Operation	Specifies how the service interacts with the caller. WSDL supports four operation types: One-Way (service can receive a request but will not respond), Request-Response (service can receive a request and will generate a response), Solicit-Response (service will generate a request and will wait for a response), and Notification (service will send a message and will not wait for a response).
Port Type	A port type defines a web service, the operations the service offers, and the corresponding messages.
Port	Defines the interfaces the web service exposes. You can think of a port as a module or class within a traditional programming language.
Service	Defines the service in terms of bindings (protocols), messages, port types (methods), and types.
Types	Specifies the data type the service supports.