XML Web services are, depending on your point of view, a breath of fresh air after the complexities of Microsoft .NET Remoting or a simplified approach to distributed code execution that lacks a few key features. Both arguments contain at least a grain of truth. More accurately, XML Web services represent a new approach to distributed architecture, one that favors simplicity, best design practices, and cross-platform use over raw communication speed. XML Web services provide a simple, robust, and flexible way to make a remote procedure call (RPC). Most introductory .NET books provide a brief introduction to XML Web services and describe some of the underlying standards such as WSDL and SOAP. This chapter takes a more practical approach. We start with a quick introduction to XML Web services, examine how the technology differs from .NET Remoting, and consider where XML Web services fit into the design of an enterprise application. We also examine how you can make use of ASP.NET platform services in an XML Web service, publish the availability of an XML Web service, and consume XML Web services from other platforms.

Sample Chapter from the book: Microsoft® .NET Distributed Applications: Integrating XML Web Services and .NET Remoting

The Role of XML Web Services in a Distributed System

XML Web services, like any other type of middle-tier component, do not provide any type of user interface. They are used exclusively by other applications and are never invoked directly by end users. For example, you might create a package or a stock quote lookup XML Web service and then call this XML Web service from an ASP.NET Web application or a desktop Windows client.

.NET XML Web services are often identified as ASP.NET Web services because they represent an extension of the ASP.NET platform. In ASP.NET, every Web page acts like an individual application that runs briefly on the Web server when requested and returns an XML result over HTTP. ASP.NET is optimized for this task and uses multiple worker threads, automatic process recycling, output caching, and other enterprise-level features to ensure it can handle a large volume of clients. XML Web services work in much the same way as Web pages: They run briefly on the Web server and return a result in an XML markup (generally as a SOAP message). Much as ASP.NET Web pages create the illusion of a continuously running Web application, XML Web services can create the illusion of a stateful object. In reality, however, XML Web services are stateless components that are created and executed just-in-time when a client invokes an XML Web service method. This is one of the most dramatic departures from .NET Remoting, which provides the flexibility to allow singleton and client-activated objects that remain in memory under a set lease lifetime policy.

.NET Remoting vs. XML Web Services

Here’s a quick overview of the major differences between the XML Web service and .NET Remoting technologies:

• XML Web services are more restricted than objects exposed over .NET Remoting. An XML Web service works in a similar way to a SingleCall .NET Remoting object. It isn’t possible to create a singleton or a client-activated object.
• Because of the restricted nature of XML Web services, the design issues are simplified. XML Web services are generally easier to create than remotable components (and easier to design well).
• Communication with .NET Remoting can be faster than XML Web service communication if you use a binary formatter. XML Web services support only SOAP message formatting, which uses larger XML text messages.
• XML Web services support open standards that target cross-platform use. For example, each .NET XML Web service has an associated WSDL document that describes how a client can interact with the service. Therefore, any client that can parse an XML message and connect over an HTTP channel can use an XML Web service, even if the client is written in Java and hosted on a UNIX computer.
• XML Web services are designed for use between companies and organizations. They can use a dynamic discovery mechanism or a UDDI registry that "advertises" services to interested parties over the Internet.
• XML Web services don’t require a dedicated hosting program because they are always hosted by ASP.NET. That also means that they gain access to some impressive platform services, including data caching, Web farm–ready session state management, authentication, and an application collection for global, shareable objects. These features, if required, can be extremely difficult to re-create by hand in a component exposed through .NET Remoting.
• Because XML Web services work through Microsoft Internet Information Services (IIS) and ASP.NET, they can communicate with clients using the default HTTP channel (usually port 80). This means that consumers can use XML Web services just as easily as they can download HTML pages from the Internet. There’s no need for an administrator to open additional ports on a firewall.

XML Web Service Plumbing

Table 5-1 XML Web Service Technologies

So how do all these standards fit together? We’ll begin with the process of creating the XML Web service, which can be summarized in three steps:

1. Create a dedicated virtual directory to host the XML Web service on your Web server, using IIS.

2. Code the custom XML Web service class, using the <WebMethod> attribute to mark each method that should be remotely callable. At its simplest, the XML Web service class is a collection of stateless methods. .NET takes care of the communication infrastructure that allows the client to discover and call these methods.

3. Deploy the XML Web service files to the virtual directory.

The second step is for the client to find and use your XML Web service:

1. The client finds the XML Web service, either through a predetermined URL or by using a discovery document or the UDDI registry.

2. The client requests the WSDL document that describes the XML Web service. .NET creates this document quickly and automatically by examining your XML Web service.

3. The client generates a proxy class based on the WSDL document. If the client is written using .NET, this step is performed automatically.

