Web Services with ADO.NET

This article has been excerpted from book "A Programmer's Guide to ADO.NET in C#".

Web services provide a way to run a service on the Web and access its methods using standard protocols, including Simple Object Access Protocols (SOAP), Extensible Markup Language (XML), Web Service Description Language (WSDL), and Hypertext Transfer Protocol (HTTP). Technically, a web service is nothing more than an application that exposes its interface to a client who wants to access the service's abilities. The uses of a web service include validating credit cards, searching for data in a database, inserting an order into a shopping cart, and updating a guest list. The sky is the limit on what you can have your web service do on your server. In the past, JavaBeans, ActiveX/Component Object Model (COM) controls, and other nonstandard service components handled these services, which required specialized formats to exchange data with the client. But web services under .NET run by invoking methods in the service directly through HTTP or SOAP, so someone wanting to run your web service from their computer at home can simply send an HTTP call to your service, passing the parameter in a standard Uniform Resource Locator (URL). I'll show you how to do this later in the article.

Three attributes make up a Web service:

Discovery: First, you need to locate the Web service. You locate Web service through the Discovery Service Protocol. The *.disco file stores the protocol in your Visual studio (VS) .NET project. This file contains reference to all the Web services under your Web site's virtual directory. VS can automatically generate this file for you. The discovery file (.vsdisco), an XML file, is used to identify searchable paths on the web server used by discovery process.
Description: Once you have discovered your service, you need a way to tell the client what methods, classes, and so on the web service has and what wiring protocol (SOAP, HTTP, and so on) the services are using. You do this through WSDL, an XML format. VS provide tools for generating WSDL files automatically from your services.
Wiring Protocol: Web services under .NET use two main protocols, HTTP-post /HTTP-get and SOAP. HTTP-post and HTTP-get enable you to send and receive information via a URL by passing and receiving name value pair strings. Unfortunately, HTTP can only pass strings that represent different data types. SOAP allows you to pass a richer type of information, such as datasets.

Exploring Web Services and the .NET Framework Library

The .Net framework class library provides four namespaces that contain web service classes. These namespaces are

System.Web.Services,System.Web.Services.Description, System.Web.Services.Discovery, and System.Web.Services.Protocol.

The System.Web.Services namespace provides classes that enable you to build and use web services. It has four classes. The WebService class defines the optional base class for Web services, which provides direct access to an ASP.NET application. Server, Session, User, and Context are some of its properties. WebMethodAttribute, WebServiceAttribute, and WebServiceBindingAttribute are other classes of this namespaces.

The System.Web.Services.Description namespace provides classes that enable you to describe a WSDL.

The System.Web.Services.Discovery namespace provides classes that enable Web service consumers to locate a Web service through discovery.

The System.Web.Services.Protocols namespace provides classes that define the protocols used to transmit data between a client and a Web service.

Creating a Web Service in VS .NET

To understand Web services better, I'll show you to build a simple Web service. The Web service will receive an order ID and then query the Northwind database's Orders table for the correct order. It'll then return the order in a DataSet.

The first step in creating the web service is to select File > New > Project and choose the ASP.NET Web service template, as shown in Figure 8-1.

Figure 8-1 Creating a new Web service project

This creates a Web service project on the MCB server. By default, local-host is available as a Web server on your development machine. After the server name, you give it a project name. In this sample, the project name is OrderRetrievalService. VS .NET creates a new folder with the project name on the Web server and keeps all project files under that folder. Clicking the OK button creates the project.

If you look at the solution explorer, you'll notice a list of files created automatically for the project, as shown in Figure 8-2. You won't be able to see some code and resources files by default; they are hidden. You need to click on the show All Files button of the Solution Explorer to view all the files (see Figure 8-2).

Figure 8-2 Files included in the web service project

