An Example Application

Having considered the basic makeup of a Web service, let’s look at how to fill in the functionality by adding Web service logic to a Web method. We’ll build a couple of Web methods that will crop up throughout this and the next chapter.

We’ll use the record store database example from Chapter 2, but this time we’ll provide more functionality than the ability to browse the database. In fact, we’ll ape the abilities of Microsoft’s Window Media Player to demonstrate how Web services are used in Windows Media Player to provide vital aspects of the functionality, such as the ability to provide details about a CD (artist, artist biography, discography, cover information, and so on).

Windows Media Player isn’t the only software that provides this functionality; plenty of other software, such as MusicMatch Jukebox, also provides it. All of these players use Web services to leverage existing repositories of CD information, such as track listings and album covers, and they match this information to what is being played on the application, whether it be an MP3 file, a CD, or a DVD. The response is typically timely enough and invisible enough to give novices the impression that no external call to the Web has been made. This is a particularly common and suitable application of Web services—and for the Web methods on which .NET Web services depend.

In the next chapter, we’ll create our own media player application by embedding Windows Media Player into a client application. Our small application will be able to identify and return information about CDs.

In this chapter, we’ll create a Web service that the client application will use. We’ll select two categories of information that Windows Media Player typically accesses on the Web and build two Web methods. The first Web method will expose an artist biography for each record, and the second will display a stored image of a CD cover when a user places a CD in the CD player and starts the application. You’ll see how the Web methods both return straightforward text from a database in the form of a string and also something more complex in the form of an image returned as a byte array.

Our application will first check to see whether it can identify the record; if it can, it will check to see if there is an entry for it in our database, using the identifier and using our own Web services for details. If the application can’t identify the artist or record, we will just return the information we can find. This might be a tracklisting and album title, or it might be nothing at all.

The first problem we face is how to uniquely identify CDs when they are placed in the CD tray. This issue has been a source of controversy among companies that initially provided tools to solve the issue as freeware and then added copyright handles at a later point. We’ll use an .ocx file from freedb.org and embed this into a Windows Forms client; the tool from freedb.org will provide a useful wrapper to keep hidden the low-level basics of reading from the CD and identifying the CD.

The Example Web Service

We start by creating our .asmx file. First we need to add the classes that we will reference in the Web method. These are

using System.Web.Services.Protocols; using System.Data.OleDb;

Then we place our Web service definition just before the Service1 class definition:

