How to: Consume a Disconnected Service Agent

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies.
This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
To create client business applications using current Microsoft technologies, see patterns & practices' Prism.

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.

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

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: 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.

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

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