4. The client uses the proxy class much as it would use an XML Web service class if it were instantiated in the local process. Behind the scenes, the proxy sends a SOAP message to the XML Web service and receives a SOAP message result. The proxy class handles the Internet communication and SOAP formatting automatically (as shown in Figure 5-1).

   

   Figure 5-1 XML Web service interaction

This process is similar to .NET Remoting in several respects. First of all, the client communicates using a proxy class. The proxy class mimics the XML Web service and handles all the low-level details. Many programming platforms, including .NET, provide tools that create this proxy automatically.

The key difference is in how the proxy class is created. With .NET Remoting, the proxy object is generated dynamically. As soon as a .NET client instantiates a remote object, the runtime springs into action, creating the proxy based on the information in the assembly that describes the remote class. With XML Web services, the proxy class is created using the information found in the WSDL document. This is similar to the type of information contained in the assembly metadata, but it’s stored in a cross-platform, human-readable XML format.

Another difference is the fact that the XML Web service proxy class is created during the development cycle. If the XML Web service changes, the proxy class must be manually regenerated. This process sidesteps the headaches required with .NET Remoting, where the client always needs a reference to the assembly that describes the remote component (or a supported interface). The WSDL document also contains enough information for non-.NET clients to communicate with the XML Web service on their own, without requiring a proprietary tool. We’ll look at this issue at the end of the chapter.

The Role of IIS

IIS is the software that allows your computer to become a Web server and allows remote clients to download HTML pages (or run ASP.NET pages). IIS is included with Microsoft Windows 2000, Windows XP, and Windows .NET Server, but it isn’t necessarily installed by default. To ensure that your computer has IIS installed, try typing the following into your Web browser: http://localhost/localstart.asp.

Here, localhost is the special "loopback" alias that always refers to the current computer. (Alternatively, you can use the specific server name or IP address.) localstart.asp is a traditional ASP file that is stored in the root directory of your computer’s Web site home directory. If you receive an error when you attempt this request, you should check to make sure you have IIS installed.

To install IIS, follow these steps:

1. From the Start menu, choose Settings, Control Panel.

2. Select Add Or Remove Programs, and then click Add/Remove Windows Components.

3. Select Internet Information Services in the list, and click Next to install the appropriate files.

You must install IIS on your development computer even if the XML Web service will ultimately be hosted on a different Web server.

For those who aren’t familiar with IIS, here are the key fundamentals you need to understand before you can create XML Web services:

• IIS provides access to the Web server through virtual directories.   If you want to provide access to the C:\MyWeb directory, for example, you might create a virtual directory http://[ComputerName]/MyWeb. In this example, the virtual directory name (MyWeb) is the same as the physical directory name, but this isn’t required. If your computer is accessible over the Internet (or an intranet), clients can browse to a Web page in the virtual directory. For example, you can view the HTML page C:\MyWeb\index.html by requesting http://[ComputerName]/MyWeb/index.html.
• Virtual directories don’t have the same permissions as normal directories.   By default, remote clients aren’t allowed to browse the virtual directory, run executables, create files, or download restricted file types (such as Microsoft Visual Basic source code files). You can configure some of these settings using IIS Manager and add further restrictions such as authentication requirements.
• IIS handles your computer’s Internet exposure.   However, it doesn’t run ASP or ASP.NET pages or XML Web services. Instead, IIS maintains a list of registered file extensions. For example, ASP.NET pages (ASPX files) and XML Web services (.asmx files) are registered to the ASP.NET worker process. If IIS receives a request for one of these file types, it hands the work off to the ASP.NET worker process, which handles the rest of the work.

Creating a Virtual Directory

Luckily, creating your own virtual directory is easy. Follow these steps:

1. Create the physical directory on your hard drive.

2. Start IIS Manager by choosing Settings, Control Panel, Administrative Tools, Internet Services Manager from the taskbar.

3. Start the Virtual Directory Wizard in IIS Manager by right-clicking on the Default Web Site item (under your computer in the tree) and choosing New, Virtual Directory from the shortcut menu.

4. Click Next to get started. Specify the alias, which is the name that your virtual directory will have for Web requests. Click Next to continue.

5. Specify the physical directory that will be exposed as the virtual directory. Click Next to continue.

6. The final wizard window gives you the chance to adjust the virtual directory permissions. The default settings allow clients to run ASP.NET pages and XML Web services but not make any modifications or upload files. This is the recommended configuration.

7. Click Next, and then click Finish to end the wizard. You will see the virtual directory in the IIS Manager tree display (as shown in Figure 5-2). After you have created a virtual directory, you can create a Web project in it using Visual Studio .NET.

Figure 5-2 IIS Manager

The XML Web Service File Format

The following sample .asmx file indicates that the XML Web service class called MyWebService can be found in a separate MyWebService.vb code file. ASP.NET is gracious enough to compile this file automatically when needed (a service that ordinary .NET components don’t provide).

<%@ WebService Language="VB" Codebehind="MyWebService.vb"
    Class="MyWebService" %>

And here’s a more typical example that indicates that the XML Web service class is named MyWebService and is already compiled into a DLL assembly called MyAssembly:

<%@ WebService Language="VB" Class="MyWebService,MyAssembly" %>

Most developers will program XML Web services with Visual Studio .NET. In this case, the .asmx file is created automatically. (In fact, Visual Studio .NET doesn’t even display the contents of .asmx files in the integrated development environment [IDE], but if you use Notepad to examine these files, you’ll see content similar to what’s shown here.) Visual Studio .NET also compiles all the XML Web service classes in the project into a single DLL assembly. Therefore, when it comes time to deploy the completed project to a production Web server, all you need to do is copy the individual .asmx files and a single DLL assembly. You can safely leave the Visual Basic source code files behind.

Creating an XML Web Service

<WebMethod()> _
Public Sub AddCustomer(ByVal customer As CustomerDetails)
    ’ (Code omitted.)
End Sub

Optionally, you can set additional <WebMethod> properties to configure a text description for each Web method, which can help the client understand how your service works. You can also add a <WebService> attribute to your class declaration (although this isn’t strictly required) to set a description for the entire service and associate an XML namespace with your service.

Listing 5-1 shows an example of the CustomerDB service provider component redesigned as an XML Web service. The differences are highlighted.

Imports System.Web.Services
Imports System.Data.SqlClient
Imports System.Data
 
‘ The XML namespace is not related to a .NET namespace.
‘ It simply associates a unique identifier that can be used 
‘ to describe your service in the WSDL document.
‘ Typically, you will use a URL that you control.
<WebService(Namespace:="http://www.prosetech.com/", _
 Description:="Methods to interact with the Customers table.")> _