[WebService (Name="RecordStoreWebService",      Namespace="http://www.notashop.com/wscr",      Description="A Web service which exposes the details "         + "about an LP and its cover")] public class Service1 : System.Web.Services.WebService {     ⋮ 

We place our Web methods in the Service1 class definition.

The Example Web Methods

The first Web method, GetBio, takes a string containing the unique identifier of the CD and returns a string containing biographical information from our SQL database. The Web method returns the corresponding Biography field from the Biography table:

[WebMethod(Description="Gets the Artist's associated Biography")] public string GetBio(string Id) {     OleDbConnection objConnection;     OleDbCommand objCommand;     string [] ArtistBio;     string ArtistB;     ArtistBio = new String[10];     string strConnect;     string strCommand;     OleDbDataReader DataReader1;     int i=1;     strConnect = "Provider=SQLOLEDB.1;Password='';"         + "Persist Security Info=True;User ID=sa;"         + "Initial Catalog=dansrecordsSQL;Data Source=CHRISUHOME";     strCommand = "SELECT Biography From Biography WHERE "         + "Id='" + Id + "'";     // Provide your own server's connection information here  objConnection = new OleDbConnection(strConnect);     objConnection.Open();     objCommand = new OleDbCommand(strCommand, objConnection);     DataReader1 = objCommand.ExecuteReader();     while (DataReader1.Read())     {         ArtistBio[i] = DataReader1.GetString(0).ToString();         i++;     }     DataReader1.Close();     objConnection.Close();             ArtistB = ArtistBio[1];      return ArtistB; }    

Our Web method accepts a string—the identifier of the CD—and returns a string after querying the database by using the OleDbConnection and OleDbCommand objects and by using an OleDbDataReader object to return the information from the query. The query is then read into an array from which the returned string is taken. We’ve chosen a string within this Web method for reasons of interoperability.

Our Web method uses a data reader. In Chapter 9, you’ll see that returning a data set causes problems for all client applications that are not .NET applications. To circumvent this limitation, we’ll briefly use the data reader to read the biographical information into an array, and then we’ll store the contents of the array in a string.

The second Web method is more complex. The Web service is provided with the identifier of the CD and must supply an image. Images are stored in BLOB format within a database, but that immediately poses the problem of how to retrieve information from the database and supply it to the Web method. We have to translate the image into a byte array and return this to the client. The client must translate the byte array back into image, which can be displayed on the form. (We won’t worry about how the client deals with this information until the next chapter; we simply want the Web method to return a byte array.) Here’s the code that achieves this:

[WebMethod(Description="Gets the Artist's or CD's Associated Picture")] public byte[] GetPic(string Id) {     OleDbConnection objConnection;     OleDbCommand objCommand;     string strConnect;     string strCommand;     strConnect = "Provider=SQLOLEDB.1;Password='';"         + "Persist Security Info=True;User ID=sa;"         + "Initial Catalog=dansrecordsSQL;Data Source=CHRISUHOME";     // Provide your own server's connection information here  strCommand = "SELECT CoverPic From AlbumDetails "         + "WHERE Id = '" + Id + "'";     objConnection = new OleDbConnection(strConnect);     objConnection.Open();     objCommand = new OleDbCommand(strCommand, objConnection);             // Convert stream to byte array     OleDbDataAdapter da = new OleDbDataAdapter(objCommand);     DataSet ds = new DataSet();     da.Fill(ds, "AlbumDetails");     int count = ds.Tables["AlbumDetails"].Rows.Count;     if(count>0)     {            Byte[] BLOBPicByteArray =  new Byte[0];             BLOBPicByteArray=(Byte[])             (ds.Tables["AlbumDetails"].Rows[count - 1]["CoverPic"]);         objConnection.Close();         return BLOBPicByteArray;     }      else      {         Byte[] BLOBPicByteArray =  new Byte[0];         objConnection.Close();         return BLOBPicByteArray;     }     }

Caution

How the image is placed in the AlbumDetails table affects the functionality of the Web method. If you use a Microsoft Access front end at any point to insert the images into the database, by default an OLE container will be inserted around the image, and this will cause the Web method to return an error because it expects an image rather than an OLE container. To work around this, you can insert the image using pure SQL statements or create a small procedure that inserts the image as BLOB data via the form. We supply a small method for doing this together with the code you can download for the book.

This method is more complex than the first one; the code required to extract the image from the database is similar, but once the image has been identified, it has to be read as a stream of bytes into a byte array. The mechanics by which the requisite piece of data is identified is pretty much the same as with the first method—the connection and command objects are used to execute a SQL query against the database—but we’ll use the more flexible DataAdapter object to return the result of our data query before reading the stream of bytes into the byte array.

You can now browse the .asmx file, and you should get details on the two Web methods that have just been created, as Figure 7-1 shows.

Figure 7-1: Browsing the Service1.asmx file of RecordStoreWebService

If you set up the example MSDE/SQL database, you should also be able to send a test request and get a response back. We now have two Web methods that provide the required functionality. We haven’t supplied the Web methods with any extra attribute settings because we know that the Web methods will not need to use session handling, caching, or transactions in any form. However, creating a class and exposing it as a Web method isn’t the end of the story. We have to consider how this information will be encoded, how to keep track of state, how the functionality of the Web service will be affected by configuration files, and how to deploy and debug the Web service.