How to: Consume a Disconnected Service Agent

The following procedure describes how you can consume the proxy and callback files generated by the Create Disconnected Service Agent recipe from your application code.

Prerequisites

You must have a disconnected service agent implemented. For information about how to do this, see How to: Create a Disconnected Service Agent.

Steps

To create and enqueue a request to a Web service using the proxy class

1. Add references to your project for the Disconnected Service Agent Application Block assembly SmartClient.DisconnectedAgent.dll.

2. Add references to your project for the project that contains the disconnected service agent (if the project that contains the disconnected service agent is located in a different project).

3. Add a using statement to your code for the Disconnected Service Agent Application Block namespace, as shown in the following code.

   using Microsoft.Practices.SmartClient.DisconnectedAgent;
   

4. Import into your code the namespace for the proxy and callback classes. The following code shows the using statement for the proxy in the Disconnected Service Agent QuickStart.

   using Quickstarts.DisconnectedAgent.IntegerCalculatorAgent; 
   

5. Create an instance of your proxy class, specifying the Request Manager's pending queue for the first parameter, as shown in the following code extracted from the Disconnected Service Agent QuickStart.

   IntegerCalculatorServiceDisconnectedAgent calculator;
   // ...
   calculator = new IntegerCalculatorServiceDisconnectedAgent(RequestManager.Instance.RequestQueue);
   

   Note

   Note: In smart client applications, a common practice is to register the service agent in the Services collection of a WorkItem. In those cases, you would get a valid service instance from the Services collection.

6. Optionally, create an OfflineBehavior instance and set the properties you need to customize the request. You can obtain the default OfflineBehavior configured for a method by calling the static method of the proxy named Get[methodName]DefaultBehavior, as shown in the following code extracted from the Disconnected Service Agent QuickStart.

   OfflineBehavior behavior = IntegerCalculatorServiceDisconnectedAgent.GetAddDefaultBehavior();
   

   As an example, you could specify one of the following properties for the OfflineBehavior:

7. Tag. This identifies the kind of request (such as "Update Route"). If you specify this, you will be able to use this Tag value elsewhere in your code to force dispatch of all requests with the tag.

   • MaxRetries. This is the maximum number of times that the disconnected service agent will attempt to dispatch the request before moving it to the dead letter (failed) queue.
   • Stamps. This is the number of stamps to indicate the relative importance of the request.
   • Expiration. This is the date that indicates when the request expires.

8. Call the method you require, passing to it any parameters required by this method and optionally an OfflineBehavior instance. For example, the first line of code calls a Web service method named Add, specifying the two parameters required by that method. The second line adds an extra OfflineBehavior instance to customize the request behavior.

   calculator.Add(1, 2);
   
   // or
   
   calculator.Add(1, 2, behavior);
   

9. However, before you can execute this code, you must also complete the code for the callback handlers in the callback handlers file generated by the recipe. Add code to specify the actions to take when the request succeeds or fails.

   public override void OnAddReturn(Request request, object[] parameters, int returnValue)
   {
       // Request succeeded so display values here - for example, show
       // the sum result by showing the returnValue in a MessageBox
       // or raise an EventBroker event with a subscriber on the UI thread
       // that will data-bind the results.
   }
   
   public override OnExceptionAction OnAddException(Request request, Exception ex)
   {
       // Handle the exception – for example, show a message to the user.
   }
   

Outcome

You will have application code that performs Web service requests using the Disconnected Service Agent Application Block to support occasionally connected smart clients.

Next Steps

The following are typical tasks that you perform after you consume a service agent:

• Perform entity translation. If your service agent does not contain logic for entity translation, you might need to write code to translate entities before and after calling the service agent's methods. To do this, you can use the EntityTranslatorService. For more information, see How to: Translate Between Business Entities and Service Entities.
• Update the UI with results received from the Web service. Because the return callback will be called in a thread other than the UI thread, you will need to implement the UI Threading pattern. For guidance about how to map business entities to UI elements, see How to: Map Business Entities to User Interface Elements.