Microsoft .Net XML Web Services: Step by Step by Adam Freeman, Allen Jones

From the Publisher

Teach yourself how to write and deploy XML Web services for Microsoft .NET-one step at a time. XML Web services can vastly simplify application integration and interoperability, but developing them requires an understanding of many different programming techniques and technologies. This step-by-step tutorial delivers expert, task-based instruction designed to help you apply what you already know about C#, Microsoft Visual Basic(r), and other object-oriented programming (OOP) languages to XML Web services development-at the pace that best suits you. Topics include XML Web services architecture; writing, testing, and debugging Web services; and consuming Web services asynchronously through clients or with HTTP; and advanced topics such as managing Web service state, security, SOAP, and .NET remoting. The book features skill-building lessons and practice exercises, with plenty of examples in both the C# and Visual Basic .NET languages.

Product Details

• Table of Contents
• Read a Sample Chapter

Table of Contents

Read a Sample Chapter

• Proxy Classes and Web References
  • Creating a Web Reference
  • Renaming the Web Reference
  • Viewing the Web Reference Files and Properties
  • Using a Proxy Class
• XML Web Service Clients
  • Creating the Windows Forms Client
  • Creating the Web Forms Client
  • Creating the Console Client
  • Chapter 4 Quick Reference

4   Building a SOAP Client

In this chapter, you will learn how to:

• Automatically create a proxy class by setting a Web reference in Microsoft Visual Studio .NET.

• Manage Web references in Visual Studio .NET.

• Create a Windows Forms client that uses a proxy to consume an XML Web service.

• Create a Web Forms client that uses a proxy to consume an XML Web service.

• Create a console client that uses a proxy to consume an XML Web service.

The purpose of the XML Web service model is to support program-to-program communications. The consumer of an XML Web service can be any type of application. A Windows application, a server process, or another XML Web service are just some of the possibilities. XML Web service consumers do not need to know the details of the platform or language used to implement the XML Web service; the only requirement is that the consumer be able to formulate requests and process responses using the correct protocol and message structure. The protocol and message structure used by an XML Web service is defined in a service description document written in Web Service Description Language (WSDL).

XML Web services created in ASP.NET support the following three protocols for communicating with consumers:

• Simple Object Access Protocol (SOAP)

• HTTP-GET

• HTTP-POST

SOAP is the most common XML Web service communication protocol; it is more complex than the HTTP protocols but provides more capabilities. This chapter focuses on clients that use the SOAP protocol. We discuss the HTTP-GET and HTTP-POST protocols in Chapter 5, "Building an HTTP Client."

SOAP is an XML-based protocol that provides a way of encoding and packaging data for transmission across a network that is independent of language, platform, and vendor. A client can use SOAP to communicate with any XML Web service, even one not developed and running on the Microsoft .NET platform. In addition to interoperability, SOAP supports the encoding of complex data types. We discuss this in Chapter 6, "Data Types and XML Web Services."

Proxy Classes and Web References

Although the structure and syntax of SOAP are fundamentally simple, trying to manually encode complex data as SOAP messages can result in long and confusing XML documents. Constructing and processing SOAP messages is a tedious and error prone process that requires high attention to detail. Any deviation from the SOAP message structure defined in the service description of an XML Web service can result in communications failure.

Proxy classes remove the need for the programmer to manipulate SOAP messages directly. A proxy is a normal .NET Framework class with methods that mirror the functionality exposed by an XML Web service. Each proxy method takes the same number and type of arguments and returns the same data type as its XML Web service equivalent. For example, the proxy class for the VISAValidator service from Chapter 3 would have a ValidateVISA method that takes a String argument and returns a Boolean value, just as the service does.

To invoke the XML Web service’s functionality, a client application simply calls the proxy class method. The proxy class takes care of all communications with the XML Web service and returns the response it receives from the service. To the client application, the XML Web service invocation appears to be a local method call, while in reality the call could be serviced by an XML Web service anywhere on the Internet. The following diagram illustrates the role of the proxy; the client application is oblivious to the activity that goes on once the call is made to the proxy method.

(Image Unavailable)

The use of proxies takes the complexity of SOAP processing out of your application code. Better still, because XML Web service interfaces are defined using WSDL, Visual Studio .NET can automatically generate proxy classes without you having to write a single line of code.

NOTE:
You can also create proxy classes using the Wsdl.exe command line tool supplied with the .NET Framework Software Developer’s Kit (SDK). Using Wsdl.exe provides greater control over the functionality of the generated proxy, but you lose the seamless integration provided by Visual Studio .NET that makes development so straightforward. We discuss the Wsdl.exe utility in Chapter 16, "Manually Creating Proxies."

Creating a Web Reference

In Visual Studio .NET, you generate a proxy class for use in your project by creating a Web reference that points to the XML Web service that you want to use. To demonstrate how to generate a proxy, in the following procedure we will create a new Visual Studio .NET project using the Windows Application project template. We will not develop any functionality for this application; we just want to demonstrate the process of proxy creation. Later in this chapter, we will use this process to create three real XML Web service client applications.

Create a Web Reference

1. Create a new C# or Visual Basic .NET project using the Windows Application project template. Give the project the name ProxyTest and enter a suitable path as the project’s location. We will use C#. Whichever language you choose, create the project at C:\XMLWebServicesSBS\Projects\Chapter04.

   (Image Unavailable)

2. In Solution Explorer, right-click on the ProxyTest project’s References folder and choose Add Web Reference from the shortcut menu.

   (Image Unavailable)

3. In the Address text field at the top of the Add Web Reference dialog box, enter for the VISAValidator service that we created in Chapter 3. Ignore the text in the Add Web Reference dialog box that discusses UDDI and DISCO. We discuss these topics in Chapter 9, "Publishing and Discovering XML Web Services."

4. Press Enter or click the Go button to the left of the Address field. You will see the service help screen for the VISAValidator XML Web service in the left pane of the Add Web Reference dialog box.

   (Image Unavailable)

5. Click the Add Reference button.

Renaming the Web Reference

You now have a proxy for the VISAValidator XML Web service based on the Web reference you just created. However, you will see that the name assigned to the Web reference is the same as the name of the server that hosts the XML Web service, which is most likely localhost. Together, the project name and the Web reference name form the namespace assigned to the proxy class (in our example, ProxyTest.localhost). It is common practice to rename the Web reference to more appropriately reflect the function of the XML Web service.

Rename the Web Reference

1. In Solution Explorer, right-click on the Web reference we just added and select Rename from the shortcut menu.

   (Image Unavailable)

2. Enter ValidatorService as the new name for the Web reference.

3. Press Enter.

   Visual Studio .NET updates the name of the Web reference and makes the necessary changes to the underlying proxy class files.

Viewing the Web Reference Files and Properties

We aren’t interested in examining the contents of a proxy class in detail. These files are automatically created and managed by Visual Studio .NET and should not be edited manually. However, you should become familiar with the files Visual Studio .NET creates and know what their purpose is. You’ll also need to configure the three properties that a Web reference contains. The following procedures show you how to accomplish this.

View the Files

1. In Solution Explorer, click the Show All Files button.

2. Fully expand the folder tree below the ValidatorService Web reference. You’ll see the Web reference files displayed as shown here.

(Image Unavailable)

The following table lists the Web reference files:

View the Web Reference Properties

1. In Solution Explorer, select the entry for the ValidatorService Web reference.

2. Press F4 to display the property page for the ValidatorService Web reference, shown here.

   (Image Unavailable)

The following table lists the three properties of a Web reference.

Using a Proxy Class

Once we’ve created a proxy class, the steps necessary to use it are straightforward. Access to an XML Web service occurs just like access to any other class. If the XML Web service referenced by a Web reference is modified, you need to update the proxy class to reflect the changes. This process is automated through Visual Studio .NET. The following procedures show you the basic steps for performing these tasks. We will demonstrate these again in the context of real client applications (with complete code samples) later in this chapter.

Enable a proxy class

1. Add the following statement to your client application to import the namespace for the proxy class.

   C#

   using ProxyTest.ValidatorService;

   Visual Basic .NET

   Imports WindowsFormsClient.ValidatorService

2. Instantiate the proxy class.

   The proxy instance is stateless and thread safe; multiple objects and threads can use the proxy repeatedly. Alternatively, you might want to instantiate the proxy each time you use it, although this isn’t an efficient technique.

   C#

   VISAValidator x_validator = new VISAValidator ();

   Visual Basic .NET

   Dim x_validator As VISAValidator = New VISAValidator ()

3. Call the methods of the proxy class.

   As you do with any other method, you need to provide the necessary arguments and process any results. Proxy methods can throw exceptions, which we discuss in Chapter 7, "Exception Handling."

   C#

   x_validator.ValidateVISACard("0123 4567 8901 2345");

   Visual Basic .NET

   x_validator.ValidateVISACard("0123 4567 8901 2345")

Update a Proxy Class

1. In Solution Explorer, right-click on the Web reference.

2. From the shortcut menu, select Update Web Reference.

   Visual Studio .NET retrieves the WSDL file for the XML Web service and updates the proxy class code. You will, of course, need to update your own client code to deal with any changes made to the proxy methods.

   (Image Unavailable)

Proxy class functionality
For every method exposed by the referenced XML Web service, the proxy class contains three methods. One method supports synchronous communications with the XML Web service, and the other two support asynchronous communications. We demonstrate synchronous communications in this chapter and discuss asynchronous use of XML Web services in Chapter 15, "Consuming XML Web Services Asynchronously." The three method names always follow the same form: WebMethodName, BeginWebMethodName, and EndWebMethodName. The following table summarizes the methods contained in the VISAValidator proxy class.

XML Web Service Clients

After creating the VISAValidator XML Web service in Chapter 3, we validated a VISA card number using the simple Internet Explorer interfaces made available by ASP.NET. These interfaces provide an excellent testing tool, but they are not suitable for general use.

Armed with the knowledge of how to create a proxy class, we are ready to build custom applications that interact with XML Web services. Using a proxy class offers great flexibility and is applicable whether you’re developing a large e-commerce system or a simple Windows application. To demonstrate the use of proxy classes, we will develop three different types of client applications that validate VISA credit card numbers using the VISAValidator service from Chapter 3:

• A Windows Forms application

• A Web Forms application

• A console application

Although the interfaces and application architectures differ significantly among these clients, all three provide the same functionality and use the proxy class in the same way to interact with the VISAValidator service. Each application will do the following:

1. Provide an area in which a user enters a credit card number and starts the validation process.

2. Instantiate a proxy for the VISAValidator XML Web service.

3. Call the ValidateVISACard method of the new proxy object, passing in the credit card number requiring validation.

4. If the ValidateVISACard method returns true, display the message "Number Valid"; otherwise the message "Number Invalid" is displayed.

Creating the Windows Forms Client

We will start by creating a Windows Forms client for the VISAValidator XML Web service. Once we have the WindowsFormsClient project structure in place, we’ll need to create the user interface, a step we’ll take with a number of applications throughout the book. The client in this example consists of a single form containing five controls. In this section, we will provide complete instructions for how to configure the form and the controls it contains. In future examples, we will provide details about the form and controls to use in a table similar to the one in this example, but we will not provide details about how to construct the form. The Windows Forms controls we use are all available on the Visual Studio .NET toolbox.

Once we complete the user interface for WindowsFormsClient, we’ll demonstrate how to implement the functionality behind the interface and then build and test the client.

Create the Windows Forms Project

1. Create a new Visual Studio .NET project using either the C# or Visual Basic .NET Windows Application project template. In the New Project dialog box, name the project WindowsFormsClient and specify the following location: C:\XMLWebServicesSBS\Projects\Chapter04.

   (Image Unavailable)