Public Class CustomerDB
 
    Private ConnectionString As String = _
     "Data Source=localhost;Initial Catalog=Store;" & _
     "Integrated Security=SSPI"
 
    <WebMethod(Description:="Add a new customer record.")> _
    Public Sub AddCustomer(ByVal customer As CustomerDetails)
 
        Dim Sql As String = "INSERT INTO Customers "
        Sql &= "(FullName, EmailAddress, Password) VALUES (‘"
        Sql &= customer.Name & "‘, ’"
        Sql &= customer.Email & "‘, ’"
        Sql &= customer.Password & "‘)"
        ExecuteNonQuery(Sql)
 
    End Sub
 
    <WebMethod(Description:="Modify an existing customer record.")> _
    Public Sub UpdateCustomer(ByVal customer As CustomerDetails)
        Dim Sql As String = "INSERT INTO Customers "
        Sql &= "(FullName, EmailAddress, Password) VALUES (‘"
        Sql &= customer.Name & "‘, ’"
        Sql &= customer.Email & "‘, ’"
        Sql &= customer.Password & "‘)"
        ExecuteNonQuery(Sql)
 
    End Sub
 
    <WebMethod(Description:="Modify an existing customer record.")> _
    Public Sub UpdateCustomer(ByVal customer As CustomerDetails)
 
        Dim Sql As String = "UPDATE Customers SET "
        Sql &= "FullName=‘" & customer.Name
        Sql &= "‘, EmailAddress=‘" & customer.Email
        Sql &= "‘, Password=‘" & customer.Password
        Sql &= "‘ WHERE CustomerID=" & customer.ID.ToString()
        ExecuteNonQuery(Sql)
 
    End Sub
 
    <WebMethod(Description:="Delete an existing customer record.")> _
    Public Sub DeleteCustomer(ByVal customerID As Integer)
 
        Dim Sql As String = "DELETE FROM Customers WHERE CustomerID="
        Sql &= customerID.ToString()
        ExecuteNonQuery(Sql)
 
    End Sub
 
    ’ This private method is not remotely callable.
    Private Sub ExecuteNonQuery(ByVal sql As String)
 
        Dim con As New SqlConnection(ConnectionString)
        Dim cmd As New SqlCommand(sql, con)
 
        Try
            con.Open()
            cmd.ExecuteNonQuery()
        Catch Err As Exception
            Throw New ApplicationException( _
             "Exception encountered when executing command.", Err)
        Finally
            con.Close()
        End Try
 
    End Sub
 
    <WebMethod(Description:="Retrieve a single customer record.")> _
    Public Function GetCustomer(ByVal customerID As Integer) _
     As CustomerDetails
 
        Dim Sql As String = "SELECT * FROM Customers Where CustomerID="
        Sql &= customerID.ToString()
 
        Dim con As New SqlConnection(ConnectionString)
        Dim cmd As New SqlCommand(Sql, con)
        Dim reader As SqlDataReader
        Dim Customer As New CustomerDetails()
 
        Try
            con.Open()
            reader = cmd.ExecuteReader(CommandBehavior.SingleRow)
            reader.Read()
            Customer.ID = reader("CustomerID")
            Customer.Name = reader("FullName")
            Customer.Email = reader("EmailAddress")
            Customer.Password = reader("Password")
        Catch Err As Exception
            Throw New ApplicationException( _
             "Exception encountered when executing command.", Err)
        Finally
            con.Close()
        End Try
 
        Return Customer
 
    End Function
 
    <WebMethod(Description:="Retrieve all customers in an array.")> _
    Public Function GetCustomers() As CustomerDetails()
 
        Dim Sql As String = "SELECT * FROM Customers"
 
        Dim con As New SqlConnection(ConnectionString)
        Dim cmd As New SqlCommand(Sql, con)
        Dim reader As SqlDataReader
        Dim Customers As New ArrayList()
 
        Try
            con.Open()
            reader = cmd.ExecuteReader()
            Do While reader.Read()
                Dim Customer As New CustomerDetails()
                Customer.ID = reader("CustomerID")
                Customer.Name = reader("FullName")
                Customer.Email = reader("EmailAddress")
                Customer.Password = reader("Password")
                Customers.Add(Customer)
            Loop
        Catch Err As Exception
            Throw New ApplicationException( _
             "Exception encountered when executing command.", Err)
        Finally
            con.Close()
        End Try
 
        ’ Now we convert the ArrayList to a strongly-typed array,
        ’ which is easier fo the client to deal with.
        ’ The ArrayList makes this possible through a handy
        ’ ToArray() method.
        Return CType(Customers.ToArray(GetType(CustomerDetails)), _
          CustomerDetails())
 
    End Function
 
    <WebMethod(Description:="Retrieve all customers in a DataSet.")> _
    Public Function GetCustomersDS() As DataSet
 
        Dim Sql As String = "SELECT * FROM Customers"
 
        Dim con As New SqlConnection(ConnectionString)
        Dim cmd As New SqlCommand(Sql, con)
        Dim Adapter As New SqlDataAdapter(cmd)
        Dim ds As New DataSet
 
        Try
            con.Open()
            Adapter.Fill(ds, "Customers")
        Catch Err As Exception
            ’ Use caller inform pattern.
            Throw New ApplicationException( _
             "Exception encountered when executing command.", Err)
        Finally
            con.Close()
        End Try
 
        Return ds
 
    End Function
 
End Class
 

Public Class CustomerDetails
 
    Public ID As Integer
    Public Name As String
    Public Email As String
    Public Password As String
 
End Class

Remember, if you aren’t designing your class with Visual Studio .NET, you also need to create the .asmx file that "advertises" the XML Web service to ASP.NET and move both files to a virtual directory. Visual Studio .NET performs these minor steps automatically.

Data Serialization

Why the discrepancy? Even though XML Web services and .NET Remoting components can both send SOAP messages, they use different formatters. Components exposed through .NET Remoting or saved to disk require the <Serializable> attribute and use the SoapFormatter class from the System.Runtime.Serialization.Formatters.Soap namespace. Web services, on the other hand, make use of the XmlSerializer class in the System.Xml.Serialization namespace. Both of these classes transform .NET objects into XML messages. The difference is that the SoapFormatter can exactly reproduce any serializable .NET object, provided it has the assembly metadata for the class. This involves some proprietary logic. The XmlSerializer, in contrast, is designed to support third-party clients who might understand little about .NET classes and assemblies. It uses predetermined rules to convert common data types. These rules, which are based on XSD and the SOAP standard, allow for the encoding of common data types, arrays, and custom structures but don’t provide any standard way to represent code (such as constructors and property procedures). Therefore, these details are ignored.

Table 5-2 lists the data types supported in XML Web services and the SOAP standard.

Table 5-2 Data Types Supported in XML Web Services

Testing the XML Web Service

Figure 5-3 The CustomerDB test page

To test a Web method, you click one of the methods. A separate window will appear, with text boxes provided for parameters and with an Invoke button. When you click Invoke, the request message is sent, the XML Web service class is created, the Web method executes, the XML Web service class is destroyed, and the result is returned as an XML document that appears in the browser. Figure 5-4 shows the result of invoking the GetCustomers method from the test page. It returns an XML structure representing an array with five customers (two of which are collapsed in the screen shot).

