When you use the HTTP protocol (either GET or POST requests), all parame-
ters must be passed by value, because HTTP doesn’t support call by refer-
ence. In fact, the interface supplied by any ASP.NET Web service (the WSDL
file) won’t contain any by reference method definitions.
If you want to try passing a parameter by reference to a Web Service, add the following method to Listing 15.4:
[WebMethod]
public void GetTimeByRef(ref TimeStruct ts)
{
ts = GetTimeEx();
}
Next, change Line 14 of Listing 15.6 to the following:
timeServer.GetTimeByRef(ts);
The modified listings should produce the same result as before. If you need to write a method that modifies more than one parameter, simply make each parameter byref by adding the ref keyword.
Accessing Data with Web Services
Because the SOAP protocol allows you to send any kind of parameter and receive any kind of return value, you can send and receive ADO.NET datasets. By using datasets in combination with Web Services, you can create Web Services that provide many kinds of data services. This section will describe a sample Web Service that manages a task list using dataset objects and XML files.
The Shared Task Web Service
The sample Shared Task Web Service allows multiple users to add and change tasks in a central location. The service stores the tasks in an XML file and allows any number of users to add and update tasks in the list. Figure 15.1 shows an example of a client that uses the Shared Task Web Service.
Any Internet application that allows more than one user to update data records has to deal with data concurrency issues. These issues consist of problems that can happen when two or more users update the same data record at the same time. You handle this problem by using a record-locking policy.
NEW TERM
Consuming a Web Service
349
FIGURE 15.1
A Web form that uses
15
the Shared Task Web
Service.
You can implement two kinds of record-locking policies to handle the simultaneous update problem: optimistic locking and pessimistic locking. Optimistic locking
means that users can overwrite each other’s changes. Pessimistic locking means that once a user obtains a lock on a data record, other users can’t update that record until the first user releases the lock. Let’s look at a scenario for each locking situation.
A typical pessimistic locking scenario might be the following:
1.User Joe reads a database record and sets a lock on the record.
2.User Sue reads the record but can’t get a lock for it.
3.Sue tries to update the record but gets an error such as The record
is locked by Joe.
4.Joe updates the record, saves changes, and releases the lock.
5.Sue can now update the record.
A typical optimistic locking scenario might be the following:
1.Joe reads a database record.
2.Sue reads the same record.
3.Sue updates the record.
4.Joe updates the record and overwrites Sue’s changes.
From these scenarios, you might think that optimistic locking is a bad idea. Joe and Sue don’t know that they overwrote each other’s changes.
However, pessimistic locking can make a Web Service or Web application extremely slow because record locking takes up valuable database resources and can prevent other users from accessing other records. Most databases that use record locking must keep a
350
Day 15
permanent database connection open to the client program to preserve the lock. Database connections are a scarce resource. If a server has too many open database connections, it will perform extremely slowly. To compound the problem, if your Internet application uses XML to store data, you have to implement your own record-locking logic, which can be quite complex.
One solution to the pessimistic locking problem involves using record versioning. One way of implementing record versioning is to attach a timestamp to each record. The scenario works like this:
1.Joe reads a database record. The record contains a field with a timestamp of the last time the record was modified.
2.Sue reads the same record, along with the same timestamp.
3.Sue updates the record. The timestamp is changed to the current time because the record has been modified.
4.Joe tries to update the record. His record’s timestamp doesn’t match the timestamp of the current record. The server detects this difference and gives Joe the option of refreshing his record to get the latest changes or simply overwriting the current record.
In this solution, Joe knows that he is about to overwrite a record whose value has changed.
Implementing Optimistic Locking
Let’s implement the Shared Task Web Service so that it uses this record versioning solution to the optimistic locking program. Our first task is to design the look of the XML file that stores the shared tasks. Listing 15.7 shows an example.
LISTING 15.7 TaskStore.XML: A Sample XML File Containing Shared Tasks
Each task contains a name, due date, owner name, and modified field.
Next, create a schema for the XML file. As a first step, use Visual Studio to automatically
15
generate the schema. Then you can modify the schema to make the name field a primary key and to establish the appropriate data types for each field. The name and owner fields should be strings, and the due and modified fields should be of type dateTime. If you are following along with the lesson, you can make these changes in the Design view of the XML Schema editor in Visual Studio. The lesson for Day 11, “Using ADO.NET and XML Together,” gave details on how to use the editor. The final XML Schema should look like Listing 15.8.
LISTING 15.8 TaskStore.XSD: A Schema Definition for the Shared Tasks XML File
Lines 38–42 define a primary key for the XML file using the unique element. The name field is defined as the primary key field using the selector (Line 40)
and field (Line 41) elements. Line 10 uses the EnforceConstraints attribute to make sure that ADO.NET uses the primary key when it reads the XML file. This way, ADO.NET will throw an exception if duplicated records with the same name field are added to the file.
Next, create a Web Service that allows users to add and modify tasks:
1.Create a new project using the Blank Web Project template. Name the project TaskServer.
2.Add a config.web file by choosing Add New Item from the Project menu.
3.Copy the TaskStore.xml file into the project directory. Add the file to the solution by choosing Add Existing Item from the Project menu.
4.Add the TaskStore.xsd file into the project.
5.Create a new typed dataset using the TaskStore.xsd file. To do so, select the TaskStore.xsd file from the Solution Explorer window. Then select the Generate DataSet option from the Schema menu.
6.Add a new Web Service file by using the Project menu’s Add Web Service option. Call the Web Service TaskServer.asmx.
Create a method called GetTasks to return all tasks in the TaskStore.xml file to the user. Listing 15.9 shows what the method should look like.
LISTING 15.9 Returning a Dataset Containing All Shared Tasks
1:[WebMethod]
2:public sharedtasks GetTasks()
3:{
4:sharedtasks ds = new sharedtasks();
ANALYSIS
Line 2 declares that the GetTasks method should return an object of type
ANALYSIS
sharedtasks. The sharedtasks class is defined in the typed dataset file that was just created in step 5. Lines 4–5 create a new typed dataset and read the content from the TaskStore.xml file. Line 6 returns the new typed dataset.
Now create a method that will add a new task. The method, called AddTask, should accept the sharedtasks typed dataset, which will contain one new task. The method should check to make sure that the new record doesn’t have a duplicate name field. Listing 15.10 shows an example of the AddTask method.
16:Error = “A task with the name “ + newRow.name + “ already exists.”;
17:}
18:catch(Exception ex)
19:{
20:bSuccess = false;
21:Error = “Error: “ + ex.Message;
22:}
23:return bRetVal;
24:}
Line 5 creates a reference to the row containing the data for the new task called newRow by selecting the row at index 0 from the task table. Line 7 gets the current
task list by calling the GetTasks method and assigns it the typed dataset called ds.
354
Day 15
Lines 8–12 try to add the new row to the dataset by calling the ImportRow method (Line 10). ImportRow will throw a ConstraintException object if the new record contains a duplicate name field. Line 11 will write the new version of the shared task list back to disk if the ImportRow call was successful.
Lines 13–17 deal with a ConstraintException, if it occurs. Line 16 creates an error message that client programs can display to the user.
Next, add a method to the TaskService that will modify a row in the shared tasks file. This method needs to check the “modified” field of the record and match it against the “modified” field in the current record. If the two match, the client’s original data was valid. If the two modification times are different, the client’s data is out of sync with the data on the server. In this case, the method should return an error message. Listing 15.11 shows an example of the ModifyTask method.
LISTING 15.11 Modifying a Task, Checking to See Whether Another Client Has Modified the Record
27:Error = “This task has been changed by another user. “ +
28:“Please refresh your view of the data.”;
29:}
37: }
ANALYSIS Line 6 creates a reference to the modified row that the client sent, called modifiedRow. Line 8 gets the current set of shared tasks by calling the
GetTasks method.
Lines 10–11 return an array of DataRow objects in the shared task database that have the same name as the modified row that the client sent. Presumably, this array of matching rows contains only one value.
Lines 15–16 create a reference to the target row to be modified in the shared task database by retrieving the first object from the array of matching rows created previously.
Line 18 contains the key check to compare the modification timestamps between the client’s record and the server’s record. If they are identical, the client’s data is up-to-date, and the changes should be accepted. Lines 20–22 update the server’s version of the data and persist the data to disk.
Lines 24–30 create an error message if the client’s data is out of sync with the server’s version of the data.
As a final step, compile the new service.
Implementing a Client Web Form
This section will give an example of a Web form client that accesses the shared task service. You can use this Web form project to create multiple clients to the service and simulate the data concurrency problems that can occur. To create the client project, follow these steps:
1.Add a new project to the current solution using the Blank Web Project template (choose New Project from the File menu). Name the project Task Client.
2.Add a config.web file by using the Project menu’s Add New Item option.
3.Add a new Web reference from the TaskService by using the Add Web Reference option on the Project menu.
ANALYSIS
356
Day 15
4.Rename the proxy class created by Visual Studio to TaskServerProxy. To do so, right-click the localhost Web reference in the Solution Explorer window and select Rename.
5.Add a new Web form by using the Add Web Form option on the Project menu. Call the Web form TaskUI.asmx.
Next, create a user interface for the Web form. The form should contain a DataGrid to display the shared tasks and three buttons to add records, modify records, and refresh the grid. Also, add text boxes so that users can specify the name, due date, and owner of each new or modified record. Listing 15.12 shows an example of the Web form.
LISTING 15.12 TaskUI.aspx: A Web Form Client for the Task Service
Lines 8–9 define a data grid for the tasks, called taskGrid. Lines 11–13 define new text box controls that allow users to specify the task name, due date, and
owner. Lines 15–20 define button controls to add tasks, modify tasks, and refresh data. Using the data grid for task editing could enrich this interface, but this example keeps things simple.
Consuming a Web Service
357
Next, set up the infrastructure for the client Web form. The client should keep its version
of the task list in session state and contain methods to load the grid from the Web 15 Service on the first page hit. Listing 15.13 shows the infrastructure for the Web form.
LISTING 15.13 TaskUI.aspx.cs: The Infrastructure Code for the Web Form Client
Adding a New Task by Calling the Remote Web Service
LISTING 15.14
44: Refresh();
45: } 46: } 47: }
The Refresh method (Lines 17–23) is responsible for fetching the latest version ANALYSIS of the task list from the Web Service. The Bind method (Lines 24–29) binds the
taskGrid Web control to a dataset and stashes the dataset in session state.
The Page_Load method (Lines 30–41) will either refresh or rebind the data grid, depending on whether this is the first time the page has been rendered or if this request is from a control postback.
The OnRefresh method (Lines 42–45) reloads the data grid by calling the Refresh method. The Refresh button, defined in the Web form user interface, calls this method.
The final two steps involve creating event handlers for the Add and Modify buttons. First, create the AddTask event handler, which should use the contents of the text boxes in the user interface to construct a new dataset. It should pass this dataset to the Web Service by calling the Web Service’s AddTask method. Listing 15.14 shows an example of the client’s AddTask method.
Lines 3–4 get the contents of the client’s version of the task list from session ANALYSIS state and call the AcceptChanges method to prepare the dataset for the new
changes that are about to occur.
Lines 6–8 add a new row to the dataset, using the contents of the text boxes in the Web form. Lines 9–10 create a new dataset object, called delta, containing just this changed row by calling the GetChanges method.
Lines 12–14 invoke the AddTask method from the Shared Task Web Service, passing the delta dataset.
If the Web Service successfully adds the task, the AcceptChanges method is called (Line 18) so that the client’s version of the dataset reflects this new record. If the task can’t be added, Line 23 calls RejectChanges, which prevents the new record from being added to the dataset’s client copy.
The last method that needs to be added to the code behind file should handle record modifications. This event handler, ModifyTask, should modify the due date and owner fields only. The Web Service will take care of modifying the timestamp associated with the record. If the client’s original copy of the record is synchronized with the server’s record, the server will update the record’s timestamp to reflect the change. If another user has changed the record, the server won’t update the timestamp but will return an error message instead. Listing 15.15 shows an example of the ModifyTask event handler.
Consuming a Web Service
359
LISTING 15.14 Continued
21:
else
15
22:
{
23:
ds.RejectChanges();
24:
ErrMessage.Text = Error;
25:
}
26:
Bind(ds);
27: }
LISTING 15.15 Modifying a Task by Calling the Remote Web Service
24:bool bOk = ts.ModifyTask(ref delta, ref Error);
25:
26:if(bOk)
27:{
28:modifiedRow.modified = delta.task[0].modified;
29:ds.AcceptChanges();
30:ErrMessage.Text = “”;
31:}
32:else
33:{
34:ds.RejectChanges();
35:ErrMessage.Text = Error;
36:}
37:Bind(ds);
38:}
Lines 6–13 contain code to find the row in the local dataset to modify by matching what the user entered into the name text box with records in the local dataset.
Lines 17–18 modify the fields in the row to match what the user entered in the Due and Owner text boxes.
Lines 20–21 create a new dataset, called delta, that contains the modified records. Lines 22–24 send the delta dataset to the Web Service by calling the service’s ModifyTask method.
If the modification proceeds without any errors, the timestamp for the modified record is updated (Line 28), and Line 29 calls the AcceptChanges method. If the server returns an error, the RejectChanges method is called on Line 34.
