Rules-Driven WCF Router

Download sample

A SOAP router is an intermediary that forwards SOAP messages from a client to an application endpoint based on a set of rules. This sample creates a SOAP router using Windows Communication Foundation (WCF).

The router uses the Windows Workflow Foundation (WF) rules engine to implement the core router functionality that determines where to forward a given message. This sample shows two key concepts: how you can use Windows Workflow Foundation and WCF together in an application and how you can use the Windows Workflow Foundation rules engine outside of a workflow (also referred to as "standalone").

The sample consists of four projects: a calculator service, an echo service, a router, and a client. In this sample, the calculator and echo services are standard WCF services and are defined in the Calculator.cs and EchoService.cs files, respectively.

The router service uses WCF extensibility to process messages and other behavior, such as the handling of transport patterns (datagram/session, request-reply/duplex).

The RouterTable.cs source file defines the class that utilizes the WF rules engine to decide where to forward the message received from the client. As each message is processed by the router, the router calls RouterTable.SelectDestination() to obtain an endpoint address to which to forward the message, based on the contents of the message.

At this point, RouterTable.cs runs the SelectDestination RuleSet found in Selectdestination.Rules to determine which of the possible endpoints (Calculator service or Echo service) to forward the message to.

To understand or edit the SelectDestination RuleSet, you should open it using the External RuleSet Toolkit Sample found in the .NET Framework version 3.5 SDK.

To open the SelectDestination RuleSet

1. Start the External RuleSet Toolkit Sample application.

2. From the Data menu, click Import.

3. In the Open File dialog, select router\SelectDestination.rules.

4. In the RuleSet editor, click the SelectDestination RuleSet.

5. In the Workflow/Type Selection dialog, click Browse.

6. In the open file dialog, go to the router/bins folder and click WCF_Router.Router.exe.

7. In the Contained Types section of the Workflow/Type Selection dialog box, click RoutingTable, then click OK.

8. In the External RuleSet Toolkit application, expand SelectDestination, click Version 1.0, and then click Edit Rules.

9. When opened in the External RuleSet Toolkit, the SelectDestination RuleSet appears as shown in the following illustration.

The SelectDestination RuleSet from the External RuleSet Toolkit

There are six rules within the SelectDestination RuleSet. The following is a description of each rule, in order of highest to lowest priority.

1. Initialize variables: Initializes the variables in the RouterTable class so that the rest of the rules can use them.

2. CalculatorService: Checks whether a message matches the criteria for forwarding the message to the CalculatorService (the messages must contain the header "calculator"). If so, the CalculatorService endpoint is added to the list of possible endpoints to which the message can be forwarded.

3. EchoService: Checks whether a message matches the criteria for forwarding the message to the EchoService (the messages must contain the action message header http://microsoft.servicemodel.samples/iechoservice/echo). If so, the EchoService endpoint is added to the list of possible endpoints to which the message can be forwarded.

4. No matches: Checks whether there are no possible endpoints to which the message can be forwarded. If it is true, then this fact is logged to the console.

5. One match: Checks whether there is a single possible endpoint to which the message can be forwarded. If it is true, then forward the message to this endpoint.

6. Multiple match: Checks whether there are multiple possible endpoints we could forward the message to. If it is true, then forward the message to an endpoint randomly selected from the list of possible endpoints.

Note that this RuleSet uses a .NET Framework 3.5 feature for Windows Workflow Foundation rules: the ability to use the new keyword to invoke constructors of classes. For example, in the CalculatorService rule, if the message matches the criteria, the rule adds a new EndpointAddress to the list of possible addresses.

When you run the sample, the operation requests and responses are displayed in the client console window. Press ENTER in the client window to shut down the client.

Echo("Is anyone there?") returned: Is anyone there?
Add(5) returned: 5
Add(-3) returned: 2

To build and run the sample

1. To run the sample in a single- or cross-machine configuration, follow the instructions in Running the Windows Communication Foundation Samples, with the following exceptions:

   • In both the single-machine and cross-machine configurations, four projects and four executables are required—one for the client, one for the SOAP router, and one for each application service.

   • In a cross-machine configuration, the following changes must be made to the four configuration files:

   • Change line 21 of the App.config file for the CalculatorService and EchoService. The intermediary's real hostname must replace the localhost hostname.

   • Change line 16 of the router's App.config file. Change the two addresses (separated with a '|') to the hostname of the EchoService and CalculatorService, respectively.

   • Change lines 5 and 7 of the client's App.config file. The intermediary's real hostname must replace the localhost hostname.

   • You can also run the ServiceModel Metadata Utility Tool (Svcutil.exe) on the two application services (once they are updated to use the correct address) and regenerate the App.config files.

2. Ensure that the router, EchoService, and CalculatorService are all running before you start the client. Each of the three services prints out the endpoint addresses on which they are listening at startup.

   Note

   The EchoService and CalculatorService application endpoints use the router's address.

3. Run the client. The client first contacts the EchoService, and then the CalculatorService. The router displays the WS-Addressing actions of messages it is forwarding, in both directions.

   Note

   If Client.exe and Router.exe are on separate machines, uncomment the <identity/> section in Client.exe.config and set the user principal name to the one of the user running Router.exe.

See Also

Other Resources

External RuleSet Toolkit Sample
Intermediary Router

© 2007 Microsoft Corporation. All rights reserved.