Figure 5-4 The result of invoking GetCustomers

It’s important to understand that this technique does not require any special functionality from your Internet browserit’s simply a convenience provided by ASP.NET. If you were to type the exact same request string into a Netscape or Opera browser, you would receive the same test page and the same XML document. The request string is actually a request to the XML Web service using HTTP GET. It identifies the XML Web service, Web method, and any required parameters:

http://[Server]/[VirtualDirectory]/[AsmxFile]/[WebMethod]?[Arguments]

Here’s the HTTP GET request required to get the list of all customers:

http://localhost/CustomerDB/CustomerDB.asmx/GetCustomers?

And here’s another HTTP GET request string; this one retrieves information for the single customer record with the CustomerID of 1:

http://localhost/CustomerDB/CustomerDB.asmx/GetCustomer?customerID=1

Note that when you use the test page, the method of communication is HTTP GET (not SOAP). This means that you won’t be able to test some methods in your browser, such as UpdateCustomer.

The WSDL Document

The WSDL document is far from compact. It’s designed to be independent of communication protocols (like HTTP) and encoding methods (like SOAP), which gives it the ability to be used with future technologies. Unfortunately, this also means that the WSDL document requires a lengthy, multipart structure. If you browse through the WSDL document for the CustomerDB XML Web service, you’ll find information about the supported methods and the custom-defined CustomerDetails class (excerpted here):

<s:complexType name="CustomerDetails">
  <s:sequence>
    <s:element minOccurs="1" maxOccurs="1" name="ID" type="s:int" /> 
    <s:element minOccurs="0" maxOccurs="1" name="Name" 
               type="s:string" /> 
    <s:element minOccurs="0" maxOccurs="1" name="Email" 
               type="s:string" /> 
    <s:element minOccurs="0" maxOccurs="1" name="Password"
               type="s:string" /> 
  </s:sequence>
</s:complexType>

Fortunately, there is little need to read the WSDL document directly. If you’re creating a .NET client, you can create a proxy class based on the WSDL document automatically. The same feat is possible with many third-party tools in non-.NET languages.

Consuming the XML Web Service

Figure 5-5 Adding a Visual Studio .NET Web reference

Figure 5-5 shows the version of the Add Web Reference dialog box that you’ll see in Visual Studio .NET 2003. In earlier versions, the window is functionally equivalent but looks a little different. Visual Studio .NET 2003 also adds a few links that allow you to easily search for UDDI Web servers and browse the information they provide.

When you click Add Reference, the proxy class is generated in the language of the current project and is added to the project. By default, however, the proxy class is hidden because it shouldn’t be modified directly. If you want to examine the proxy class, choose Project, Show All Files from the Visual Studio .NET menu. By default, the proxy class file has the name Reference.vb and is grouped under the server name in the Web References section of Solution Explorer (as shown in Figure 5-6).

Figure 5-6 The Reference.vb proxy class file

Even if you aren’t using Visual Studio .NET, you can still create the proxy class using the WSDL.exe command-line utility that is included with the .NET Framework. This utility is found in the .NET Framework directory, such as C:\Program Files\Microsoft.NET\FrameworkSDK\Bin.

The syntax for WSDL.exe is shown here. Table 5-3 describes each field.

wsdl /language:language  /protocol:protocol /namespace:myNameSpace
     /out:filename /username:username /password:password
     /domain:domain <url or path>

A typical WSDL.exe command looks something like this (split over two lines):

wsdl /language:VB /namespace:localhost 
     http://localhost/CustomerDB/CustomerDB.asmx?WSDL

This creates a CustomerDB.vb proxy class file. You can then add this file to a client project or compile to a DLL using the vbc.exe command-line compiler, as shown here:

vbc /t:library CustomerDB.vb

Table 5-3 WSDL.exe Command-Line Parameters

Examining the Proxy Class

Listing 5-2 shows a shortened version of the autogenerated CustomerDB proxy class. Notice that it includes a copy of the CustomerDetails class, which allows the client to use this type natively. The proxy class also includes specialized Begin and End versions of each Web method (as in BeginGetCustomer and EndGetCustomer), which allow the Web method to be called asynchronously. These methods, which aren’t shown here, are examined in more detail in the next chapter.

Imports System.Web.Services
Imports System.Web.Services.Protocols
Imports System.Xml.Serialization
 
