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:
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.
![adobook.jpg]()
|
This essential guide
to Microsoft's ADO.NET overviews C#, then leads you toward deeper
understanding of ADO.NET. |