First, the Web.config file is an XML file containing information on how to run the service under ASP.NET. Second, the Global.asax and Global.asax.cs files enable you to handle application-level events for the service. Theses event handlers include event-handling pairs such as Application_Start-Application_End, Session_start-Session_End, and Begin_Request-End_Request. You can view Global.asax.cs by right clicking on the Global.asax file in the Solution Explorer and choosing view code. Next, OrderRetrievalServices.vsdisco is an XML file containing information for discovery of the service. You will actually need to generate an OrderRetrievalService.disco file for your client to see the service (more on this later).

Finally, the Service1.asmx file serves as the entry point into the service. The code behind the service, Service1.asmx.cs is where you will place the method for retrieving the order. Right-click on the Service1.asmx file in the Solution Explorer and choose View Code from the pop-up menu, as shown in Figure 8-3.

Figure 8-3 Viewing the code in the Web service

See Listing 8-1 for the Web service code. Note that it looks like any other C# component; it has a constructor, an InitializeComponent method, and a Dispose method.

Listing 8-1. Initial Web service code in OrderRetrievalService.asmx.cs

public class Service1 : System.Web.Services.WebService

{

public Service1()

{

//CODEGEN: This call is required by the Asp.Net Web Services Designer

InitializeComponent();

}

#region Component Designer generate code

//Required by the Web Services Designer

private IContainer component = null;

/// <summary>

/// Required method for Designer support-do not modify

/// The contents of this method with the code editor.

/// </summary>

private void InitializeComponent()

{

}

/// <summary>

/// Clean up any resources being used.

/// </summary>

protected override void Dispose(bool disposing)

{

if (disposing && component != null)

{

components.Dispose();

}

base.Dispose(disposing);

}

#endregion

// WEB SERVICE EXAMPLE

// The HelloWorld() example service return the string Hello World

// To build, uncomment the following lines then save and build the project

// To test this web service, press F5

// [Webmethod]

// public string HelloWorld()

// {

// return "Hello World";

}

Now I'll add database support to the Web service. Actually adding database support to a web service is quite easy using ADO.NET. You can add ADO.NET data components to a web service by just dragging ADO.NET component from the toolbox's Data tab to Web Forms. Similar to windows forms, you can also use the Server Explorer to add database components to a Web service.

You can access different kinds of data sources in a similar fashion. The only thing you change is the data provider and the connection string.

In this example, I'll use the Access 2000 Northwind database. I simply create a connection and a data adapter to the Orders table in the Northwind database. You can do this automatically through the .NET framework by simply dragging the orders table from the server explorer onto the Service1.asmx.cs Design view, as shown in Figure 8-4. In fact, as you can see from the figure, you can drag any database table to the Web page.

Figure 8-4 Creating the OleDbDataAdapter from the Server Explorer

Drag the orders table to the page. This action adds a connection, data adapter, and four command objects as follows:

private System.Data.OleDb.OleDbCommand oleDbSelectCommand1;

private System.Data.OleDb.OleDbCommand oleDbInsertCommand1;

private System.Data.OleDb.OleDbCommand oleDbUpdateCommand1;

private System.Data.OleDb.OleDbCommand oleDbDeleteCommand1;

private System.Data.OleDb.OleDbConnection oleDbConnection1;

private System.Data.OleDb.OleDbDataAdapter oleDbDataAdapter1;

Figure 8-5 shows the results in design view.

Figure 8-5 Results of dragging the orders table from the Server Explorer

If you drag the Orders table from SQL server database, the result will look like Figure 8-6. The only difference is that SQL server uses the Sql data provider instead of the OleDb data provider.

Figure 8-6 Results of dragging the SQL server orders table from the Server Explorer

Now, the next step is to add a Web method to the project. You can use the Class Wizard to add a method, or you can also add a method manually. For this example, I'll use the Class Wizard to add a method.

To add a method to the project, open the class view from main menu's View > Class View option and right-click on the Service1 class and select Add > Add Method, as shown in Figure 8-7.

Figure 8-7 Adding a new method to a Web service

