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)

BizTalk Server 2013 New Features Series Index

By Nick Hauenstein

I thought it would be wise to create a post that can serve as a continually updated index of the articles that I have written within the BizTalk Server 2013 New Features Series here on the QuickLearn Team Blog. This post is that listing, and it also includes links to the code developed for each post where applicable.

Without further ado, here’s where we have been so far:

  1. What the BizTalk Server 2013 Mapper Updates Mean for You
    Introducing XslCompiledTransform and returning null values from functoids
  2. Acknowledging a Subtle Change in BizTalk Server 2013
    Examining X12 999 Acknowledgments
  3. Windows Azure Service Bus Queues + BizTalk = Out of Body Experiences
    How to handle messages that are only properties [Code Sample]
  4. SharePoint Integration without Cheating in BizTalk 2013
    Introducing the Client-side Object Model support in the improved SharePoint adapter.
  5. Why Updated Platform Support Matters
    Using PipelineTesting library in concert with the Fakes/Shims support of Visual Studio 2012 [Code Sample]
  6. A Brief Tour of the BizTalk Server 2013 Evaluation Windows Azure Virtual Machine
    How to quickly setup the BizTalk 2013 IaaS offering
  7. Publishing a WCF Service via Service Bus Relay in BizTalk Server 2013 (Part 1)
    Using the installed-by-default AppFabric connect functionality to expose/consume a NetTcp endpoint in IIS via Service Bus Relay — for a client that understands Service Bus Relay
  8. Publishing a WCF Service via Service Bus Relay in BizTalk Server 2013 (Part 2)
    Using the new adapters to expose/consume a BasicHttp endpoint hosted In-Process via Service Bus Relay — so that it is transparent to the client
  9. Automating and Managing BizTalk Server 2013 with PowerShell
    Shows off the soafactory PowerShell Provider for BizTalk while also trying to give PowerShell 101
  10. Exploring the Out-of-the-Box Support for SFTP in BizTalk Server 2013
    Using the SFTP adapter to talk to an Ubuntu Linux box on Azure
  11. Dynamic Send Port Improvements in BizTalk Server 2013
    Shows off the new Send Handler Mapping dialog for Dynamic Send Ports
  12. BizTalk Server 2013 and TFS 2012 – Why Can’t I Lock the Files
    Shows how to configure your TFS workspace to be BizTalk ready
  13. BizTalk Server 2013 Support for RESTful Services (Part 1/5)
    GETing Data + Context Property URL Mapping
  14. BizTalk Server 2013 Support for RESTful Services (Part 2/5)
    Receiving POSTed XML + URL Rewriting [Code Sample]
  15. BizTalk Server 2013 Support for RESTful Services (Part 3/5)
    POSTing UrlEncoded Data to ASP.NET Web API Service [Code Sample]
  16. BizTalk Server 2013 Support for RESTful Services (Part 4/5)
    JSON Decoding + Cross-domain communication with JSONP and CORS [Code Sample]
  17. BizTalk Server 2013 Support for RESTful Services (Part 5/5)
    Using OAuth to authenticate with cloud service providers’ APIs
  18. BizTalk Server 2013: Discovering Dependencies
    Exploring the Dependencies Statistics Panel
  19. Getting Started with the ESB Toolkit 2.2 Extensibility Samples in BizTalk Server 2013
    Examining ESB Install/Configuration Process for Development / Troubleshooting the Designer Extensibility Samples
  20. BizTalk Server 2013 Ordered Delivery Improvements
    Discussing the specific improvements that are seen in how BizTalk Server 2013 handles Ordered Delivery.
  21. BizTalk Server 2013: Eliminating the Dependency on SQL Server 2005 Notification Services
    Configuring BAM Alerts without touching SQL Server 2005 Notification Services.
  22. Building Blocks of Windows Azure BizTalk Services
    Overview of Windows Azure BizTalk Services Features.
  23. Mapping Code Pairs in the WABS Mapper
    Demonstrates attempted approaches for dealing with EDI code pairs using the new WABS mapper.
  24. Top 5 Indicators of the BizTalk Server 2013 Community’s Vitality
    Survey of the BizTalk Server 2013 ecosystem