The Disconnected Service Agent Application Block

Which provides management features for executing Web services from occationally connected smart client applications.

The application can maintain a queue of Web service requests when offline and then replay them when a connection to the server application becomes available.

Core Classes

1. RequestManager class - manages the request queues and uses the services of the RequestDispatcher class to dispatch these requests. It stores the queues of pending and failed requests.
2. Request class - is a store for a Web service request, including the arguments or parameters required by the Web service method.
3. ConnectionMonitorAdapter class provides information about the connection used by the request

Request Manager Subsystem

Controls the dispatching of Web service requests. It takes the messages from the queue and dispatches them when the application is online
It allows you to stop and start automatic dispatch, dispatch all pending requests, and dispatch individual requests.
The requests remain in the database until successful submission to remote server or until the request expires or when exceeding the specified number of retries.

You can access the single instance of the RequestManager class through its Instance property and by calling the initialize method with following parameters

1. The queues for pending and failed requests
2. A reference to a class that implements the IConnectionMonitor interface
3. A reference to a class that implements the IRequestDispatcher interface
4. An instance of the EndPointCatalog class that contains the endpoints to use for the request.

The Request Class Hierarchy

Provide features required to create individual requests to send to a remote Web service. It exposes the properties that define the behavior, parameters, endpoints, and other details for the request.
The Enqueue method add the request to the queue or dispatch it immediately.
It exposes the CallParameters property to contain the arguments for the Web service method.

You can also influence the behavior of a request through the OfflineBehavior class. It specifies the features of the request, such as the expiration, maximum number of retries, relaive importance of request, Tag value.

The OfflineBehavior class exposes two properties that allow you to define callback handlers for its ReturnCallback and ExceptionCallback properties as instances of the CommandCallback class.


The ConnectionMonitorAdapter Class

It exposes information about the underlying connection.
It allow you to handle in your code to get information about changes to the connection state. connectionStatusChange event occurs when the current connection state changes.


Initializing the Request Manager

Assume that the queues use the table names Requests and DeadLetter for pending and failed queues.

1. add referene

Microsoft.Practices.Smartclient.DisconnectedAgent
Microsoft.Practices.Smartclient.EnterpriseLibrary

2. Invoke any of the overloads of the static method Initialize.

RequestManager requestManager = DatabaseRequestManagerIntializer.Initialize();
it using the default database specified in the Data Access application Block configuration

// or

RequestManager requestManager = DatabaseRequestManagerIntializer.Initialize("databaseName");
You can specify a particular data base.

Creating a Simple Request

1. Create a new instance of the Request class and set the properties for this request. you must specify the name of the Web service method exposed by the remote server and the name of the endpoint.

Request req = new Request();
req.MethodName = "DeliveryRouteUpdate";
req.Endpoint = "MyWebServiceHost";

2. You must also specify the online proxy type for the request to allow the dispatcher to submit it to the remotr server. The proxy class is the one that Visual Studio generates when you add a Web reference to your project

req.OnlineProxyType = typeof(MyWebServiceProxy);

3. To specify the behavior of the request, set the properties of its OfflineBehavior instance using the Behavior property exposed by the Request class.

behavior.ProxyFactoryType = typeof(WebServiceProxyFactory);

4. Set the values of the other OfflineBehavior properties are required. eg Tag, MaxRetries, Stamps


Adding parameters to a Request

Create an array of type Object containig the parameters you want to pass to the Web service by using the static ToArray method ofthe CallParameters helper classs

int customerCode = 1234;
string comment = "New value for comment";
req.CallParameters = CallParameters.ToArray(customerCode, comment);

Handling Callbacks for a Request

1. The RequestDispatcher class calls one of two methods in your application code when a request succeeds or fails.
Create a class to contain these methods

public class MyDisconnectedServiceAgentCallbackClass
{
...
}

2. Create a method that takes

- references to the Request.
- an Object array for the parameters you submitted to the service.
- an Object for any value returned by the web service

public void MyReturnCallbackMethod(Request req, Object[] qParams,
Object result)
{
MessageBox.Show("Request succeeded. Return value is: "
+ result.ToString());
}

3. To get an indication of when a request fails, you create a method that takes as parameters a reference to the Request and an Exception instance. The method should return a value from the OnExceptionAction enumeration, either Dismiss or Retry.

public OnExceptionAction MyExceptionCallbackMethod(Request req,
Exception ex)
{
MessageBox.Show("Your request failed with error: " + ex.Message);
return OnExceptionAction.Dismiss;
}

4. Specify that the dispatcher should call these methods in your class by setting the relevant properties of the OfflineBehavior instance for your request.

req.Behavior.ReturnCallback = new CommandCallback(typeof(MyDisconnectedServiceAgentCallbackClass), "MyReturnCallbackMethod");
req.Behavior.ExceptionCallback = new CommandCallback(typeof(MyDisconnectedServiceAgentCallbackClass), "MyExceptionCallbackMethod");

Adding a Request to a Queue

Pass the configured request to the Enqueue method of the DatabaseRequestQueue instance.

reqManager.RequestQueue.Enqueue(req);

Removing a Request from the Queue

use the Remove method of the DatabaseRequestQueue instance

reqManager.DeadLetterQueue.Remove(req);

Accessing Requests in a Queue

You can reference the pending request queue using the RequestQueue property

IRequestQueue theQueue = reqManager.RequestQueue;

// or:

the "dead letter" or failed request queue using the DeadLetterQueue property

IRequestQueue theQueue = reqManager.DeadLetterQueue;

To remove a request from the queue use the Remove method of the queue.

theQueue.Remove(req);

Dispatching a Single Request Immediately

Call the DispatchRequest method of the RequestManager, passing to it the request to dispatch. The dispatching process is asynchronous.

reqManager.RequestQueue.Enqueue(req);
reqManager.DispatchRequest(req);

Dispatching all pending requests

reqManager.DispatchAllPendingRequests();

Dispatching Specific pending Requests

To dispatch requests having a specific value for their Tag property (say "Sales Order")

reqManager.DispatchPendingRequestsByTag("Sales Order");

Starting and Stoping the Dispatcher Service

To stop the dispatch of requests, call the StopAutomaticDispath method of RequestManager.

if (reqManager.Running)
{
reqManager.StopAutomaticDispatch();
}

To start the dispatch of requests, call the StartautomaticDispatch method of the RequestManager

if (! reqManager.Running)
{
reqManager.StartAutomaticDispatch();
}