The Add Method option opens the C# Method Wizard, which lets you add a method. As you can see from Figure 8-8, I added a GetOrderFromDatabase method, which return a DataSet (type "DataSet" in the Return Type text box). This method also takes one argument of integer type. You type the parameter name "OrderId" of integer type and use the Add button to add the parameter. Now click Finish. This process adds a method to the class, which looks like following:

public DataSet GetOrderFromDatabase(int OrderId)

{

return null;

}

Figure 8-8 Adding GetorderfromDatabase using the C# Method Wizard

Wait, this method is not a Web method yet. Before you write any code, you need to add the [WebMethod] attribute at the beginning of this method to recognize it a Web method.

Now you're going to add some code to the method. This method returns a DataSet that will have records from the Orders table corresponding to an OrderId. Listing 8-2 shows the GetOrderFromDatabase method.

Listing 8-2. The Web Service method for obtaining an order from an OrderId

[WebMethod]

public DataSet GetOrderFromDatabase(int OrderId)

{

DataSet ds = new DataSet("OrderSet");

oleDbDataAdapter1.SelectCommand.CommandText = "Select * from Orders WHERE OrderID = " + OrderId.ToString();

oleDbDataAdapter1.Fill(ds, "Orders");

return ds;

}

As you can see from Listing 8-2, the method receives an OrderId from a client and returns a DataSet to the client. It uses the DataAdapter to fill a DataSet with the row containing that OrderId.

Note: You have to add a WHERE clause onto SelectCommand to filter the single row of data. Also, you must make all exposed methods in the Web service public, and they must contain a [WebMethod] attribute; otherwise, the client won't them.

Testing your Web Service

Now you are ready to build and test your web service. First, build the service using the Build menu option and then start it in Debug mode. This will bring up the Web service in your browser, as shown in Figure 8-9.

Figure 8-9 Initially running the Web service Service1.asmx.

As you see in figure 8-9, one method GetOrderFromDatabase is available in the browser.

You can make this screen a bit more descriptive by adding a WebService attribute to the top of the class and then adding descriptions to both the WebService attribute and the WebMethod attribute. As you can see from listing 8-3, I added a description to both.

Listing 8-3. Adding description to the WebService and WebMethod attributes

[WebService(Description = "Working with orders in Northwind")]

public class Service1:System.Web.Services.WebService

{

[WebMethod(Description = "Retrieve an orders from Northwind")]

public DataSet GetOrderFromDatabase (int orderID)

{

. . . . .

}

The service now looks like Figure 8-10.

Figure 8-10 The Web service after you add attributes

If you click on the link for the GetOrderFromDatabase method, you see the screen on figure 8-11. This browser screen enables you to test the method by entering an OrderID.

Figure 8-11 Testing the Web service's GetOrderFromDatabase method

After you click the invoke button, the browser returns the XML data representing the DataSet, which contains the order with the order ID of 10248. Figure 8-12 shows a piece of the XML data representing the order and displayed by the browser.

Figure 8-12 The Order DataSet displayed by the browser in XML format

Note that because you're using a complex structure such as a DataSet for the return parameter, you need to use SOAP with an XSD schema (which happens to be the default wiring protocol) to transfer the data back to the client. The encoding of the SOAP format is beyond the scope of this article, but if you're interested, you can visit the World Wide Web Consortium (http://www.w3.org).

As you can see from figure 8-12, the default namespace for the DataSet xmlns is http://tempuri.org. You can use the WebService attribute to specify the namespace and description text for the XML Web service. As you can see, VS .Net doesn't generate this attribute by default. You have to write it manually. If you are specifying more than one property, you can separate them with a comma. For example, the following code sets the namespace and the description properties of the WebService attribute:

[WebService(Namespace = "http://servername/xmlwebservices/",

Description = "My Web Service")]

public class Service1 : System.Web.Services.WebService

{

// Implementation code.

}

Conclusion

Hope this article would have helped you in understanding Web Services with ADO.NET. See other articles on the website also for further reference.

This essential guide to Microsoft's ADO.NET overviews C#, then leads you toward deeper understanding of ADO.NET.