Getting Started with the ESB Toolkit 2.2 Extensibility Samples in BizTalk Server 2013

By Nick Hauenstein

This post is the nineteenth in a weekly series intended to briefly spotlight those things that you need to know about new features in BizTalk Server 2013.

This week I wanted to highlight something about the integration of the ESB Toolkit 2.2 within the installation media of BizTalk Server 2013, but I didn’t want the post to end there – providing no more value than a quick perusal of the MSDN docs. As a result, while I will rehash some of that content in the first few sections of this post, I also want to dive into something that is of greater direct interest to the community at large – Itinerary Designer extensibility in 2013.

Now that I’ve spilled the beans, yes BizTalk Server ESB Toolkit 2.2 can now be found on the installation media for BizTalk Server 2013. It lives in the ESBT_x64 and ESBT_x86 folders alongside the core BizTalk setup.

Though the what’s new page for BizTalk Server 2013 lists a known issue with the Intinerary Designer vsix file not being at the normal location, the initial installation actually appears to have installed the designer for me – so there were no direct issues there – and it was definitely a welcome change. Though I will admit that I was more than a little bit worried when I spotted the BizTalk Server 2010 logo in the installer:


Basic Configuration

Another change I noticed along the way of installing the ESB Toolkit is some changes to the way the configuration tool works. Though these changes were certainly more welcome. I am currently running BizTalk on a single-server Windows Azure VM for the purposes of writing this specific blog post. I’m really not a big fan of putting a lot of setup work into such a one-off effort. I’ve even gone so far as to have a general purpose setup script that I use to install Visual Studio / Office / and configure BizTalk each week. So I was definitely happy when I saw that something akin to BizTalk Server’s “Basic Configuration” is now available for ESB Toolkit 2.2:


While it’s unlikely that I would do a blanket default settings setup for a production environment, it certainly is helpful at development time at least.

Easier Installation of Microsoft.Practices.ESB Application

Another welcome addition to the configuration tool is the ESB BizTalk Applications page. This page allows you to install the BizTalk applications which provide the core Itinerary On-ramps as well as the JMS/WMQ components. This removes the step of having to dig around for the correct MSI in the installation directory of the Toolkit, and running through the typical import/install dance:


While I was there, I did notice that the Help menu doesn’t actually contain any menu items – something that will likely go unnoticed as so few tend to actually read the manual.

In this version, I would have liked to see integrated publishing of the requisite tModels to UDDI here in order to support the UDDI resolver (without having to result to the UDDI publishing command line tool). I would also liked to have seen more granular editing/interaction directly within the tool for configuration stored in SSO (at the very least to be able to lookup effective configuration).

That being said, the additions that did make it in here are certainly welcome.

Examining the Designer Extensibility Samples

Now that we have the initial configuration out of the way, let’s get to something a little bit more interesting. I have seen some interest on the MSDN forums lately around ESB extensibility, so I wanted to dig in and see how everything fit together in the ESB Toolkit 2.2 + BizTalk Server 2013 world.

As a result I turned to one of my favorite samples that ships with the Toolkit (in the file, found in the installation directory for the Toolkit) —  the Designer Extensibility Samples. This set of samples demonstrates how you can provide access to custom components (e.g., custom Resolvers, custom Orchestration-based Itinerary Services) within the Itinerary designer.

One of the samples contained shows how to create a designer extension that allows the setting of typed properties on an Orchestration-based Itinerary Service. This will allow you to avoid using a Resolver to specify configuration settings (or creating a custom resolver for that purpose). In order to retrieve the settings, the Orchestration-based service can make use of the  PropertyBag property of the IItineraryStep instance related to the step — which allows you to enumerate a set of KeyValuePair<string, string> (this is the mechanism currently used by the Broker Service to store its specialized configuration data (you can see an example of an itinerary including the broker here).

The main magic for this sample is really just the use of the PersistInPropertyBag attribute on a property within a class that derives from ItineraryServiceExtenderBase, and is decorated with the ObjectExtender attribute. But getting it working in 2013 was no small task.

Troubleshooting the Designer Extensibility Samples

It seems as if samples are the last things touched during a major version upgrade, and this was no exception. To get this puppy going, I had to do some work. The first thing I had to do was to install both the (1) Microsoft Visual Studio 2012 Visualization & Modeling SDK (formerly DSL SDK) and (2) Enterprise Library 5.0.

After those pre-requisites were out of the way, I had to (3) add a reference to System.ComponentModel.DataAnnotations (because for whatever reason, Visual Studio outright refused to believe that the StringLengthValidatorAttribute from EntLib was indeed an attribute. I checked the inheritance chain and we had ValueValidatorAtribute : ValidatorAttribute : BaseValidationAttribute : ValidationAttribute : System.Attribute.

While this inheritance chain has a depth worthy of the label Enterprise, it does correctly end in System.Attribute. The kicker here (and thus the reason for adding the reference) is that ValidationAttribute is from the System.ComponentModel.DataAnnotations assembly. Ugh.

The final bit of voodoo that was required was to build and copy the output to the Lib folder for the Itinerary Designer. So where is that path? Well, while it used to live in two different places (one under the current user’s AppData folder), that is all changed around with Visual Studio 2012. Now, you can get away with copying it to the magical path: C:Program Files (x86)Microsoft Visual Studio 11.0Common7IDEExtensionsMicrosoft.Practices.Services.Itinerary.DslPackageLib

Once building both of the samples, and copying them to that Lib folder, you will have the ability to create an Itinerary Service and specify the OrchestrationSample Itinerary Service Extender. This will populate the Properties window with properties that can be persisted to the Property Bag as shown:


Additionally, the Resolver sample extender also functions beautifully1, and gives us some nice properties to work with: image

Final Thoughts

This week, I don’t really have any greatly inspired final thoughts (which is looking like it’s somewhat of a pattern now). I am happy to see ESB Toolkit more directly integrated with the product, and not something tossed completely to the side. I definitely welcome the improvements that are there so far, and welcome any further that will make lives easier – especially with regards to the sample.

It looks like we’re probably going to be spinning up our courseware development efforts around ESB Toolkit 2.2 pretty soon here — so keep watching this space for a class announcement when it becomes available.

NOTE: Next week, I will be at Disneyland on vacation with my family. While I do volunteer evenings and weekends to put these longer posts together for (hopefully) the benefit of the community, I’m not about to do that while on vacation. As a result, there will not be a new post in the series that week. The series will resume the week of October 7th. Until then, take care! 🙂

1 I just want to give a quick shout-out here to Dean Kasa at Vancity who posed the question of if this can work in ESB 2.2 – looks like it can to me, sorry I can’t reproduce the issue you’re seeing)

Leave a Reply

Your email address will not be published. Required fields are marked *