2. Add a Web reference pointing to the VISAValidator XML Web service that we created in Chapter 3.

   Use the process described in the section "Create a Web Reference" earlier in this chapter. The URL for this service is http://localhost/XMLWebServices/Chapter03/VisaValidator/Validation.asmx.

   (Image Unavailable)

3. In Solution Explorer, rename the Web reference ValidatorService either by selecting it and pressing F2 or by right-clicking it and selecting Rename from the shortcut menu. The following screenshot shows the WindowsFormsClient project with the renamed Web reference.

   (Image Unavailable)

Create the Windows From

1. In Solution Explorer, double-click on the source file for Form1 (either Form1.cs or Form1.vb depending on which language you are using) to open the design view for Form1.

2. Press F4 or select Properties Window from the View menu to open the Properties page for Form1.

3. Change the Text property of Form1 to VISA Validator Client.

4. Set the Size property of Form1 to 290,190.

   Here’s a summary of the changes to make to Form 1 properties.

5. Press Ctrl+Alt+X or select Toolbox from the View menu to display the toolbox.

   Using the toolbox, we’ll add Windows Forms controls (three labels, one text box, and a button) to Form1. You can either double-click the control or drag it from the toolbox onto the form. These controls allow us to interact with the VISAValidator XML Web service and display the results of credit card validation requests. Because this is the first example in this book of a user interface, we’ll provide detailed instructions for configuring each control. Form1 should end up looking like the following.

   (Image Unavailable)

6. Add a label to contain the string "Card Number:" that you can see toward the top of Form1. With the label selected, press F4 to bring up the properties page. Don’t bother changing the label’s name, but change the Text property to Card Number:, the Location property to 8,20, and the TextAlign property to MiddleRight.

7. Add a text box in which to enter the credit card number for validation. Change the text box’s Name property to CreditCardNumberText, clear the value from the Text property, and set the Location to 140,20. The text box must be long enough to allow a full credit card number to be visible when entered, so set the Size property to 120,20.

8. Add a second label to hold the "Result:" string. Set the Text property to Result:, TextAlign to MiddleRight, and Location to 8,60.

9. Add a third label to Form1; this label will display the result of a credit card validation request. Set the Name property to ResultLabel and clear the Text property value. The Location should be 140,60, and the TextAlign property should be set to MiddleLeft.

10. To complete Form1, add the final control, a button, to the bottom of the form. Set the button’s Name property to ValidateButton, the Location property to 100,110, and change the button’s Text property to Validate.

Here’s a summary of the controls we’ve added to Form1 and the properties we configured.

Implement the WindowsFormsClient functionality

1. In the Form1 design view, double-click the Validate button.

   Visual Studio .NET will show Form1 in code view and display an empty method named ValidateButton_Click, allowing you to add the code that will be executed when the user clicks the button. Add the code so that the method reads as follows:

   C#

   private void ValidateButton_Click(object sender, 
       System.EventArgs e) {
       VISAValidator x_validator = new VISAValidator ();
       bool x_valid 
           = x_validator.ValidateVISACard(CreditCardNumberText.Text);
       if (x_valid) {
           ResultLabel.Text = "Number Valid";
       } else {
           ResultLabel.Text = "Number Invalid";
       }
   }

   Visual Basic .NET

   Private Sub ValidateButton_Click(ByVal sender As System.Object, _
       ByVal e As System.EventArgs) Handles ValidateButton.Click
       Dim x_validator As VISAValidator = New VISAValidator ()
       Dim x_result As Boolean
       x_result _
           = x_validator.ValidateVISACard(CreditCardNumberText.Text)
       If (x_result) Then
           ResultLabel.Text = "Number Valid"
       Else
           ResultLabel.Text = "Number Invalid"
       End If
   End Sub

2. Scroll to the top of the code view window and add the statement required to import the namespace of the proxy class. The full list of imports should be as follows.

   C#

   using System;
   using System.Drawing;
   using System.Collections;
   using System.ComponentModel;
   using System.Windows.Forms;
   using System.Data;
   
   // imports the webservice proxy namespace
   using WindowsFormsClient.ValidatorService;

   Visual Basic .NET

   ‘imports the webservice proxy namespace
   Imports WindowsFormsClient.ValidatorService

