Building a Distributed Web Service Using a Strongly-Typed DataSet in C# 

 This is part two of series of articles intended to provide practical background information on design approaches for the .NET platform as well as providing clear explanations of the .NET features it introduces.

In the last article in this series, it was described how to create a Web service that consumes another Web service that does not provide its result set in a .NET DataSet, by using the WSDL (Web service description language) which the consumed Web service provides, it is described how to build from this a strongly-typed DataSet that becomes a first-class player in the .NET object model, the benefits of which will become apparent during the coding process explored in this article.

Figure 1 - A distributed Web service application utilizing the QueryandPackage Web service

The QueryandPackage Web service this article describes how to build queries Microsoft's Best Bets Search Web service and packages the results in a strongly-typed DataSet, which any .NET Web Form or Win Form application can use.

This Web service, along with Microsoft's Best Bets Search Web service will form the basis for a distributed Web service application in keeping with the design goals of Microsoft .NET.

In this article, it will be shown how easy and simple it is to design, build and manage a distributed Web application that provides valuable services to clients. The article will also point out and explore the key .NET features that aid the structuring and implementation of the Web service as it goes through the coding process.

Getting In The Flow

The first thing to do is to prepare a flow chart of the actions that the Web service will take. In Visual Studio.Net Beta 1, there are some great built-in modeling tools that will help in this process as well as offering the great benefit of keeping these modeling files with the project. However, these tools are not yet fully usable, so in this article Microsoft Visio is employed for this purpose:

Figure 2: Query and Package WebService Flow Chart

Figure 2, above, displays the flow of the process that the Web service will provide, but it does express a design. So let's look at that as well.

Implementing a .NET Design Approach

Remember that .NET is based on an object-oriented foundation, emphasizing component development, modularity and code reusability. This means that when designing an application in .NET, it is desirable to explore how to design the application in such a way that it is made up of components that can be used by other components.

This approach can be applied to a Web service as follows:

.NET uses an .ASMX file to represent a Web service. Think of the .ASMX file as the front-end, or gateway to a service. It does not necessarily have to directly house the service itself. The Web service can call a component or components that do the work of the Web service.

The advantages to this approach are many. For example, separating the component from the Web service enables to component to be used by other applications, be they other Web services, server applications or client applications.

Further, the .NET platform enables existing components created with Win32 or COM technologies to be called from .NET, enabling .NET applications to be based on existing code bases. This capability enables the migration to .NET to occur very smoothly and in stages that work best for the organization they serve - yet another way in which .NET sets a standard for flexibility in implementation.

Following this design approach, here is a representation of the way in which Web services can be implemented:

Figure 3 - .NET Web service design

So, in the same manner that ASP.NET introduces the idea that the code that runs with a page is separated from the HTML that is on that page, design of functionality within .NET applications are meant to follow this component-based approach.

Building the WebService

In this Web service, only one component is required to do the work specified in Figure 2. The steps and code to build this Web service follow. It is assumed that the reader has read and implemented part one of this article and has created a Web service project in VS.NET Beta 1, consumed the Microsoft Best Bets Web service and has created a strongly-typed DataSet that is part of the object model of this project. The steps to complete the Web service pick up where the last article left off.

The reader should have the Web service project open with the following files in place:

 

Code Discussion

The first step will be to create a component in the project and code it to perform the desired steps:

1. Right-Click on the C# Search WebService icon and choose Add Component…

2. An "Add New Item" dialog will come up - name the component QueryandPackage and press return;

3. Right-click on the newly created file, QueryandPackage.cs and choose "View Code";

 

The code window opens. Note that Visual Studio has created the shell of the component as a .NET component object which can be viewed with the Class Viewer in Visual Studio:

The component object has been created with the following features:

The Namespace of the code file is set to default Namespace of the project, thereby setting it logically in the hierarchy of the object model of the project. Namespaces provide a logical organizational system. Namespaces are used both as an "internal" organization system for a program, and as an "external" organization system-a way of presenting program elements that are exposed to other programs;

The SearchandQuery class is declared - the component object itself is created as a subclass of the .NET class

System.ComponentModel.Component. A component, as defined by .NET, is an object that allows the use of objects supplied by another application or of exposing its own objects for use by another application.

