The Book of VB .NET: Web Services, Part 1, Page 2
Enhancing the PostalWebService class
You can also make a more useful Web Service that returns a custom object with several pieces of information at once, as shown in the following example. Notice that the Package information has been separated into two classes; we'll assume here that you will not want to provide the entire database record to the client, in case it includes sensitive information (such as a credit card number).
Public Class PostalWebService Inherits System.Web.Services.WebService
<WEBMETHOD> Public Function GetPackageInfo(ByVal TrackID As String) _ As ClientPackageInfo Dim PackageInfo As Package PackageInfo = GetPackageRecordFromDB(TrackID) Return PackageInfo.BasicInfo End Function
Private Function GetPackageRecordFromDB(ByVal TrackID As String) As Package ' Some database access code here. Dim PackageInfo As New Package()
' To perform a crude test, uncomment the following two lines. ' PackageInfo.BasicInfo.PackageID = TrackID ' PackageInfo.BasicInfo.DeliveryDate = Now
Return PackageInfo End Function
Public Class Package Public BasicInfo As New ClientPackageInfo Public CreditCardNumber As String End Class
Public Class ClientPackageInfo Public PackageID As String Public DeliveryDate As Date End Class
Database and OOP mavens will realize that there are many different ways to implement this type of scenario. (You may also wonder why the credit card is stored with each package.) In a real world example, security concerns will shape the whole construction of the database.
In any case, this example demonstrates that a .NET Web Service can pass many types of information to the client, including DataSets, .NET objects, arrays, and simple variables. Keep in mind, however, that if you were to pass an object with a built-in method, the method would be lost. Only the data is preserved.
Testing Your Web Service
So now that you have created a Web Service, how can you use it? Or maybe you're still wondering exactly what is provided with the Web Service we've created. Fortunately, Internet Explorer includes a handy feature that allows you to preview and perform a limited test on any Web Service.Your Web Service in Action
To try out this useful feature, run your Web Service. Remember, Web Services are designed to be used from inside other applications, not executed directly. However, when you choose to run a Web Service in Visual Studio .NET, your browser will display the test page shown in Figure 13-1.
This window lists all the available Web Service methods. (In this case, only one, GetPackageInfo, is available.) The Service Descriptions link will display the WSDL description of your Web Service. (WSDL is described in the next section of this article.)
Figure 13-1: The Internet Explorer test page
Click on the GetPackageInfo link, and the following test page will appear:
Ignore the puzzling XML code at the bottom of the page for now, and concentrate on the first portion of the page, which provides a prefabricated way for you to test your application. Try it by entering a package ID and clicking on Invoke. If you've entered the preceding example, and uncommented the hardcoded package values, you will receive the result shown in Figure 13- 3.
Figure 13-2: Testing a Web Service method
Figure 13- 3: AWeb Service response
At this point you'll probably start to wonder if your Web Service has worked at all. However, on close examination, it turns out that the appropriate information is present; it's just been marked up in a special XML format. What you have received is a translated version of the ClientPackageInfo class. The class is marked with a beginning and an ending tag, and inside are the members, including a PackageID and a DeliveryDate field.
You don't need to understand the format of this information if you are programming in Visual Basic .NET. As you'll discover later in this article, .NET provides special utilities that abstract away this layer of XML. These features allow you to call a Web Service and retrieve its data as thought it were a local function inside your application. However, understanding this format can give you some additional insight into what's really going on with Web Services.
The Open Standards Plumbing
Much of the excitement over Web Services results from the fact that they are built on open standards. It's this foundation that makes them more flexible and extensible than previous attempts at allowing distributed component-based programming, including such existing standards as DCOM (Microsoft's own Distributed COM), and RMI (Java's Remote Method Invocation).
XML and WSDL
Web Services use remote function calls written in XML language. XML language is ideally suited to Web Services because it is text-based, which means that unlike binary data, for instance, it can easily flow over normal HTTP channels on the Internet without getting stopped by corporate firewalls. XML is also excellent because it is self-describing, and it provides a way to identify (or "mark up") information.
XML, however, is only the starting point. XML is just a tool for describing data, much as SQL is a tool for accessing databases. Both are generic, and both can be used in countless different ways. What is needed is an agreed-upon standard for encoding information in XML, guaranteeing that other clients will be able to decode the information by following a uniform set of rules.
The standard way of describing your .NET Web Services is WSDL, an XMLbased language that has been accepted by Microsoft, IBM, and a host of other vendors. If you want to find out all the low-level details of WSDL, you can read up on it at http://msdn.microsoft.com/xml/general/wsdl.asp. However, for most developers, these details won't hold any more interest than the kinds of technology that underlie many of the other aspects of the .NET platform. What is more interesting is examining the WSDL information that Visual Basic .NET generates automatically for your particular Web Service. To display this information, click on the Service Description link on the Internet Explorer Web Service test page. You'll see a lengthy-and perhaps intimidating-document that describes the types and the functions used in your Web Service.
A portion of the WSDL document for the PostalWebService is shown in Figure 13- 4.
Figure 13- 4: Part of the WSDL document describing a Web Service
WSDL describes your Web Service, but another standard is needed to communicate with it. In fact, there are three different ways to communicate with a Web Service. The first is HTTP GET, which Internet Explorer uses automatically when you click on Invoke on your test page. The second is HTTP POST, which is very similar to HTTP GET. Internet veterans will realize that a POST request sends information in the body of an HTTP request instead of in the query string. The final method is SOAP, which is what .NET will use transparently when you create a client later in this article.
SOAP is another XML-based standard, and it predates the .NET platform. Essentially, when you send information to and retrieve information from your Web Service in a .NET application, your requests and responses are packaged in the SOAP format. The SOAP format looks similar to the HTTP response we got before, but it is not identical. The test web page shows the actual format for SOAP and HTTP requests and responses when you click on a method.Accessing a Web Service Directly
Now that you understand a little bit about the standards underlying Web Services, you may realize that you don't really need to go through the Internet Explorer test page, although it is very convenient.
To see the WSDL contract for a Web Service, just add ?WSDL after the filename in your Internet browser. This works for any .NET Web Service, including those that have been created by other developers. The Web Service WSDL contract for the PostalWebService can be retrieved with this line (assuming it's in a virtual directory called NoStarchWeb on the local computer):
You can also interact with the Web Service through HTTP GET by typing the parameter list into the URL. In fact, if you enter the value 221 for the Get- PackageInfo function and click Invoke, this is what Internet Explorer links to:
In other words, Internet Explorer just passes the function name and the TrackID parameter as part of an HTTP GET request. At this point, you might start to realize that if communicating with Web Services is this straightforward, it really is possible to access them on different operating systems and platforms.
When IIS receives a web request like the one shown above, it passes it to the ASP.NET worker process, which then creates the Web Service. The Web Service runs the appropriate function, returns the result as an XML page, and is destroyed. The end result appears as a page in your Internet browser.
The next section looks at how .NET applications consume Web Services by using SOAP calls, which allows you to retrieve the results of a Web Service in a .NET program instead of a browser.
Part 2 will appear tomorrow.
Matthew MacDonald, an author, educator and MCSD developer, has worked with Visual Basic and ASP since their inceptions. He is the author of "The Book of VB .NET" (No Starch Press) and "ASP.NET: The Complete Reference" (Osborne McGraw-Hill) and co-author of "Programming .NET Web Services" (O'Reilly).