3. Click Build Solution on the Build menu or press Ctrl+Shift+B to build the solution.

Test the WindowsFormsClient Application

1. Press F5. Visual Studio .NET will run the WindowsFormsClient application in debug mode, and you will see the VISA Validator Client form.

   (Image Unavailable)

2. Type a credit card number into the Card Number text field and then click Validate.

   If the number is valid (as shown above), you will see the message "Number Valid." However, if the number is invalid or incorrectly formatted, you will see the message "Number Invalid."

Creating the Web Forms Client

Next we will create a Web Forms client named WebFormsClient. This project is an ASP.NET application that runs from a Web server and is accessed through a browser. The great thing about developing Web Forms applications in Visual Studio .NET is that you have access to the same design time features as you do when building Windows Forms applications.

The process to develop the Web Forms client is almost identical to the process for creating the Windows Forms project, so we will move quickly. We’ll first create the WebFormsClient project structure and then create the user interface. The user interface is similar to the one we created for WindowsFormsClient. It will contain the same number and type of controls. We’ll use three labels, one text box, and a button. Don’t worry about getting the size and position of these controls exact as long as the result looks similar to the WebForm1 shown later in this section. The design modes for WebForm1 and Form1 from the WindowsFormsClient example look different because WindowsFormClient runs as a standard Windows application, while WebFormsClient runs in a Web browser.

When the user interface for WebFormsClient is complete, we will implement the functionality behind the interface. The process to test the WebFormsClient is the same as for WindowsFormsClient. However, because WebFormsClient is a Web Forms application, it runs from an IIS server using Internet Explorer.

Create the Web Forms Project

1. Create a new Visual Studio .NET project using the C# or Visual Basic .NET ASP.NET Web Application template. Web Forms applications must be hosted on IIS servers, so you need to specify the URL http://localhost/XMLWebServices/Chapter04/WebFormsClient to indicate where the project should be stored.

   (Image Unavailable)

2. Add a Web reference to the VISAValidator XML Web service. We detailed this process in the section "Create a Web Reference" earlier in this chapter.

3. Rename the Web reference ValidatorService.

Create the Web Form

1. In Solution Explorer, double-click the WebForm1.aspx entry to open WebForm1 in design mode.

   (Image Unavailable)

2. Press F4 to open the property page for the WebForm1 Document element.

3. Change the Title property of Document to VISA Validator Client.

4. Add the Web controls specified in the following table to WebForm1 and set their properties to the values listed.

Impement the WebFormsClient functionality

1. With WebForm1 in design view, double-click on the Validate button. Visual Studio .NET switches WebForm1 to code view and displays an empty method named ValidateButton_Click. Changing this method allows us to control what happens when the user clicks the Validate button.

2. Add the code so that the method reads as follows.

   C#

   private void ValidateButton_Click(object sender, 
       System.EventArgs e) {
       VISAValidator x_validator = new VISAValidator ();
       bool x_valid = 
          x_validator.ValidateVISACard(CreditCardNumberText.Text);
       if (x_valid) {
           ResultLabel.Text = "Number Valid";
       } else {
           ResultLabel.Text = "Number Invalid";
       }
   }

   Visual Basic .NET

   Private Sub ValidateButton_Click(ByVal sender As System.Object, _
       ByVal e As System.EventArgs) Handles ValidateButton.Click
       Dim x_validator As VISAValidator = New VISAValidator ()
       Dim x_result As Boolean
       x_result _
           = x_validator.ValidateVISACard(CreditCardNumberText.Text)
       If (x_result) Then
           ResultLabel.Text = "Number Valid"
       Else
           ResultLabel.Text = "Number Invalid"
       End If
   End Sub

