BizTalk 2006 R2 SP1 WCF Extensions

A few days ago a service pack for BizTalk 2006 R2 (known as BizTalk 2006 R2 SP1) was released and it includes a large number of rollup fixes accumulated from quite a few hotfixes. I ran it on my local development box and it installed fine for the most part. It did do have a hickup on HL7 though. It also includes some new product features which is a little unusual for a service pack release. Perhaps it should be called BizTalk 2006 R2.5. 🙂
One of the major new product features in the service pack is better tooling around WCF extensions. This post is going to give an introduction on how this worked prior to the service pack, then go through a brief tutorial of how I tested the new functionality. This post is based on SP1 beta so it is subject to change.
Prior to SP1:
If you implemented a WCF extension prior to SP1 then you had to go through a considerable amount of complexity to get the extension to show up in the BizTalk WCF port configuration pages. I retraced Richard Hallgren’s steps in his post as a good example of getting an WCF extension in the form of an EndpointBehavior. The relevant steps I want to focus on are:
  • Develop the extension behavior
  • Add a line similar to machine.config:
    <add name="addCustomWCFProperties" type="CustomWCFProperties.Behavior.PromoteUserNameBehaviorElement, AddCustomWCFPropertiesBehavior, Version=, Culture=neutral, PublicKeyToken=705e34637fdffc54" />
  • Configure the WCF port and choose the behavior.
The difficulty with this approach is that for every custom behavior (which might be used on a per port basis), you have to put stuff in machine.config. In most server environments this can require moving mountains to edit machine.config. Also, if you use behaviors on many ports it can quickly become difficult to manage. SP1 limits the scope of the config item to the executing host but it also introduces a couple challenges of its own. 
With SP1:
The current SP1 approach is to configure config options using a tab on the adapter handler properties. The directions are given for the custom send handler here:
Basically what is involved is importing a config file that has the custom behavior defined. The SP1 beta documentation mentions this as a custom binding but it means the custom behavior. Here is a screenshot of what the page will look like after SP1 is installed:
Then here is what the page looks like after you have imported a custom extension:
This current documentation does not provide a template or starting point for what the imported config file should be so there is essentially a gap. What I did was try to use the machine.config from the Pre SP1 directions because I thought this is the most direct route that people are likely to do after they run SP1. A better approach would be to use the template I have at the bottom of this post as a starting point for the config file you import.
Unfortunately the process is more complicated using machine.config because there are extra nodes in the machine.config that the import config button does not like.
You will get errors like:
Import WCF configuration
Unable to import configuration from file "C:Documents and
SettingsbencDesktopmachine.config".(System.Configuration.ConfigurationErrorsException) It is an
error to use a section registered as allowExeDefinition=’MachineOnly’ beyond machine.config.
(C:Documents and SettingsbencLocal
SettingsTempConfig73d27aa8-b21b-4d47-abeb-c81ec7a756fc.config line 202)
So if you want to go this route, follow these steps to clean the machine.config to the point that the page imports the config file properly. These steps are subject to what is in your machine.config. Also, I am not sure if any of these steps will have any undesired consequences and you should use these steps at your own risk. But these worked for me:
  • Copy your machine.config and work on the copy
  • Find all attribute occurences of allowExeDefinition="MachineOnly" and remove this attribute
  • Remove the commonBehaviors ConfigSection and Config elements and children
  • Remove the machineSettings ConfigSection and Config elements and children
  • Find behaviorExtensions element below <system.servicemodel><extensions> and remove all of the existing ones except for your custom ones.
Then try to import again and it should work. The screen will look exactly alike to the picture Richard Hallgren had for choosing the custom behavior, you just took a different path. The custom WCF extension behavior is the first in the list shown below:
I am guessing that the import config button is trying to merge part of the imported configuration into some master configuration and this is why it is failing. If you try to import a config file that does not cause errors and does not have any extensions, you will not get a message back that nothing was imported, the text box just stays blank.
You will then be able to select the custom behavior for a port running under the handler where you imported the config file.
I have found that it is actually possible to import the same config file multiple times across multiple handlers so this means it is possible to have one WCF extension configured for multiple BizTalk hosts.
Once you get through the wizard you can then export the WCFExtensions config file which gives you a template for the future that I have included here (not sure why the ESB line exported here):
<?xml version="1.0" encoding="utf-8"?>
  <enterpriseLibrary.ConfigurationSource selectedSource="ESB File Configuration Source" />
        <add name="addCustomWCFProperties"
type="CustomWCFProperties.Behavior.PromoteUserNameBehaviorElement, AddCustomWCFPropertiesBehavior,
Version=, Culture=neutral, PublicKeyToken=705e34637fdffc54" />
Here is a link to my exported .config file (shown above) that I used to successfully import Richard Hallgren’s
Hopefully the documentation will improve in the final version of BizTalk 2006 R2 SP1.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Blog at

Up ↑

%d bloggers like this: