Attaching an ESB 2.0 Itinerary To WCF Message Header

Attaching an ESB 2.0 Itinerary To WCF Message Header

Yesterday I was building a unit test to test an Http Adapter provider ( ) that we needed for communication with a Http based endpoint; and before you go down the road of why use HTTP Adapter vs the WCF Adapter and all its endless possibilities, the HTTP Legacy adapter didn’t have issues with badly formed messages like the WCF Adapter did.

When building the unit test, I wanted to use the ESB WCF Generic on ramps, and the WCF Adapter to send a message into the ESB. For those that don’t know this, there is a sample test client that comes with the ESB Samples. This test client contains code to embed an Itinerary and send this itinerary using a SOAP header. The sample also contains code to send to an ASMX web service, and a WCF service. In my opinion the samples are fairly cumbersome and awkward in regards to sending an itinerary into the ESB. Also, keep in mind that this test client was built for ESB 1.0, and ASMX focused doesn’t really take WCF and it’s power into account.

Thus the reasoning for this post…. I wanted to show that there are other ways accomplish this same goal, however using WCF, and the WCF InboundHeaders promoted property.

Let’s say I have an itinerary that looks as simple as this:

This itinerary uses a custom Http Adapter provider through the Resolve_Http_Endpoint resolver configuration to send in the message using the BizTalk HTTP Adapter.

To embed this itinerary into a WCF message, I’ll need to export this itinerary as XML and get the Itinerary content as such:

<Itinerary xmlns:xsi=\”\” xmlns:xsd=\”\” uuid=\”\” beginTime=\”\” completeTime=\”\” state=\”Pending\” isRequestResponse=\”false\” servicecount=\”1\” name=\”HttpLegacyItinerary\” version=\”1.0\” xmlns=\”\”><BizTalkSegment interchangeId=\”\” epmRRCorrelationToken=\”\” receiveInstanceId=\”\” messageId=\”\” xmlns=\”\” /><ServiceInstance name=\”DTSTwoWaySyncResponse\” type=\”Messaging\” state=\”Pending\” position=\”0\” isRequestResponse=\”true\” xmlns=\”\” /><Services xmlns=\”\”><Service uuid=\”dde8337957054bb79fbdb8be148d5c02\” beginTime=\”\” completeTime=\”\” name=\”DTSTwoWaySyncResponse\” type=\”Messaging\” state=\”Pending\” isRequestResponse=\”true\” position=\”0\” serviceInstanceId=\”\” /></Services><ResolverGroups xmlns=\”\”><Resolvers serviceId=\”DTSTwoWaySyncResponse0\”>&lt;![CDATA[STATIC:\\transportType=HTTP;transportLocation=http_legacy://localhost/MyApp/default.aspx;action=;endpointConfig=RequestTimeout=30&amp;ResponseStatusCode=200;jaxRpcResponse=false;messageExchangePattern=;targetNamespace=;transformType=;]]&gt;</Resolvers></ResolverGroups></Itinerary>

Now that I have the itinerary content, I can use one of the Generic WCF Onramps, or create my own, which is actually what I did. To create your own WCF Generic on ramp:

  1. Create a BizTalk Receive Location inside the ESB BizTalk Application using the BizTalk Admin Console.

  2. Configure the Receive Location to use a WCF-Custom adapter. I choose to use the netTCP Binding with all the default settings. The Uri for this adapter was set to: net.tcp://localhost:8888/ReceiveMsg/service.svc

  3. Configure the Receive Location to use the ItineraryReceivePassthrough pipeline with all the defaults.

  4. Create a Dynamic Send port that matches the filter expressions you created inside the Itinerary. Mine were set to

    1. … ServiceName=DTSTwoWaySyncResponse

    2. … ServiceType=Messaging

    3. … ServiceState=Pending

    4. … IsRequestResponse=True

After I configured all the BizTalk receive and send ports, I needed the client code in my unit test project to invoke and send the test message to the WCF Generic on ramp, along with the attached itinerary as a Soap header (WCF Message Header).

To Configure a client with the message header I created a unit test with a method marked up with the [TestMethod] attribute and added the following code:

NetTcpBinding b = new NetTcpBinding ();

EndpointAddress epa = new EndpointAddress ( “net.tcp://localhost:8888/ReceiveMsg/service.svc” );

IBizTalkReceiveLocation proxy = ChannelFactory < IBizTalkReceiveLocation >.CreateChannel(b, epa);

Message msg = Message .CreateMessage( MessageVersion .Default, “SendToBizTalk” ,

XmlTextReader .Create(

new StringReader (

“<?xml version=\”1.0\” ?><TestMessage>Post To Http Adapter</TestMessage>” )));

Write_ItineraryTo_WCF_InboundHeaders( ref msg);


The Method of interest here is the “ Write_ItineraryTo_WCF_InboundHeaders(ref msg);” line of code.

This method is outlined here:

private void Write_ItineraryTo_WCF_InboundHeaders( ref Message wcfMessage)


// code taken from msdn:

//const string PropertiesToPromoteKey = “;;

const string PropertiesToWriteKey =; ;

//XmlQualifiedName propItinerary = new XmlQualifiedName(“Itinerary”, “;);

XmlQualifiedName writeItinerary = new XmlQualifiedName ( “Itinerary” ,; );

//Create a List of KeyValuePairs that indicate properties to be promoted to BizTalk message context.

//A Property Schema must be deployed and string values have a limit of 256 characters

//List<KeyValuePair<XmlQualifiedName, object>> promoteProps = new List<KeyValuePair<XmlQualifiedName, object>>();

//promoteProps.Add(new KeyValuePair<XmlQualifiedName, object>(propItinerary , HttpLegacyItinerary ));

//wcfMessage.Properties[PropertiesToPromoteKey] = promoteProps;

//Create a List of KeyValuePairs that indicate properties to be written to BizTalk message context

KeyValuePair < XmlQualifiedName , object > pair = new KeyValuePair < XmlQualifiedName , object >(writeItinerary,


List < KeyValuePair < XmlQualifiedName , object >> writeProps = new List < KeyValuePair < XmlQualifiedName , object >>();


XmlSerializer ser = new XmlSerializer ( typeof ( Itinerary ),; );

//XmlSerializerNamespaces ns = new XmlSerializerNamespaces();

//ns.Add(“itin”, “;);

Itinerary itin =

( Itinerary )ser.Deserialize( XmlDictionaryReader .Create( new StringReader (HttpLegacyItinerary)));

MessageHeader header = MessageHeader .CreateHeader( “Esb” , “” , itin, new myItinerary (itin, “i” ,; ));

// code for testing the Itinerary pipeline component…

//string str2 = header.ToString(); // .Replace(“\r\n”, “”);

//string pattern = “<[a-zA-Z0-9]:Itinerary.*?</[a-zA-Z0-9]:Itinerary>”;

//string str = Regex.Match(str2, pattern).Value;


wcfMessage.Properties.Add(PropertiesToWriteKey, writeProps);

//wcfMessage.Properties[PropertiesToWriteKey] = writeProps;


This method takes the itinerary content as a string, and deserializes it into an actual Itinerary class from the ESB Itinerary OM v1.0 assembly. This class then used to create a WCF Message header using the MessageHeader.Create static method call.

There’s one major note here to pay attention to…

The ESB Itinerary pipeline Component that is used with the ItineraryReceivePassthrough pipeline retrieves the Itinerary from a SOAP 1.x message header which is written (not distinguished/nor promoted) into the BizTalk Message context by either the SOAP adapter, or the WCF Adapter. When using the SOAP legacy adapter in BizTalk, SOAP headers are automatically written to the message context, again I must stress, that they are written, not promoted, nor distinguished. This means that the values are not available to orchestrations, nor routing capabilities by default. To get these values promoted, then you have to deploy a property schema with the correct SOAP target namespace. For WCF adapters, however, to get the headers promoted or written you must follow this msdn article:

The component uses a regular expression in order to find the itinerary inside the Soap Headers content. The Regular expression is: string pattern = “<[a-zA-Z0-9]:Itinerary.*?</[a-zA-Z0-9]:Itinerary>”;

What this regular expression tells us is that we must take care to add a prefix qualifier with exactly 1 character to the Itinerary Message Header, otherwise, your itinerary will not be found. Also make sure that you don’t use the “ a” prefix qualifier, as this is already take by WCF and SOAP specifics. Thus any other value will do fine.

Well in order to do this I had to use the overridden MessageHeader.Create() static method, which supports the use of a custom XmlObjectSerializer. This will allow me to control the serialization of the ESB Itinerary so that I may achieve this functionality. This is outlined in the following code:



private Itinerary itin = null ;

private XmlSerializerNamespaces ns = null ;

private XmlSerializer ser = null ;

public myItinerary( Itinerary itin, string prefix, string nameSpace)


this .itin = itin;

ns = new XmlSerializerNamespaces ();

ns.Add(prefix, nameSpace);

ser = new XmlSerializer ( typeof ( Itinerary ),; );


public override bool IsStartObject( XmlDictionaryReader reader)


return true ;


public override object ReadObject( XmlDictionaryReader reader, bool verifyObjectName)


return ser.Deserialize(reader);


public override void WriteEndObject( XmlDictionaryWriter writer)



public override void WriteObjectContent( XmlDictionaryWriter writer, object graph)


ser.Serialize(writer , this .itin, this .ns);


public override void WriteStartObject( XmlDictionaryWriter writer, object graph)




This custom XmlObjectSerializer class just uses the XmlSerializer behind the scenes, and a XmlSerializerNamespaces instance to add the prefix and namespace setting when serializing the Itinerary ESB OM v1.0 class back into the message stream with a single character prefix qualifier.

After all this was done, I was able to send the test message into the WCF Channel, with the attached WCF Message Header containing the ESB 2.0 strict Itinerary.

Case Closed!!!

Overstanding the ESB Itinerary Cache

Overstanding the ESB Itinerary Cache

If you Google-Bing the ESB Itinerary Cache you come across a definition of the likes: “ The itinerary cachingpipeline component for use in Solicit-Response send ports.”


Messages submitted through the ESB itinerary on-ramp can be either a one-way or two-way (request-response) itinerary. To support request-response itineraries, the itinerary mechanism must provide caching for BizTalk dynamic Solicit-Response send ports.

The Itinerary Cache pipeline component persists the itinerary stored in the outbound message and reapplies it to the response message returned to the send port after the service call is complete. This allows the itinerary service to process and execute other services defined after the current service in the itinerary.

The ESB Itinerary Cache pipeline component caches the itinerary during the period that the message is in the Send Transmit pipeline process cycle. The component then retrieves the itinerary and writes it to a BizTalk context property in the inbound message after receipt during the Send Receive process cycle.”

The above definitions are taken directly from MSDN…

There is no need to further explain what this component is used for as the above definitions handle this nicely…

Question: How does this thingy-magiggy work???

Answer:Under the hood, the ESB ItineraryCache is a pipeline component that caches the Itinerary into a cache object defined the the Enterprise Library 4.1 caching application block mechanism upon sending the message, and retrieves the itinerary from the cache upon receiving the the message. Thus this component functions differently upon if the component is executed from a Send pipeline versus a Receive Pipeline.

The Default Mechanism:

By default this caching is done in memory and only caches your itinerary for 5 minutes. The Itinerary is stored and retrieved through the Cache object collection using the CorrelationContextPropertyName property which is set on the pipeline component property sheet. Again, by default the value for this property is the TransmitWorkID context property which can be found as a BizTalk system property.

What is interesting to note here, is that for every itinerary that is transmitted or received, this property must be promoted in order to write or read to the caching collection; along with the fact that the value for this property must be unique within a 5 minute time span, otherwise an non-unique key argument exception will be thrown. Also by default, this property is only promoted by BizTalk when the message is received from a 2-way Receive Port. This property is usually used in conjunction with the IsRequestResponse , the IsSolictResponse, the WasSolicitResponse , and the RouteDirectToTP BizTalk system properties to help correlate 2-way synchronous responses within BizTalk 2 way adapters, orchestrations, and other 2 way patterns. Thus, if you are not using a 2 way receive port, 2-way Receive Adapter, or Correlated 2 way design pattern, these properties, including the TransmitWorkID will not be promoted. This means that by default you won’t be able to use the itinerary caching component.

Another note to take interest in is that when using this caching component, upon transmission (sending) of the message, the component will only write the itinerary into the cache if a few conditions are met:

  1. The ESB determines that the direction of the message flow is a true “SendTransmit”. How the ESB Determines this condition is using two branches. The first branch checks to see if the IsRequestResponse property is true. If so, the ESB continues to check for conditions that do not satisfy the Receive Transmit (the sending side of a 2 way receive port), or Receive Inbound (the receiving side of the 2-way receive port). The Receiving Transmit conditions are simply checked against the Send Port Name being promoted and WasSolicitResponse containing any value; whereas the Receiving Inbound conditions are checked against the Receive Port Name being promoted. If these cases are not true, ESB checks for the IsSolicitResponse = true , which determines that the message direction is a true “SendTransmit”. The second branch checks for the case of IsRequestResponse = false. If the Receive Port Name, and Send Port Names are not promoted, nor is the WasSolicitResponse = true, then the ESB checks for the Send Port ID property to be promoted, in which signals the message direction to be a true “SendTransmit”
  2. BizTalk has properly promoted the BTS.IsRequestResponse or the ESB Itinerary.IsRequestResponse properties to true. This is done again by using a 2 -way Receive Port, or using an Itinerary, Itinerary Routing shape, Off Ramp or Off Ramp extender and setting its IsRequestResponse property to “ true”, and in some cases, all of the shapes in question must have these properties to “true”.

  3. When writing the Itinerary to the cache, the CorrelationContextPropertyName value exists.

  4. When writing the Itinerary to the cache, a duplicate does not already exist for the CorrelationContextPropertyName value.

Upon receiving the message, the same type of checks are also evaluated when trying to retrieve the itinerary from the cache:

  1. When reading from the cache, the CorrelationContextPropertyName value must exist.

  2. The ESB determines that the direction of the message flow is a true “SendInbound”. How the ESB Determines this condition is also using two branches. The first branch is exactly like the “SendTransmit” logic, the only exception being ESB does NOT check for the IsSolicitResponse = true; however does check to see if the Send Port Name is promoted, which determines that the message direction is a true “SendInbound”. The second branch is also similar to the “SendTransmit” with the only exception being the if the Send Port Name is promoted, the message direction is considered a true “SendInbound” .

If you don’t want to be subjected to using 2-way receive ports, or you want to use this Caching mechanism outside the scopes of a 2-way Send port (i.e. a 2-way Asynchronous design pattern), you can use a custom CorrelationContextPropertyName , and Namespace setting, and override the default IsRequestResponse , WasSolicitResponse , and optionally RouteDirectToTP (for sending back to the original caller), system properties. If you’ve read above, you should have a basic overstanding of how the Itinerary Cache works, which should allow you to be dangerous in how to model 2 way Itineraries. See a future post on this…

Extending the Default Caching Mechanism:

Extending the default Itinerary Caching component is as simple as changing the default CorrelationContextPropertyName , or changing the Timeout property, Creating a custom Itinerary Caching component, or even the default Caching manager.

If you don’t want to be subjected to using 2-way receive ports, or you want to use this Caching mechanism outside the scopes of a 2-way Send port (i.e. a 2-way Asynchronous design pattern), you can use a custom CorrelationContextPropertyName , and Namespace setting, and override the default IsRequestResponse , WasSolicitResponse , and optionally RouteDirectToTP (for sending back to the original caller), system properties. If you’ve read above, you should have a basic overstanding of how the Itinerary Cache works, which should allow you to be dangerous in how to model 2 way Itineraries. See a future post on this…

Routing 2-way Synchronous response to endpoints other than the initiator

Routing 2-way Synchronous response to endpoints other than the initiator

Recently, in our implementation of an ESB 2.0 BizTalk 2009 solution, a requirement popped up where an endpoint initiates a request to a synchronous system, and the system responds back with a response. In typical development practices, this is referred to a request/response or client/server pattern. You may say to yourself, “big deal, this is easy…” In a normal solution, the response is routed back to the initiator of the request. Lo and behold, we came across a scenario, where the response needs to be routed to other endpoints based on fairly complex rules and processes; not the original caller (initiator), hence the purpose of this blog entry.

As a BizTalk Developer, you say the above is not a problem. Why? Because BizTalk can handle designs like this with ease, using orchestrations, static send ports with unique filter expressions, and even orchestrations with dynamic send ports. You can actually put the complex logic, rules and processes inside custom components, or the Business Rules Engine (BRE) within orchestrations or even pipeline components. However if we’re staying true to the Agile game, and we want to build a architecturally sound ESB, using the normal BizTalk approach doesn’t fit the bill, in other words, it won’t work. The reasons why are simple, we either loose Agility, gain invisibility, create a mystery black box with custom code, or have increasingly complex algorithms which are prone to break and miss the agile mark altogether. The goal here is to think about BizTalk 2009 and the ESB 2.0 toolkit as a set of capabilities and then model the capabilities to generate the result you want.

Question: So now what capabilities do we need?

Answer: We want the ability to design steps or process flow which accepts a message from an initiator, and then based off of some rules, dynamically determine the 2 way service, retrieve the response and through more rules dynamically send the response to another endpoint who is not the initiator.

Question: So which capabilities match BizTalk and ESB?

Answer: The capabilities to design steps and process flows are the Itineraries pattern of ESB. The BizTalk Business Rules Engine incorporates the complex logic. The ESB Resolvers assist to resolve logic, and endpoint addresses, such as the 2 way service to invoke, and the resulting endpoint to send the responses to. In addition to the resolvers, BizTalk provides WCF Adapters to send and receive the request/response and results.

Question: So how do we do this?

Answer: You model an itinerary in BizTalk 2009’s ESB 2.0 using the Itinerary designer that accepts a message from a caller (initiator), and then sends the request to a 2-way Synchronous Endpoint, which then blocks (correlates automatically for the response) and then sends the Response to a completely different endpoint based off of a Business rule.

Question: Is this easy?

Answer: Yep Follow these high level steps:

  1. Create an Itinerary using the ESB Itinerary Designer.

  2. Configure the Itinerary to use a 2-way Receive Port, even though you will use a 1-way receive port in production.

  3. Configure the Itinerary to be a Request/Response Itinerary, which is to say verify the IsRequestResponse = true. (See the Itinerary Cache Post for more info on this…

  4. Model the itinerary with with the call the the synchronous request/response endpoint.

  5. Within your steps, use the BRE Resolver to determine maps, and endpoint addresses for the configuration of which synchronous endpoint to send the request to.

  6. Optionally: Use the Service Broker shape to route to different endpoints based off of promoted properties from the response.

  7. Lastly, use a Business Rule Resolver to dynamically determine the resulting endpoint configurations.

Below is an example of an Itinerary which uses Business Rules to invoke a Synchronous endpoint and routes the results to another endpoint which is not the initiator.

Explanation of Itinerary:

The above image can be read following the directions of the arrows, starting with the upper Left shape named: ReceiveMsg . This first shape signifies an ESB OnRamp, which equates to a BizTalk Physical receive port.

The next shape: MapToCanonical represents an ESB Messaging Step. Messaging steps are processes or components that are destined to execute inside of pipelines. These pipelines are configured with ESB based pipeline components such as the ESB Dispathcher, which understand the Itinerary step mechanism to execute ESB Itinerary steps. In the above example, the MapToCanonical step uses a Transform based ESB Step process to execute a BizTalk transformation (Map) to convert the message received from the OnRamp into a canonical message format. The map which executes is determined by the ESB Resolver: SetMapToCanonical . This resolver utilizes the BRE Resolver to execute and evaluate complex logic using the BizTalk Business Rules Engine (BRE) to choose the correct map for transformation.

The next step: RouteToEndPoint is another ESB messaging step, which utilizes the ESB Routing process to promote properties and publish the message to the BizTalk Message box. This step is configured to use the BRE Resolver named: GetURI . This resolver executes business logic and evaluate rules to determine the URI address, and Send adapter to send the request to.

The next step: PushToMsgBox, is an off ramp extender shape which gathers more promoted property information from the actual ESB OffRamp: SendToEndPoint (BizTalk Physical Send Port). Here’s an interesting point to note, remember that the ESB Itinerary pattern is just a model to design steps as in the order of execution, not the actual process such as an orchestration. As we define our steps, BizTalk needs to know where these ordered steps should execute. In other words, when we use “Messaging Steps” these obviously execute inside Messaging components of BizTalk, hence pipelines stages. However, for BizTalk we have two sides of the messaging system. BizTalk has a messaging stack before saving to the Message Box (Receive Pipelines), and a stack after the Message Box (Send Pipeline). In the design above, the PushToMsgBox off ramp extender is used to signify all steps after this will execute in the Send Handler (Send pipeline stages).

The next step after the off ramp extender is the MapToEndPoint step. This step, again is a messaging step which uses the BRE Resolver named: SetMapToEndPoint , will be executed after the message is published to the BizTalk Message box, and inside the send pipeline associated with the send port configured through Off Ramp: SendToEndPoint .

The next step is the SendToEndPoint ESB Off Ramp. This Off Ramp is configured to use a 2-way Solicit-Response dynamic send port. From a BizTalk perspective, the 2-way dynamic send port is configured to use a send pipeline which contains the ESB Dispatcher pipeline component, and the ESB Itinerary Cache pipeline component. The receive pipeline is configured to use the ESB Itinerary Cache, Xml Disassembler, and the ESB Dispatcher components respectively. The 2-way send port is also configured with the 4 basic ESB promoted properties within the Filter expression. Screen shots of the various properties and values are provided below.

The next step is MapResponseToCanonical . Notice here that the messaging step is set to run in the Receive Handler (Receive Pipeline) of the SendToEndPoint off ramp. This means that this step runs on the receiving side of the 2-way dynamic send port. This step is configured to use the ESB Transformation service, and the BRE Resolver to again determine which map to use for transformation. This step transforms the reponse to a canonical format to eventually publish back to the Message Box.

The next step is RouteResponseToEndPoint, just like step before, this step also is configured to execute in the Receive Handler of the SendToEndPoint off ramp. Which also means it will execute on the receiving side of the 2-way dynamic send port. This step is also configured to use the ESB Routing service and again the BRE Resolver to determine the Endpoint URI and adapter to use to send the final response.

The next step is PushResponseToMsgBox. This step is an off ramp extender which signifies that the remaining steps will be executed after the message is published to the Message Box, along with any other special properties that need to be promoted.

The next step is MapResponseToEndPoint, this step is a messaging step which again uses the ESB Routing Service and the BRE Resolver to determine the Uri address and BizTalk Send adapter settings to use for sending the response.

The last step is SendResponseToEndPoint, this is the Off Ramp which points to a simple Dynamic Send port for actually sending the response from BizTalk.

64 Bit ESB/BizTalk Lessons Learned

As some of you are well aware of. We at Tellago ( are implementing a major ESB 2.0/BizTalk 2009 (64 bit) solution. This blog posts servers as a reminder of the configurations, issues, and *gotchas* we have identified thus far. So this list will be a living list J

  1. Beware of the applications that are really 32bit running on a 64bit host. Use the Task Manager to check to see if it’s a 32bit or 64bit process
    1. For example when configuring behaviors or anything that is done in a configuration file for any normal WCF Service using the SvcUtility (which is a 32bit process), the settings need to be applied in the 32bit configuration file to see it, as well as in the 64bit configuration file locations. *Twice as nice* – yeah
    2. Locations to be aware of for the Machine Config:
      1. %windows%\Microsoft.Net\v.x.x\Framework64\Config
      2. %windows%\Microsoft.Net\v.x.x\Framework\Config
    3. Another example is when configuring a WCF Custom adapter using the BizTalk Admin Console (32bit process) reads the Machine configuration from the 32 bit location as outlined above instead of the 64 bit locaiton, however the runtime reads it from the 64 bit location *gotcha*!!! Thus any behaviors or custom bindings needs to be configured in both the 32bit and 64bit machine configuration files…. !!!
  2. When using The BRE with classes that use static methods the Registry location has changed for 64 bit it’s now in the Wow6432Node… however the StaticSupport value is a DWORD(32 bit) not 64bit… *Gotcha*!!!
    1. Static Support:
      1. HKLM\Software\Wow6432Node\Microsoft\BusinessRules\3.0\
      2. Value to set: StaticSupport DWORD (32bit) 1
  3. When configuring WCF Custom Isolated URL’s in IIS 7.0 64bit: Don’t copy paste Urls, manually type them in. *gotcha*!!!
  4. For BizTalk configuration, trace sources, SVC traces and etc… change the BizTalk 64bit exe configuration file.
  5. When running WCF-CustomIsolated, and IIS 7.0 applications, verify that the assemblies running in this space are not limited to 32bit hosts, if so, run the application pool as a 32 bit host only mode.
  6. Beware of using the BizTalkExplorerOM classes in components, by default this library does not support 64 bit. To use any of this library, you must run it in a 32 bit Default Host, or recompile the component that uses this library with the 32bit compile option in VS.NET; just make sure you change it from the default *any* compile option. There is an MSDN article on this I’ll post it later…
  7. MIME Decoder only supports 32 bit. Thus you’ll need to run this in the 32bit Host instance
  8. SQL Adapter (Not WCF-SQL Adapter with the WCF LOB Adapter Kit) only supports 32bit Host Instance
  9. Beware of using Dynamic Send Ports with a 32 bit default host. All dynamically configured adapters will use the Default Host Instance for that 32bit Default Host. There is no way to dynamically configure which Host a dynamic adapter will use.

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