Unlike Active Server Pages, web services are not designed to be viewed in a browser. Instead, web services are consumed by a client application using protocols such as HTTP GET/POST, SMTP, or SOAP over HTTP (see Chapter 3 for more information on consuming web services). Some of these protocols, such as SOAP, are more appropriate for server-to-server communication, while others, such as HTTP GET, are more frequently associated with the model of traditional web page access.
A web service that uses HTTP GET as a transport protocol can be accessed in much the same way as a regular web page. All that is necessary to access such a page is to point a web browser to the service endpoint. In our example, the endpoint comes is an .asmx page. But how do you know which protocols
HelloWorldService will support, since there is no mention of HTTP or SOAP in the example code? The answer is that, by default, all .NET web services try to support HTTP GET, HTTP POST, and SOAP. We say "try," because in many cases the web service may be too complex for HTTP GET support. Additionally, because web services are applications that expose functionality to web service clients, and as a result have no required graphical user interface, .NET provides a canned web service test page that is displayed when you point your browser to an .asmx page. If you open a browser and type in the URL of the .asmx web service you just created, you'll see the IE test page shown in Figure 2-5.
The page in Figure 2-5 is generated by the .NET HTTP runtime each time it receives a request for an .asmx page. The page template is itself an ASP.NET .aspx page named DefaultWsdlHelpGenerator.aspx and is stored in the \WINNT\Microsoft.NET\Framework\[version]\Config directory on the server that hosts the web service. This page operates just like any other .aspx page (remember that this is the extension for ASP.NET pages) and can be easily customized.
The test page displays the HelloWorldService service name along with the
HelloWorld() method and a link to the service description. The service name and any additional information about this service are retrieved through a process called reflection, which uses the
System.Reflection namespace to reveal information about existing types via metadata. In fact, if you look at the
Page_Load function for the DefaultWsdlHelpGenerator.aspx page (again, in the \WINNT\Microsoft.NET\Framework\[version]\Config directory on the hosting server), you'll see how this process works. If our service contained additional methods that were callable via HTTP, they would be listed as links here as well.
The runtime also automatically creates a service description from the .asmx page, an XML document that conforms to a specification called Web Service Description Language, or WSDL (pronounced "Wiz-Duhl"). If you click the service description link, you'll see the WSDL page. This page can also be viewed in a browser by appending ?WSDL to the page URL, as in HelloWorldService.cs.asmx?WSDL. The service description for our service is shown in Figure 2-6.
You can see that the WSDL document includes information about the service namespaces, protocols supported, data types used, and web methods exposed in an XML-based format. This type of information is particularly important for an application looking to use our service, as you'll see in the next chapter.
The WSDL specification is a linchpin of sorts for the various web service development platforms. As you'll see in Chapter 11, where you'll learn about web service interoperability, web service development platforms must all abide by the same version of WSDL as well as the same version of SOAP if they are to work together (actually, WSDL is not an absolute requirement, but it is necessary for automatic proxy generation, as you'll see in Chapter 3). The version of WSDL we discuss in this book, 1.1, is currently supported by .NET and most other web service implementations (e.g., SOAP::Lite, Apache Axis). The .NET Framework currently implements SOAP 1.1.
Getting back to the service test page: if you mouse over the HelloWorld link, you'll see the destination URL:
By clicking this link, you call the .asmx page, passing a parameter called
op (standing presumably for operation) along with the name of the service. This action is the same as calling the
HelloWorld web method of the web service using HTTP GET. The output page is shown in Figure 2-7.
Here you'll see the name of the service and method along with a button to test the service. Through reflection, the logic in the DefaultWsdlHelpGenerator.aspx test page is able to determine the signature of our
HelloWorld method. Because our web method takes no arguments, the page need provide only a button for invocation. If our method had a different signature--for example, if it reads a string of text--the .aspx help page would also provide a text box to capture this string and pass it, using HTTP GET, to the web method when the form was submitted. This text box method works fine for simple data type arguments, but if the web method were to require an object, this approach would not work.
Beneath the Invoke button, there are also sample service interactions for SOAP, HTTP GET, and HTTP POST. We'll talk about some of the other methods of consuming web services in Chapter 3, but for now, note that on the source, the page is still using HTTP GET to invoke our service.
<form action='http://localhost/HelloWorldService/HelloWorldService.cs.asmx/HelloWorld' method="GET"> ... </form>
You can invoke the web method using the IE test page by opening a web browser and navigating to the service's URL. You will see a page listing the service's operation, which should be HelloWorld. Click the HelloWorld operation to navigate to the web method invocation page. This is a page that allows you to test the operation by clicking a button labeled Invoke. Click the button to invoke the service.
Invoking the example service produces the results shown in Figure 2-8.
You know that web services are a means of communicating between servers using XML, so it should come as no surprise that the output of our service is nothing more than an XML document--and a short one at that! Had you used SOAP to access the service, you would have received a message in SOAP format; however, since IE isn't designed to either write or read SOAP messages by itself, you're limited to using HTTP GET and POST.
The response document begins with the following XML declaration:
<?xml version="1.0" encoding="utf-8" ?>
which identifies the document as an XML document and identifies the encoding of the document to be UTF-8 Unicode. While the encoding type may vary, all XML processors are required to support UTF-8 and UTF-16 Unicode encodings.
The first and only element in the output document is an element called
string, which contains the output of our method and has one attribute called
This namespace declaration specifies that all unprefixed elements in this document come from the namespace
In the next installment, learn about the WebService attribute.
Alex Ferrara is Chief Technology Officer at U-Inspire, a provider of on-line business training and motivational services, and head of Boston Technical, a consulting arm of U-Inspire that specializes in .NET application development.
Matthew MacDonald is a developer, author, and educator in all things Visual Basic and .NET. He's worked with Visual Basic and ASP since their initial versions, and written over a dozen books on the subject, including The Book of VB .NET (No Starch Press) and Visual Basic 2005: A Developer's Notebook (O'Reilly). His web site is http://www.prosetech.com/.