Introducing Web Services |
303 |
LISTING 13.1 TimeUtils.asmx: Returning the Current Time on the Server
1:<%@ WebService Language=”C#” Class=”TimeUtilities” %>
2:using System;
3:using System.Web.Services;
4:
5:[WebService(Namespace=”http://tempuri.org/webservices”)]
6:public class TimeUtilities : WebService
7:{
8:[WebMethod]
9:public String GetTime()
10:{
11:String ret = “The current time on the server is: “;
12:String curTime = DateTime.Now.ToString();
13:return ret + curTime;
14:}
15:}
Line 1 uses the WebService page directive. You’ve seen other ASP.NET page directives such as Page, Import, and Control on previous days. The WebService
page directive marks the remaining code in the page as a Web Service. Within the page directive, you must specify the class of the Web Service that you are going to define in the code. Each Web Service must have its own class; the one in this example is called
TimeUtilities.
Lines 2 and 3 specify that we are using the System and System.Web.Services namespaces. They are required in any Web Service that we write.
On Line 5 comes the definition of the class. Notice that before we define the class, we use an attribute for it:
[WebService(Namespace=”http://tempuri.org/webservices”)]
This line is called an attribute definition. If you are an experienced .NET code
NEW TERM
developer, you may already have used these kinds of attributes in your code. If
you haven’t used them, just understand that they supplement the code you write. In this 13 case, we are using the WebService attribute to specify the namespace for our Web Service.
Because Web Services can be exposed to the rest of the world on the Internet, each one needs a unique namespace. This namespace is exactly the same kind of thing you would use in an XML file that you were going to share with another company, as we explained on Day 8, “Using XML with Your Application.” If you are developing a Web Service for an organization, you should use your organization’s public URL instead of tempuri.org.
Next, Line 6 defines the TimeUtilities class. Because the class defines a Web Service, it must derive from the WebService class in the System.Web.WebServices namespace.
Introducing Web Services |
305 |
FIGURE 13.2
ASP.NET boilerplate documentation for the
GetTime method.
Describing the Web Service
Web Services need a way to tell client programs what methods they implement, the parameters each method takes, and the return values each method gives back. They do so through a WSDL file. WSDL, which stands for Web Services Description Language, provides clients of a Web Service with all the necessary details they need to connect to and use the Web Service.
WSDL files are XML files. To see what the WSDL file looks like for our TimeUtils application, point your browser to the URL of the TimeUtils.asmx file and append the string ?WSDL to the URL, as in the following line:
http://localhost/TimeService/TimeUtils.asmx?WSDL
Tip |
You can also see the WSDL file for the TimeUtils application by browsing to |
|
the main Web Service page and then clicking the Service Description link |
|
|
|
13 |
|
|
(refer to Figure 13.1). |
|
|
|
|
|
|
|
The WSDL file returned from our sample Web Service looks like Listing 13.2. The WSDL is quite large, even for our simple Web Service. Luckily, you should never have to create WSDL files yourself; the Web Service will generate the files automatically using the plumbing built into ASP.NET.
Introducing Web Services |
307 |
LISTING 13.2 Continued
49:<operation name=”GetTime”>
50:<input message=”s0:GetTimeSoapIn” />
51:<output message=”s0:GetTimeSoapOut” />
52:</operation>
53:</portType>
54:<portType name=”TimeUtilitiesHttpGet”>
55:<operation name=”GetTime”>
56:<input message=”s0:GetTimeHttpGetIn” />
57:<output message=”s0:GetTimeHttpGetOut” />
58:</operation>
59:</portType>
60:<portType name=”TimeUtilitiesHttpPost”>
61:<operation name=”GetTime”>
62:<input message=”s0:GetTimeHttpPostIn” />
63:<output message=”s0:GetTimeHttpPostOut” />
64:</operation>
65:</portType>
66:<binding name=”TimeUtilitiesSoap” type=”s0:TimeUtilitiesSoap”>
67:<soap:binding transport=”http://schemas.xmlsoap.org/soap/http”
68: |
style=”document” /> |
69:<operation name=”GetTime”>
70:<soap:operation soapAction=”http://tempuri.org/webservices/GetTime”
71: |
style=”document” /> |
72:<input>
73:<soap:body use=”literal” />
74:</input>
75:<output>
76:<soap:body use=”literal” />
77:</output>
78:</operation>
79:</binding>
80:<binding name=”TimeUtilitiesHttpGet” type=”s0:TimeUtilitiesHttpGet”>
81:<http:binding verb=”GET” />
82:<operation name=”GetTime”>
83:<http:operation location=”/GetTime” />
84:<input>
85: |
<http:urlEncoded /> |
13 |
|
86:</input>
87:<output>
88:<mime:mimeXml part=”Body” />
89:</output>
90:</operation>
91:</binding>
92:<binding name=”TimeUtilitiesHttpPost” type=”s0:TimeUtilitiesHttpPost”>
93:<http:binding verb=”POST” />
94:<operation name=”GetTime”>
95:<http:operation location=”/GetTime” />
96:<input>
97:<mime:content type=”application/x-www-form-urlencoded” />
Introducing Web Services |
309 |
You can see that the WSDL file contains several kinds of nodes: types, message, portType, binding, and service. The types node describes the names, parameters, and return values of each method in the Web Service. The message, portType, binding, and service definitions describe how a client should communicate with the Web Service.
Let’s analyze each WSDL definition node in reverse order.
The service Node
The service node defines the name of our Web Service—in this case, TimeUtilities— and then defines ports:
104:<service name=”TimeUtilities”>
105:<port name=”TimeUtilitiesSoap” binding=”s0:TimeUtilitiesSoap”>
106:<soap:address
107:location=”http://localhost/timeservice/timeutils.asmx” />
108:</port>
109:<port name=”TimeUtilitiesHttpGet” binding=”s0:TimeUtilitiesHttpGet”>
110:<http:address
111:location=”http://localhost/timeservice/timeutils.asmx” />
112:</port>
113:<port name=”TimeUtilitiesHttpPost”
114:binding=”s0:TimeUtilitiesHttpPost”>
115:<http:address
116:location=”http://localhost/timeservice/timeutils.asmx” />
117:</port>
118:</service>
Each port corresponds to a certain protocol that the Web Service will support. Our Web Service supports the SOAP, HTTP Post, and HTTP Get protocols.
Note |
Not every Web Service supports HTTP, because some complex parameters |
|
can’t be passed in and out of Web Services using HTTP. We’ll explain the |
||
|
||
|
rules surrounding when HTTP is supported later today. SOAP supports any |
|
|
kind of data type. |
13
The portType Node
Each port supports an “operation.” Each operation corresponds to a method that the Web Service supports. You can see that the following SOAP portType supports the GetTime operation for our Web Service. Each operation consists of “messages”: an input message for when the method is called and an output message for when the method returns a value.