Namespace localhost
    
    <WebServiceBinding(Name:="CustomerDBSoap",
     [Namespace]:="http://www.prosetech.com/"), _
     XmlIncludeAttribute(GetType(System.Object()))> _
    Public Class CustomerDB
        Inherits SoapHttpClientProtocol
        
        Public Sub New()
            MyBase.New
            Me.Url = _
 
             "http://localhost/WebServices/CustomerDB/CustomerDB.asmx"
        End Sub
 
        <SoapDocumentMethod("AddCustomer"> _
        Public Sub AddCustomer(ByVal customer As CustomerDetails)
            Me.Invoke("AddCustomer", New Object() {customer})
        End Sub
                
 
        <SoapDocumentMethod("UpdateCustomer"> _
        Public Sub UpdateCustomer(ByVal customer As CustomerDetails)
            Me.Invoke("UpdateCustomer", New Object() {customer})
        End Sub
        
        <SoapDocumentMethod("DeleteCustomer"> _
        Public Sub DeleteCustomer(ByVal customerID As Integer)
            Me.Invoke("DeleteCustomer", New Object() {customerID})
        End Sub
        
        <SoapDocumentMethod("GetCustomer"> _
        Public Function GetCustomer(ByVal customerID As Integer) _
         As CustomerDetails
            Dim results() As Object = Me.Invoke("GetCustomer", _
              New Object() {customerID})
            Return CType(results(0),CustomerDetails)
        End Function
        
        <SoapDocumentMethod("http://www.prosetech.com/GetCustomers"> _
        Public Function GetCustomers() As CustomerDetails()
            Dim results() As Object = Me.Invoke("GetCustomers", _
              New Object(-1) {})
            Return CType(results(0),CustomerDetails())
        End Function
 
        <SoapDocumentMethod("http://www.prosetech.com/GetCustomersDS"> _
        Public Function GetCustomersDS() As System.Data.DataSet
            Dim results() As Object = Me.Invoke("GetCustomersDS", _
              New Object(-1) {})
            Return CType(results(0),System.Data.DataSet)
        End Function
 
    End Class
        
    <System.Xml.Serialization.XmlTypeAttribute()>  _
    Public Class CustomerDetails
        Public ID As Integer
        Public Name As String
        Public Email As String
        Public Password As String
    End Class
 
End Namespace

Listing 5-2 The proxy class for the CustomerDB service

The proxy class gains the ability to send SOAP messages over the Internet because it inherits from the SoapHttpClientProtocol class, which provides an Invoke method. Notice that each method receives a result as a generic object, which it then converts to the expected strongly typed class or structure.

By contrast, .NET Remoting uses its own dynamic proxy mechanism. .NET Remoting proxies are created at run time, whereas XML Web service proxies are created at design time. As a side effect, if the XML Web service changes, you must first recompile the XML Web service and then regenerate the proxy class. In Visual Studio .NET, you can accomplish this quickly by right-clicking on the Web reference in Solution Explorer and choosing Update Web Reference.

Using the Proxy Class

Public Class WindowsClient
    Inherits System.Windows.Forms.Form
 
    ’ (Designer code omitted.)
 
    Private Sub WindowsClient_Load(ByVal sender As System.Object, _
      ByVal e As System.EventArgs) Handles MyBase.Load
 
        Dim DBProxy As New localhost.CustomerDB()
        DataGrid1.DataSource = DBProxy.GetCustomerDS().Tables(0)
 
    End Sub
 
End Class

Listing 5-3 A basic Windows client

Figure 5-7 Retrieving query results through an XML Web service

And here’s an example that shows how you can interact with the CustomerDetails object defined by the XML Web service:

Public Class WindowsClient
    Inherits System.Windows.Forms.Form
 
    ’ (Designer code omitted.)
 
    Private Sub WindowsClient_Load(ByVal sender As System.Object, _
      ByVal e As System.EventArgs) Handles MyBase.Load
 
        Dim DBProxy As New localhost.CustomerDB()
        Dim Customer As localhost.CustomerDetails
        Customer = DBProxy.GetCustomer(1)
        MessageBox.Show("CustomerID 1 is: " & Customer.Name)
 
    End Sub
 
End Class

Keep in mind that this is really just a remote procedure call. The XML Web service doesn’t retain any state. Therefore, even though you retain a reference to the proxy class, the actual XML Web service instance is created at the beginning of every method invocation and is destroyed at the end. This means that you can’t set instance variables or properties and expect the values to persist between method calls.

By default, the proxy sends its SOAP message over the default HTTP port used for Web traffic: 80. You can also tweak some proxy class settings to adjust this communication if needed. If you need to connect through a computer called MyProxyServer using port 80, for example, you can use the following code before you call any proxy methods:

Dim ConnectionProxy As New WebProxy("MyProxyServer", 80)
Dim DBProxy As New localhost.CustomerDB()
DBProxy.Proxy = WebProxy

Similarly, you can adjust the amount of time the proxy waits for a SOAP response before timing out and throwing an exception, as follows:

DBProxy.Timeout = 10000  ’ 10000 milliseconds is 10 seconds.

Debugging Web Services

To enable XML Web service debugging, right-click on the project in Solution Explorer and choose properties. Then under the Configuration Properties | Debugging node, choose Wait For External Process To Connect, as shown in Figure 5-8. This instructs Visual Studio .NET to load the debugging symbols when you run the XML Web service, instead of simply showing the XML Web service test page.

Figure 5-8 Configuring an XML Web service for debugging

If you’re testing a compiled client or a client in another instance of Visual Studio .NET, just be sure to start the XML Web service project first in order to debug it. If you’re creating a solution that includes both a client and an XML Web service, you can configure it to have multiple startup projects, exactly as you would with .NET Remoting. Simply right-click on the solution item in the Solution Explorer, and choose Properties. Figure 5-9 shows an example in which both an XML Web service and a client application are launched when the solution is started.

While testing an XML Web service, you might encounter the infamous "unable to start debugging on the server" error. This signals that Visual Studio .NET was able to compile the XML Web service but can’t execute it in debug mode. Unfortunately, this problem can result because of countless different reasons. One common problem occurs if you install IIS after you install the .NET Framework. In this case, you can "repair" the .NET Framework using the original setup CD or DVD. Microsoft describes this processand a number of other possible causes for this errorin a white paper at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vsdebug/html/vxtbshttpservererrors.asp. One common cause not mentioned is failing to create the virtual directory or trying to run a program after you’ve removed or modified the virtual directory. To correct these problems, modify the virtual directory settings in IIS Manager.

Figure 5-9 Starting an XML Web service and client

Another problem that can occur in Visual Studio .NET 2003 is a failure to authenticate. Visual Studio .NET 2003 attempts to access the local Web server using integrated Windows authentication, even if you have anonymous authentication enabled for the virtual directory. Thus, your virtual directory must allow both anonymous and Windows Integrated authentication. To allow for this, follow these steps:

1. Start IIS Manager.

2. Right-click the virtual directory for your application, and choose Properties. (Alternatively, you can configure authentication for all directories if you right-click the Web Sites folder and choose Properties.)

3. Select the Directory Security tab.

4. In the Anonymous access and authentication section, click the Edit button.

5. In the Authentication Methods dialog box, under Authenticated access, select Integrated Windows Authentication, as shown in Figure 5-10.

   

   Figure 5-10 Enabling Windows authentication for debugging

6. Click OK to apply your changes.

ASP.NET Platform Services

<WebService(Namespace:="http://www.prosetech.com/", _
 Description:="Methods to interact with the Customers table.")> _
Public Class CustomerDB
    Inherits WebService

By inheriting from WebService, your class gains four additional properties, as shown in Table 5-4. These features include a few heavyweights, such as authentication and caching, that we’ll return to in later chapters. These prebuilt features are so useful that in many situations you’ll find it easier to build a large-scale performance-optimal solution with XML Web services rather than .NET Remoting, even though .NET Remoting supports leaner binary communication.

Table 5-4 WebService Properties

You could also access these properties without deriving from WebService, by using the System.Web.HttpContext class.

SOAP Headers and SOAP Extensions

This chapter won’t discuss SOAP headers and extensions. However, Chapter 13 and Chapter 18 show how you can use SOAP headers to implement security in conjunction with a custom ticket-based authentication system.

Publishing an XML Web Service

Microsoft also supports a simpler discovery standard. In the current version of Visual Studio .NET, this is DISCO (which is slated for replacement by a similar standard called WS-Inspection, as mentioned earlier). A DISCO document is essentially an XML file with a list of links to one or more WSDL documents. A client using Visual Studio .NET can enter the URL for a discovery document when adding a Web reference and can easily find the required XML Web service. Essentially, a discovery document offers a simple approach to sharing XML Web service URLs in a standardized format.

A typical discovery document has the extension .disco or .vsdisco and contains one or more <contractRef> elements, each of which points to a WSDL document. It can also contain <discoveryRef> links that point to other discovery files or <schemaRef> links that point to XSD documents. Here’s an example that can allow a client to locate the CustomerDB XML Web service:

<?xml version="1.0" encoding="utf-8" ?>
<disco:discovery  xmlns:disco="http://schemas.xmlsoap.org/disco"
 xmlns:wsdl="http://schemas.xmlsoap.org/disco/wsdl">
  <wsdl:contractRef 
   ref="http://MyServer/WebServices/CustomerDB.asmx?WSDL"/>
</disco:discovery>

Note that the example doesn’t use the localhost reference because the client requires the real name of the server.

Microsoft also supports a dynamic discovery format. When a client requests this file, the Web server automatically creates a list of all the XML Web services in the given virtual directory and any subdirectories. You can specifically exclude search paths (typically to save time) by using the <exclude> attribute, although this doesn’t stop the client from adding a reference to an XML Web service in one of these directories if it is not secured through IIS.

<?xml version="1.0" encoding="utf-8" ?>
<dynamicDiscovery 
 xmlns="urn:schemas-dynamicdiscovery:disco.2000-03-17">
  <exclude path="_vti_cnf" />
  <exclude path="_vti_pvt" />
  <exclude path="_vti_log" />
  <exclude path="_vti_script" />
  <exclude path="_vti_txt" />
</dynamicDiscovery>

Cross-Platform XML Web Services

To test this technique, you can use the Microsoft XML COM library, which includes an XMLHTTP object that can send XML documents over the HTTP channel. This example (shown in Listing 5-4 and illustrated in Figure 5-11) uses Visual Basic 6 and Microsoft XML version 4 (msxml4.dll), but earlier versions will also work.

Private Sub Form_Load()
 
    Dim Transfer As XMLHTTP
    Set Transfer = New XMLHTTP
 
    ’ Call the XML Web Service using HTTP GET.
    Transfer.open "GET", _
     "http://localhost/WebServices/CustomerDB/CustomerDB.asmx/" & _
     GetCustomers", False
    Transfer.send
 
    ’ Retrieve the XML response.
    Dim Doc As DOMDocument
    Set Doc = Transfer.responseXML
 
    ’ Configure the MSFlexGrid control.
    MSFlexGrid1.TextMatrix(0, 0) = "ID"
    MSFlexGrid1.TextMatrix(0, 1) = "Name"
    MSFlexGrid1.TextMatrix(0, 2) = "Email"
    MSFlexGrid1.TextMatrix(0, 3) = "Password"
 
    ’ Parse the response.
    Dim Child As MSXML2.IXMLDOMNode
    For Each Child In Doc.documentElement.childNodes
 
      ’ The first node (offset 0) is the ID.
      ’ The second node (offset 1) is the name.
      ’ The third node (offset 2) is the email.
      ’ The fourth node (offset 3) is the password.
      MSFlexGrid1.AddItem (Child.childNodes(0).Text & vbTab & _
       Child.childNodes(1).Text & vbTab & Child.childNodes(2).Text & _
       vbTab & Child.childNodes(3).Text)
 
    Next
 
End Sub

Listing 5-4 Consuming a .NET XML Web service in Visual Basic 6

Figure 5-11 A Visual Basic 6 XML Web service client

Ideally, the client will use a slightly more advanced technique and will use SOAP messages. You can send and receive SOAP messages using the XMLHTTP object, but the client will need to shoulder the burden of manually creating the request message and processing the response. If the XML Web service changes, the client must also adapt. However, most platforms include more sophisticated tools that enable you to send SOAP messages using a higher-level abstraction and even create proxy classes by analyzing WSDL documents. Some examples include the following:

• Microsoft’s SOAP Toolkit, which works with the previous generation of Visual Studio products (such as Visual Basic and C++)
• IBM’s Web Service Development Kit
• Oracle’s Web Integration Development Language
• Sun Microsystems’s Sun ONE (Open Net Environment) offering, which now supports Web services written in the Java language
• Perl’s SOAP::Lite kit, which provides basic SOAP functionality

Summary

This chapter also touched on some topics that we won’t return to in any detail, including ASP.NET pages and IIS configuration. If you would like to learn more about the ASP.NET platform and how to configure a Web server, you might be interested in a dedicated ASP.NET book, such as my ASP.NET: The Complete Reference (Osborne McGraw-Hill, 2002). Of course, you’ll need to return to this book to learn many of the best practices to follow when you implement these features in an enterprise application.

Finally, if you would like to try interacting with a prebuilt XML Web service, the Internet provides many choices. You can try creating client applications for the following:

• Microsoft’s TerraService (http://terraservice.net), which provides a free gateway to TerraServer, the multiterabyte database of satellite photography. You can use TerraService to download satellite images and display them in your .NET applications.
• Microsoft’s MapPoint, which enables you to access high-quality maps and geographical information. MapPoint isn’t free, but you can use a free trial of the XML Web service. See http://msdn.microsoft.com/library/en-us/dnmapnet/html/mapintronet.asp for information.

The basic services are on GotDotNet (http://www.gotdotnet.com/playground/services); they include tried-and-true favorites such as the thumbnail generator, the mail sender, and the quote of the day. Best of all, you can also see the .NET implementation code for the XML Web services.

Sample Chapter from the book: Microsoft® .NET Distributed Applications: Integrating XML Web Services and .NET Remoting