Recipe 14.3. Consuming a Web Service

Problem

You need to use a web service created by another group in your company to access data your application requires.

Solution

Add a web reference to an existing ASP.NET project using Visual Studio 2005. Create an instance of the web service class in your application and call its methods.

To add a web reference to an ASP.NET project in Visual Studio 2005:

Select the project in the Solution Explorer, right-click, and select Add Web Reference from the context menu.
In the Add Web Reference dialog box, enter the URL of the web service you want to consume, as shown in Figure 14-3, set the name for the web reference, and click the Add Reference button.

Visual Studio 2005 will create all the files needed to consume the web service and will place them in the App_WebReferences folder. The files include a .disco, a .discomap, and a .wsdl file for the web service.

After adding the web reference, create an instance of the web service class and call its methods in the code-behind class for the page. Examples 14-8, 14-9 through 14-10 show the .aspx file as well as VB and C# code-behind files for an example we've written to create an instance of the web service class from Recipe 14.1 and call its methods.

Figure 14-3. Adding a web reference

Discussion

Visual Studio 2005 makes consumption of a web service easy by creating all of the plumbing for you. You don't have to worry about creating proxy classes and the SOAP messages; it's all done for you when you add a web reference.

In our example that illustrates the solution, the web service created in Recipe 14.1 is used to obtain a list of books and display the list in a DataGrid. We have accomplished this by writing just a few lines of code.

The first step in consuming a web service is to add a web reference to your project by selecting the project in the Solution Explorer, right-clicking, and selecting Add Web Reference from the context menu. You need to enter the URL of the web service you want to consume. This is normally the full URL of the .asmx file or the WSDL file of the web service. When the web service resides on your own computer, as is the case with our example for this recipe, a URL such as the following will do:

http://localhost/ASPNetCookbook/VBWebServices/CH14QuickWebServiceVB2.asmx

When adding a web reference, select Add Web Referencenot Add Reference. Add Reference is used to add a reference to an assembly on the local server. Add Web Reference is used to add a reference to a web service.

After entering the URL of the .asmx or WSDL file of the web service, the Add Web Reference dialog box displays the operations provided by the web service in the left pane.

The web reference name should be changed to remove the tight coupling to a specific server because the server hosting the web service can change. For our example, we have renamed the web reference to ExampleWebServices, as shown in Figure 14-3.

When you click Add Reference, Visual Studio 2005 creates and adds to your project all the files needed to make a web service available to your application, including a disco file, which helps the application locate the service, and a WSDL file, which defines the services available from the web service. Then, it creates a proxy class that you use to access the web service. (The proxy class interfaces with the web service and provides a local representation of the service.) The web reference is given the name provided in the Add Web Reference dialog box.

Visual Studio 2003 created a physical class called Reference as the proxy class. Visual Studio 2005 does not create the physical class but generates a "virtual" proxy class that is not visible in the project.

After you add a web reference to the service you plan to employ, you need to create an instance of the proxy class. For example, here's how we create an instance of the proxy class for the example web service in Recipe 14.1:

 
 bookServices = New ExampleWebServices.CH14QuickWebServiceVB2 
 bookServices = new ExampleWebServices.CH14QuickWebServiceCS2();

In our example, the getBookList method is called to obtain a DataSet containing the book list. Though this method call looks like a standard method call, the proxy class is calling the web service to get the data.

 
 books = bookServices.getBookList(NUMBER_OF_BOOKS) 
 books = bookServices.getBookList(NUMBER_OF_BOOKS);

For our example, the DataSet returned by the web service is bound to a DataGrid on the form to display the list of books:

 
 dgBooks.DataSource = books dgBooks.DataBind() 
 dgBooks.DataSource = books; dgBooks.DataBind();

By creating all the plumbing required to access web services, which would be tedious to write and error-prone if you had to do it yourself, Visual Studio 2005 makes using web services in your applications more practical. This is true if the web service provider and consumer are both .NET implementations, because most of the data types provided by the Common Language Runtime (CLR) can be used in the web service interfaces. (See the ".NET Web Service Idiosyncrasies" sidebar in Recipe 14.3 for more on this topic.)

Web services provided by other technology platforms, such as Java, can be consumed by .NET applications. Java and other platforms do not have a set of rich data types that match the CLR data types, so the interface must be designed using simple data types. The details of consuming a web service from other technologies are beyond the scope of this book.

 <%@ Page Language="VB" MasterPageFile="~/ASPNetCookbookVB.master" AutoEventWireup="false" CodeFile="CH14ConsumingAWebServiceVB.aspx.vb" Inherits="ASPNetCookbook.VBExamples.CH14ConsumingAWebServiceVB" Title="Consuming A WebService" %> <asp:Content  runat="server" ContentPlaceHolder> <div align="center" > Consuming a Web Service (VB) </div> <div align="center"> <asp:DataGrid   runat="server"  BorderColor="000080" BorderWidth="2px" AutoGenerateColumns="True" width="90%" /> </div> </asp:Content>

Example 14-9. Consuming a web service code-behind (.vb)

 Option Explicit On Option Strict On Imports System Imports System.Data Namespace ASPNetCookbook.VBExamples ''' <summary> ''' This class provides the code behind for ''' CH14ConsumingAWebServiceVB.aspx ''' </summary> Partial Class CH14ConsumingAWebServiceVB Inherits System.Web.UI.Page '''*********************************************************************** ''' <summary> ''' This routine provides the event handler for the page load event. It ''' is responsible for initializing the controls on the page. ''' </summary> ''' ''' <param name="sender">Set to the sender of the event</param> ''' <param name="e">Set to the event arguments</param> Private Sub Page_Load(ByVal sender As Object, _   ByVal e As System.EventArgs) Handles Me.Load Const NUMBER_OF_BOOKS As Integer = 10 Dim bookServices As ExampleWebServices.CH14QuickWebServiceVB2 Dim books As DataSet If (Not Page.IsPostBack) Then 'create an instance of the web service proxy class bookServices = New ExampleWebServices.CH14QuickWebServiceVB2 'get the books from the service books = bookServices.getBookList(NUMBER_OF_BOOKS) 'bind the book list to the datagrind on the form dgBooks.DataSource = books dgBooks.DataBind() End If End Sub 'Page_Load End Class 'CH14ConsumingAWebServiceVB End Namespace

Example 14-10. Consuming a web service code-behind (.cs)

 using System; using System.Data; namespace ASPNetCookbook.CSExamples { /// <summary> /// This class provides the code behind for /// CH14ConsumingAWebServiceCS.aspx /// </summary> public partial class CH14ConsumingAWebServiceCS : System.Web.UI.Page { ///*********************************************************************** /// <summary> /// This routine provides the event handler for the page load event. /// It is responsible for initializing the controls on the page. /// </summary> /// /// <param name="sender">Set to the sender of the event</param> /// <param name="e">Set to the event arguments</param> protected void Page_Load(object sender, EventArgs e) { const int NUMBER_OF_BOOKS = 10; ExampleWebServices.CH14QuickWebServiceCS2 bookServices = null; DataSet books = null; if (!Page.IsPostBack) { // create an instance of the web service proxy class bookServices = new ExampleWebServices.CH14QuickWebServiceCS2(); // get the books from the service books = bookServices.getBookList(NUMBER_OF_BOOKS); // bind the book list to the datagrind on the form dgBooks.DataSource = books; dgBooks.DataBind(); } } // Page_Load } // CH14ConsumingAWebServiceCS }