components object variable of type System.ComponentModel.Container is declared. This object is part of the component model and is the object that hosts the component. It has the ability to query and get services about the components it hosts and is instantiated as part of the constructor, which follows.

SearchandQuery constructor is declared - this is the constructor for the component object itself and is called whenever an instance of SearchandQuery is instantiated. It calls the following method by default:

InitializeComponent() - this default method is called when the SearchandQuery constructor is called. It instantiates the container object for this component, which is how components communicate with the environment they are hosted in and are integrated into the visual designer of VS.NET.

4. In the code window, move to the bottom of the window and type the following code at the end of the InitializeComponent() method:

public dsBBI QueryandPackage(string strQuery)

{
 
//Instantiate new MS search object
 
MS_Search.MSComSearchService srch = new MS_Search.MSComSearchService();

//Instantiate BestBetData object to hold complete result
 
MS_Search.BestBetsData bbd = new MS_Search.BestBetsData();

//Pass the query and put results in BestBetsData object
 
bbd = srch.GetBestBets(strQuery);

//Instantiate Strongly-Typed DataSet in preparation for use
 
dsBBI ds = new dsBBI();

//Declare DataRow object from strongly-typed dataset in preparation for use
 
dsBBI.BestBetItemRow dr;

//Move results into DataSet
 
for(int i = 0 ;i <= (bbd.BestBetsCount - 1);i++)
 
{
   
//Create new DataRow
   
dr = ds.BestBetItem.NewBestBetItemRow();

 //Populate DataRow
   
dr.DisplayTerm = bbd.BestBetsItems[i].DisplayTerm;
   
dr.Rank = bbd.BestBetsItems[i].Rank;
   
dr.Set = bbd.BestBetsItems[i].Set;
   
dr.Title = bbd.BestBetsItems[i].Title;
   
dr.Url = bbd.BestBetsItems[i].Url;

//Add new DataRow
   
ds.BestBetItem.AddBestBetItemRow(dr);
 
}

return ds;

}
 
As this code is typed, note that any references to the external Web service or the strongly-typed dataset cause the Intellisense code system to provide access to the complete object model of these objects at the same level of support any .NET framework object. This is part of what is meant when Microsoft says that these objects become "first-class players" in the object model. See below for an example of this:

In the above code, a for loop is used to move the results into the strongly-typed DataSet. Close the component's code window and save any changes.

5. One more feature here: built-in documentation for C# - on the blank line just above the beginning of the method, type three slashes - "///" as follows and VS.NET automatically creates an XML entry in the code that allows the method to be documented as follows:

6. Type the following on the line in between the summary tags: This method goes out the the MS Search Web service and returns dsBBI, a strongly-typed DataSet as a result.

In the next few steps, the manner in which this documentation feature makes working in VS7 easier than ever before will be shown.

7. The next step is to add code to the Web service itself so that it will call the component. Right-click on the WebService1.asmx file in the Solution Explorer and choose "View Code":

The code window will open.

8. Move to the bottom of the window and type the following code:

[WebMethod (Description = "This Web service passes a query to the MS BestBets search service and packages the result in a strongly-typed DataSet.")]

public dsBBI QueryandPackage(string strQuery)

{
 
//Instantiate Component
 
SearchandQuery component = new SearchandQuery();

//Instantiate DataSet
 
dsBBI ds = new dsBBI();

//Call Method
 
ds = component.QueryandPackage(strQuery);

//return value
 
return ds;

}

Again, note as this code is typed that the intellisense provides pop-up references to all objects. This time, when typing the line ds = component., allow the pop-up list to display and scroll to the method of the component QueryandPackage and look at what appears - the documentation reference that was typed in step 6.

So in .NET, it is not necessary to remember everything - the environment provides a broad level of support in providing the programmer with information as it is needed - in this case an explanation of what the method does and the parameters to be passed to it.

9. This concludes the required coding to make the Web service function. Save and close the window.

10. Go to the Build menu and choose "Build".

11. Now to test the service, press F5 on the keyboard. A Web page window will appear that provides a way to test the Web service. Type "Exchange" in the value field and press the "Invoke" button:

Note that the Web service requires connectivity to the internet in order to work. In a few moments an XML representation of the result set will be returned - the Web service functions as expected.

Next Article

The nature of objects will be explored in the next article.