ESB Toolkit 2.2 Beta (Windows Azure VM): Configuration

February 25, 2013 4 comments


The following is a “brain-dump” of my experiences configuring ESB Toolkit 2.2 on a Windows Azure VM using the BizTalk Server 2013 beta (February 15th 2013 revision) on Windows Server 2012.

What’s New

There have been some enhancements made to the ESB Configuration Tool.

Default Configuration

The ability to apply a default configuration, similar to that provided with the BizTalk Server Configuration Tool, has been added. Clicking on the root tree node, ESB Configuration, produced an empty screen in previous versions of the ESB Toolkit but with ESB Toolkit 2.2 the following screen containing default configuration properties appears.


Using this screen we can set default values for the Database Server, IIS Web Services and the BizTalk User Groups and have those applied across to the Exception Management and ESB Core Components.

This simplifies the configuration for typical installations. For greater control of the configuration the Exception Management and ESB Core Components can be customised using the approach provided with previous versions of the ESB Toolkit.

ESB BizTalk Applications

This is a new node that has been added to the configuration tool. It consists of two options; Enable ESB Core Components in BizTalk Server and Enable ESB JMS/WMQ Components in BizTalk Server.


These replace the post configuration steps that were required with previous versions of the ESB Toolkit which involved manually running MSI’s to create the BizTalk Server Applications.

Moving these steps of the configuration process to the configuration tool is an obvious progression and you’d have to wonder why they were ever left as a manual step when the configuration tool was first introduced with ESB Toolkit 2.0.


As mentioned above a custom configuration is similar to the steps followed in previous versions of the ESB Toolkit, so we’ll cover a default configuration here.

1. Launch the ESB Configuration Tool.

2. Click on the ESB Configuration node and enter the Database Server, User Account and Password. The Website Name can be selected here – I’ve left it as the Default Web Site. I’ve also left the default BizTalk User Groups as this is an isolated configuration.


3. Click on the ESB BizTalk Applications node.


4. I am just going to install the ESB Core Application so select the Enable ESB Core Components in BizTalk Server checkbox and leave the Use Default Binding option selected.


5. Click Apply Configuration


The steps above should result in a fully configured ESB Toolkit. Some of the issues I encountered in reaching this point have been listed below.

IIS Install Registry Key is missing. Check that you have IIS 6.0 Extensions installed.



The ESB Toolkit is still reliant on IIS 6.0 extensions which are not installed by default on the Windows Azure BizTalk Server 2013 Beta image. To resolve this issue you must install the IIS 6 Management Console feature.


Note: The IIS 8 Management Console feature is not installed by default either on the Azure image but that is not a pre-requisite for the ESB Toolkit.


Cannot open database BizTalkMgmtDb on server XXXXX. Verify that you have the required security permissions and that communication between…(the error message cuts off here).



So far I have been unable to reproduce this error.

Application: Microsoft.Practices.ESB already exists



In an attempt to resolve the error in 2 above I decided to test out the resilience of the ESB Configuration Tool when things go wrong. I re-applied the configuration again and this time received the error above informing me that the Microsoft.Practices.ESB application already exists. Clearly the ESB Toolkit Configuration Tool still doesn’t support rollbacks or idempotency.

DeployPolicyAsResource failed (full error message is not visible)



After my attempt to re-apply the configuration in 3 above was unsuccessful I carried out the following steps to allow me to retry the configuration.

1. Click Unconfigure Feature


2. Select EsbBizTalkApplications and click Accept


3. The ESB BizTalk Applications features are now unconfigured


The reason for just unconfiguring the ESB BizTalk Applications is because I was able to identify this step as the one where the original error occurred. I could see that each of the other steps had completed successfully by viewing their state. This is done by clicking on their nodes in the ESB Toolkit Configuration Tool; a greyed out screen indicates a configured component.

After unconfiguring the ESB BizTalk Applications I selected Enable ESB Core Components in BizTalk Server again and applied the configuration which produced the “DeployPolicyAsResource failed” error.

As can be seen in the screen shot above the full error message is not visible. However, hovering over the ESB BizTalk Applications node (or any node that resulted in an error) will briefly show a tool tip containing the full error message. Depending on the size of the error message this can take a number of attempts to view the full error, as was the case here.

I was able to see that the error was being caused by the existence of the ESB.Deployment.Policy policy in the BRE which couldn’t be overwritten as it was in the “Deployed” state.

This was confusing as I had assumed that unconfiguring the ESB BizTalk Applications would have resulted in the Microsoft.ESB.Practices artefacts, including the ESB.Deployment.Policy policy, being removed.

I unconfigured the feature again and performed a visual check and confirmed everything had been removed even going as far as checking the database tables. However, no matter what I tried the same error appeared.

As a last resort I decided to unconfigure the ESB BizTalk Applications, close the ESB Toolkit Configuration Tool, launch the ESB Toolkit Configuration Tool and configure the ESB BizTalk Applications.


Result! It appears that caching in the ESB Toolkit Configuration Tool was the cause.


The enhancements that have been made to the ESB Toolkit Configuration Tool fully automates the configuration process and will hopefully remove the initial barrier to adoption I have spoken about on previous posts. There is still room for improvement though, particularly when things go wrong. Not being able to view the full error message is frustrating. Hopefully with it being a cosmetic fix this will be resolved in the final release.

Be sure to install the IIS 6 Management Console feature prior to configuring the toolkit and in the event of an error during configuration:

  1. Unconfigure the offending component
  2. Close the ESB Configuration Tool
  3. Launch the ESB Configuration Tool
  4. Re-configure the component

BizTalk Server 2010 Map Deployment Bug

June 18, 2012 6 comments

This is more of a “note to self” but I feel it is worth sharing with the community.

Microsoft recommends that hot fixes should only be applied if you are experiencing the issues they address. There are good reasons for this, mainly around the amount of testing a hot fix goes through in comparison to a service pack.

I am going to go against that advice for BizTalk Server 2010 installations and add “Cumulative Update Package 1” to my installation checklist. This is to avoid a bug that has been present in every BizTalk Server 2010 environment I have installed and configured; from development machines to production servers.


I first came up against this bug through being trigger happy with the Deploy menu item on a transforms project. I mistakenly deployed the transforms project before deploying one of the schema projects it referenced. Whilst previous versions of BizTalk Server would have prevented the transforms project from being deployed, BizTalk Server 2010 allows it.

The Bug

The bug manifests itself in the BizTalk Server Administration Console. When trying to expand the Applications folder you will receive the following error:

Schema referenced by Map ’map_name’ has been deleted. The local, cached version of the BizTalk Server group configuration is out of date. You must refresh the BizTalk Server group configuration before making further changes.

Refreshing the BizTalk Server group does not resolve the issue and the error continues to appear. This prevents access to every application in the group.

For further information on the bug have a read through Knowledge Base article 2516201

This has been covered under VSTS Bug number 678144 and is fixed in Cumulative Update Package 1 For BizTalk Server 2010.

The Fix

Applying the CU will only prevent the issue from occurring again by generating an error in Visual Studio. In the case of an MSI deployment, the error will appear during the import. However, it will not resolve the problem in the BizTalk Server Administration Console.

To remove the error you must delete the offending map in the transforms project from the bt_mapSpec table in the BizTalkMgmtDb database.

-- Locate the itemId of the map
Select * from bt_mapspec
-- Using the itemId retrieved above delete the map
Delete from bt_mapspec Where itemid = 'itemId_of_map'

On refreshing the BizTalk Server group the error will disappear and the applications can be accessed again.

Deleting entries from the BizTalk Server tables is not something I am overly comfortable with, but unfortunately it was the only resolution I could find to get rid of this particular error.

ESB Toolkit 2.1 Training Kit

I was browsing through the BizTalk Server Downloads section on MSDN recently and came across an excellent resource for BizTalk Server professionals looking to learn and leverage the capabilities of the ESB Toolkit.

BizTalk Server 2010 ESB Toolkit Training Kit

I wasn’t aware of it’s release and it doesn’t appear to be publicised anywhere on Microsoft’s site but I highly recommend you check it out.

The kit contains hands-on labs, PowerPoint slides and instructor-led videos. There is also the option to download two virtual machines for use with the labs.

The topics covered are:

  1. Understanding the BizTalk ESB Toolkit
  2. Installing the BizTalk ESB Toolkit
  3. Processing Messages Using the ESB Itinerary Mechanism
  4. ESB Pipeline Processing
  5. The ESB Resolver and Adapter Provider Framework
  6. Using ESB External Services
  7. Exception Management and the ESB Management Portal
  8. Modifying and Extending the ESB Toolkit


ESB Management Portal Customization

March 23, 2012 3 comments

The ESB Management Portal that ships with the ESB Toolkit is a sample site and is intended as a starting point for building your own portal for exception management and beyond.

This view of the portal is something that is often overlooked with the assumption made that it is a production ready component of the ESB Toolkit.

To make the most out of the portal it should be customized to suit the needs of your client or enterprise.

Resubmitting XML

The first customization required is to facilitate the resubmission of failed XML messages. “Out-of-the-box” fault messages are logged with a content type of “text/plain”. This results in only HTTP On-Ramps being visible in the resubmission location drop-down list.

To resolve this modify the usp_insert_Message stored procedure in the EsbExceptionDb as follows

IF (@ContentType = 'text/plain' AND LEFT(@MessageData,1) = '<')
  SET @ContentType = 'text/xml'

This will set the content type of all XML fault messages received to “text/xml” resulting in the WCF and SOAP On-Ramps being visible in the resubmission location drop-down list.

While there are many customizations that should be applied to the portal this is the main one to make if you require the ability to resubmit XML messages, which I am certain the majority of users will want.


MSDN Forum post by MikeGBUK

BizTalk Orchestration Profiler 2010

October 29, 2011 1 comment

BizTalk Orchestration Profiler is a really useful tool and one I would recommend to BizTalk developers building orchestration based solutions. It illustrates the degree of shape coverage for a given orchestration. It also facilitates the identification of latency issues and error prone shapes.

The current release of the BizTalk Orchestration Profiler on CodePlex will not work with BizTalk Server 2010 without some minor configuration changes as detailed below.

  1. Update the following settings with your installation path for HTML Help Workshop and BizTalk Server 2010:
    <add key="HelpCompilerLocation"
    value="C:\Program Files (x86)\HTML Help Workshop\hhc.exe" />
    <codeBase version="" 
    href="C:\Program Files (x86)\Microsoft BizTalk Server 2010\
  2. Finally add the following setting before the closing “configuration” tag:
    <startup useLegacyV2RuntimeActivationPolicy="true">
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0"/>