Figure 28-1 music.asmx response

The Music Web Service’s response represented in Figure 28-1 is automatically generated by the Web Services runtime. You’ll notice that this response contains several valuable pieces of information including the name of the Web Service, the methods implemented by the Web Service, the required parameters, the return data type and the protocols (such as SOAP, HTTP GET, or HTTP POST) you can use to invoke the Web Service’s methods. You are also provided a facility with which to test the Web Service. Type the name of your favorite band in the sBandName textbox and click the Invoke button. A new browser should open for you with the Web Service’s XML response to your request. Pretty cool, huh?

Consuming a Web Service

There are basically two ways to use a Web Service. You can either call the Web Service directly from your browser, as you just did, or you can use some application to programmatically call the service. Making a direct browser request is easy, but programmatically accessing a Web Service can be a little more difficult especially if you don’t know anything about the particular Web Service you’d like to use. In order to communicate with a Web Service, you need to know what methods it supports, what the input parameters are, and what each method returns. In other words, you need to establish a communication contract with Web Service. So how do you get this information? Luckily, Web Services are able to describe themselves. .NET Web Services automatically produce an XML-formatted Web Service Description Language (WSDL) document that describes the Service. Appending ?WSDL

to a Web Service’s URL returns an WSDL document that a client application can use to discover a Web Service. To obtain the WSDL document for your Music Web Service, use the following URL:

http://localhost/music/music.asmx?SDL

You should get an XML document in your browser window. This XML-formatted WSDL document is effectively your “communication contract” that describes the Web Service. The WSDL, as you’ll see, details the protocols supported by the Web Service — for example, HTTP GET, HTTP POST, or SOAP — as well as the semantics for calling the services and returning values. Here is a small sample of the music.asmx WSDL document:

<soap xmlns=”urn:schemas-xmlsoap-org:soap-sdl-2000-01-25”> <service>

<addresses>

<address uri=”http://localhost/music/music.asmx” />

</addresses>

<requestResponse name=”GetBandInfo” soapAction=”http://tempuri.org/GetBandInfo”>

<request ref=”s0:GetBandInfo” />

<response ref=”s0:GetBandInfoResult” /> </requestResponse>

</service>

</soap>

This section of the WSDL document defines how SOAP (refer to the first line) calls should be made to the Music Web Service. The WSDL also gives the URI (line 4) to use in order to access the Web Service. Perhaps most importantly, the Music SDL described the method it implements. On line 7, you can see that we can request the GetBand Info method.

OK, so now that you know where the Web Service is located and what method(s) it supports, you’re ready to go, right? Well not quite. You now need to build a proxy class through which to access the Web Service from an application, in this case an ASP.NET page.

A proxy is essentially a class that behaves like a local object, but it is actually just a mechanism for communicating with the Web Service. The proxy serializes, sends, receives, and deserializes the method requests. (These activities are commonly referred to as marshaling and transport activities.) There are three ways to create a Web Service proxy:

Using Visual Studio.NET

Using command line tools

Using Internet Explorer 5.5 behaviors

Creating a proxy via VS.NET is simple. It’s essentially the same as adding a reference to a Visual Basic project. IE behaviors are neat, but they’re outside the scope of this book. So, you’re going to build a proxy using a command line tool, WSDL.exe. WSDL.exe is a command line utility that creates a stub or proxy class based on a WSDL document. Once you have created your proxy class, you can then compile the proxy class into an assembly and use it to call a Web Service without needing to write any of the aforementioned marshaling or transport logic.

To create a proxy class based on your Music Web Service, go to your computer’s command prompt and type the following:

WSDL http://localhost/Music/music.asmx?sdl /l:VB /n:myMusic

If all went well, you should have received a message that looks like this:

.\Music.vb

The WebServiceUtil utility accepts many different parameters. The /c[ommand]: switch indicates that you want to create a proxy class. The /pa[th]: switch denotes the location of the SDL upon which you want to base your proxy class. The /l[anguage]: switch denotes in which language the proxy class will be created. You can just as easily create a C# proxy class by changing the language switch to /l:CSharp. Finally, the /n[amespace]: switch indicates the namespace to create the code in. The default is the global namespace. We used myMusic for demonstration purposes.

Now that you have the proxy class, let’s compile it into an assembly. If you haven’t already done so, create a physical directory named bin in your Music virtual directory’s physical path. OK, now run the following command:

vbc /out:bin\Music.dll /t:library /r:System.dll /r:System.Xml.dll /r:System.Web.Services.dll /r:System.Data.dll music.vb

This command simply creates an assembly, music.dll, based on the Music.vb proxy class and puts it in our /bin directory. The /r[eference]: switch tells the compiler to include a specified assembly. When compiling a Web Service, you must always include

System.XML.dll and System.Web.Services.dll. The System.Data.dll is included because you used ADO.NET in the Music Web Service.

That’s it! You’re done. Now that the music.dll component has been deployed to your /bin directory, you can call the Music Web Service from an ASP.NET page. Here’s an example:

<%@ Page Language=”VB” debug=”true” %> <%@ Import Namespace=”System.Data” %> <script language=”VB” runat=”server”>

Sub Page_Load(Sender As Object, E As EventArgs) Dim oDS As DataSet

Dim wsMusic As New myMusic.Music

oDS = wsMusic.GetBandInfo(“Hootie & The Blowfish”)

dgMembers.DataSource = oDS.Tables(0).DefaultView dgMembers.DataBind

End Sub </script> <html> <body>

<asp:DataGrid id=”dgMembers” BorderWidth=”1” GridLines=”both” runat=”server”/>

</body>

</html>

This is a simple example, but you get the point. You’ll notice that when you declared the variable wsMusic, you used the following line of code:

Dim wsMusic As New myMusic.Music

In this line, you are creating a new object based on the Music class in the myMusic namespace. If you hadn’t specified myMusic as the namespace in which to create the Music proxy class when you executed the WebServiceUtil utility, but rather used the default, you could write:

Dim wsMusic As Music

Once you create the wsMusic object, you can call its methods. In the following line of code, you call the GetBandInfo method and pass it a string, Hootie & The Blowfish:

oDS = wsMusic.GetBandInfo(“Hootie & The Blowfish”)

Because we know the method returns a DataSet, we bound its first table to a DataGrid control, dgMembers.

REVIEW

Web Services are an exciting piece of the .NET Framework that, with the help of XML and HTTP, enable you to easily encapsulate your business logic in .NET components and provide a service to any Web clients that speak HTTP and XML. An XML-based WSDL file, which is generated by the Web Service’s infrastructure, provides a machine-readable description of the functionality available through the Web Service.

QUIZ YOURSELF

1.What is Web Service? (See session introduction.)

2.On which two Internet protocols are Web Services based? (See session introduction.)

3.What methods can be used to access a Web Service? (See “Consuming a Web Service.”)