3. Scroll to the top of WebForm1 in code view and add the necessary statement to import the namespace of the proxy class. The full list of imports should be as follows:

   C#

   using System;
   using System.Collections;
   using System.ComponentModel;
   using System.Data;
   using System.Drawing;
   using System.Web;
   using System.Web.SessionState;
   using System.Web.UI;
   using System.Web.UI.WebControls;
   using System.Web.UI.HtmlControls;
   
   // imports the webservice proxy namespace
   using WebFormsClient.ValidatorService;

   Visual Basic .NET

   ‘imports the webservice proxy namespace
   Imports WebFormsClient.ValidatorService

4. Select Build Solution from the Build menu (or press Ctrl+Shift+B) to build the solution.

Test the WebFormsClient Application

1. Press F5.

   Visual Studio .NET launches Internet Explorer and loads the WebFormsClient page.

   (Image Unavailable)

2. Type a credit card number into the Card Number text field and then click the Validate button.

   If the number is valid (as shown above), you will see the message "Number Valid." However, if the number is invalid or incorrectly formatted, you will see the message "Number Invalid."

Creating the Console Client

The last client we’ll create in this chapter is a console application. Unlike the WebFormsClient and WindowsFormsClient applications, the console application does not have a graphical user interface. To validate a credit card number, you run the ConsoleClient application and provide the credit card number as a command line argument, for example:

ConsoleClient 0123456789012345

If the credit card number is valid, you will see the message "Number Valid." Otherwise, you will see the message "Number Invalid."

You cannot test ConsoleClient within Visual Studio .NET as easily as you can the graphical applications we developed previously; the best way to test it is to open a command prompt and run it.

Create the Console Application Project

1. Create a new Visual Studio .NET project using either the C# or Visual Basic .NET Console Application project template. In the New Project dialog box, name the project ConsoleClient and specify the following location for the project: C:\XMLWebServicesSBS\Projects\Chapter04.

   (Image Unavailable)

2. Add a Web reference pointing to the VISAValidator XML Web service. We detailed this process in the section "Create a Web Reference" earlier in this chapter. The service URL is http://localhost/XMLWebServices/Chapter03/VisaValidator/Validation.asmx.

3. Rename the new Web reference ValidatorService.

4. In Solution Explorer, select the Class1.cs source file (if you are using C#) or the Module1.vb file (if you are using Visual Basic .NET) and then press the Delete key.

5. In Solution Explorer, right-click on the ConsoleClient project entry (highlighted in bold), select Add followed by Add Class from the shortcut menu. We are going to create a class in which we will implement the functionality that calls the VISAValidator XML Web service.

   (Image Unavailable)

6. From the Templates pane on the right side of the Add New Item dialog box, select Class and then type ConsoleClient in the Name text field.

   (Image Unavailable)

7. Click Open.

   A new entry appears in Solution Explorer for the ConsoleClient class file, which contains a very simple class declaration.

   (Image Unavailable)

Implement the ConsoleClient functionality

1. Delete all of the autogenerated code in the ConsoleClient source file (ConsoleClient.cs if you’re using C#, or ConsoleClient.vb if you’re using Visual Basic .NET).

2. Insert the following code.

   C#

   Visual Basic
   End Module

3. Build the ConsoleClient project by pressing Ctrl+Shift+B or selecting Build Solution from the Build menu.

Test the ConsoleClient application

1. On the Windows taskbar, click Start and then select Run.

2. In the Run dialog box, type cmd in the Open text field and then click OK.

3. In the Command console, change the current directory to the one in which the ConsoleClient.exe file is located.

   For a C# project, this is the /bin/debug directory below the project root directory. For Visual Basic .NET, the file is located in the /bin directory below the project root. In our C# example, ConsoleClient.exe is located in the C:\XMLWebServicesSBS\Projects\Chapter04\
   ConsoleClient\bin\Debug directory.

4. Run the ConsoleClient application and pass it the number of the VISA card you want to validate, as shown here:

   ConsoleClient 4921835221552042

   Because the number 4921835221552042 is a valid VISA card number, validation will succeed and you will see the "Number Valid" message.

Chapter 4 Quick Reference