Configuring a Custom WCF LOB Adapter with ESB 2.0 Toolkit

This post will show how to use BizTalk ESB toolkit 2.0 with the BRE Resolver for setting a custom WCF Adapter setting. In one of my current projects, my team and I were faced with creating some custom WCF LOB Adapters to communicate with various servers. Some of these servers were running on Unix based OS’s and even still others were proprietary and used serial line based communication protocols. In our implementation, we used BizTalk 2009 and the ESB toolkit 2.0 to create a massive ESB to send data to these systems. The interesting part about this does not rely in the fact that the systems we were communicating with were proprietary that warrants a separate blog posting about its trials and tribulations. The most intriguing part was that we had to support dynamic endpoints. We had to support ever changing Adapters, endpoints and worry about the addition of new systems coming online within months of going to production. By the way, all of this had to be accomplished without affecting the current production running solution. So, how do we accomplish this???


As we started to dive into the agile challenge at hand, we discovered that the overall concept of this project was using a Controller pattern. This is where commands are sent from “Controller” to client listeners. In our implementation, the Controller sent the command to the ESB, and it acted as a second “Controller” where it routed, transformed, duplicated, filtered, and suppressed the commands to various client listeners.

Figure 1 ESB Controller Pattern

We accomplished the routing, and transformation using BizTalk Business Rules Engine (BRE). The ESB toolkit 2.0 allows BizTalk Server to become an ESB, and within it there is a BRE resolver who uses the BRE to determine which transformation to apply, and which endpoint to send the information to. Using the BRE Resolver to determine a map is outlined in various blog postings, as well as samples inside the ESB 2.0 toolkit documentation so I won’t drill into the details on that. In addition to this, using the BRE Resolver to select a particular send Adapter (endpoint) in BizTalk is also outlined in various blogs and sample documentation, again I will not delve into that. However, using the BRE Resolver to configure a custom WCF LOB Adapter is not covered, and I have found it wanting on various blogs; thus the reasoning for this article.

In order to use the BRE Resolver to configure your send adapter, it is always best to verify the WCF LOB Adapter is successfully running and configured correctly using a Static Send port. Once this is done, this takes most of the guess work involved in dynamically setting it up.

In our example, we built a generic adapter around set of patterns we discovered when communicating to the various endpoints using Managed Extension Framework (MEF). I’ll blog on this in another posting. To continue, we have a custom WCF LOB Adapter called “Generic” which uses a MEF component to invoke the endpoint using any particular protocol needed.

Figure 2 Static Configuration of Send Port

To statically configure this, we use a WCF-Custom adapter, the genericAdapterBinding created using the WCF LOB Adapter framework, a Soap Action header of deleteCustomers, and an Uri set to generic://MefEndpointProcessor/MefSsoKey. Just for explanation of the Uri, the MefEndpointProcessor is the name of the MEF endpoint processor to use for a particular endpoint, and the MefSsoKey is a SSO Key used within the SSO Configuration database to retrieve any custom connection settings for the endpoint/server we are sending to.

Once we have configured this statically and it works, we’re ready to move on to the more interesting part, how to configure this using the BRE Resolver inside a Business rule and thus fulfill our requirement of adding endpoints dynamically without affecting the overall system at production time.

The steps to configure the WCF Custom Adapter at a high level are rather easy.

  1. First we need an itinerary which will use the ESB BRE Resolver, so create an Itinerary that receives the message from an OnRamp.
  2. Specify the Itinerary Service routing step to route the message.
  3. Within the Itinerary routing step, create a BRE Resolver to resolve the send adapter promoted properties to use for routing to the WCF Custom adapter.
  4. Create an Off Ramp extender, and an Off Ramp, specify the dynamic port for the off ramp.

To resolve the WCF Custom adapter dynamically, configure the BRE Resolver to use a policy which contains a set of rules that have actions that configure the endpoint settings.

Figure 3 BRE Policy for configuring WCF Custom LOB Adapter

The first step in creating a BRE rule to configure the endpoint is to create a policy, and add a rule to the policy using the BRE Composer. In our example our policy is named Tellago.Demos.ESB.BRE.

There are 2 rules within the policy, one named: isActionITV and the other isNOTActionITV. These rules check the incoming command message from the “Controller” to determine who to send the message to. If the action is set to ITV then the action that executes are a series of steps to configure the WCF Custom adapter to send it to the ITV Mef Processor, for transmission to the ITV endpoint.

The next step is to configure the actions within the rules. When using the ESB 2.0 toolkit, there are a set of vocabulary definitions installed that populate a dictionary collection of key=value pairs. These keyed items that need values populated are:

  • Endpoint Config
  • Endpoint Fix JAX RPC
  • Endpoint Message Exchange Pattern
  • Endpoint Outbound Transport Location
  • Endpoint Outbound Transport Type
  • Endpoint Target Namespace
  • Endpoint Transport Namespace
  • Endpoint WCF Action

The items in the collection we are interested in are the Endpoint Config, Transport Location, Transport Type, Target Namespace, Transport Namespace and WCF Action. Once these items are populated with values after the rules execute, the ESB uses the Adapter provider to promote the associated items in the collection for the dynamic configuration of the send port. In our example, the WCF adapter provider will be used to promote binding type and configuration, WCF action, namespaces and transport Uri values.

Specifically the WCF adapter type will be WCF-Custom; the transport location will be set to generic://MefEndpointProcessor/MefSsoKey; the WCF binding information will be set to <genericAdapterBinding><binding name=”genericAdapterBinding” /></genericAdapterBinding> (even though you only set the <binding…> portion of it and leave off the <genericAdapterBinding> section inside the rule); the namespace for the message will be set to http://Tellago.Demos.Schemas.EsbBreCommand; the WCF Action will be set to deleteCustomers.

When using the WCF Custom LOB Adapter, the WCF Adapter type must be set to WCF-Custom any other value will yield an incorrect configuration. The Transport location should be set to the Uri which the Custom adapter is expecting. The Endpoint Config is a set of values that support setting WCF behaviors, binding information, and any other custom information for WCF to run. To complete the configuration, WCF also requires the namespace of the message, and action to be set to a non-empty string value.

After you’ve completed all these steps, test it out you’ll be pleasantly surprised by the agility of the solution.

Happy ESB’ng