Orchestration Designer Views of the BizTalk ESB Toolkit 2.0 Transform and Routing Services

If you’ve worked with the BizTalk ESB Toolkit 2.0, you’ve probably used Orchestration Extenders in your itineraries.  The Toolkit includes two default orchestrations (services) named Microsoft.Practices.ESB.Services.Transform and Microsoft.Practices.ESB.Services.Routing.  These service names correspond to two orchestrations installed in the Microsoft.Practices.ESB BizTalk application, named Microsoft.Practices.ESB.Agents.Transform and Microsoft.Practices.ESB.Agents.Delivery, respectively.

These two orchestrations/services are somewhat mysterious since Microsoft chose not to release the Toolkit source code, and there is no detailed step-by-step documentation that describes what each orchestration does – not even a picture of the orchestration design surfaces.

After running some itineraries through BizTalk that used these two orchestrations, I launched the resulting instances in the Orchestration Debugger.  As you probably know, the Orchestration Debugger shows a close representation of the Visual Studio Orchestration Designer view, albeit without ports and with no ability to drill into Expression shapes, etc.

I screen captured the orchestration views in the debugger and made some annotations to make the Send and Receive shapes more apparent.  Since these will probably be useful to many other BizTalk developers, I’m sharing them below in PDF and PNG formats:


UPDATE (04/27/2010): After my original post, I was able to extract the original ODX XML’s and re-create an ODX file for each orchestration. This will let you open up either orchestration in the Orchestration Designer and view all of the code in Expression shapes, etc. They are posted below.


Using the BizTalk ESB Toolkit 2.0’s ESB Configuration Tool on Windows XP

Have you ever tried to configure the BizTalk ESB Toolkit 2.0 on Windows XP?  If so, you probably didn’t get too far.  According to the system requirements, the ESB Toolkit requires Windows Server 2003 or newer.  However, the original release – ESB Guidance 1.0 – ran just fine on Windows XP.

If you’ve tried to use the ESB Configuration Tool (EsbConfigurationTool.exe) on Windows XP, you probably made it through the first step which creates the Exception Management database.  The next step, Exception Web Services, probably didn’t go so well.  You may have gotten an error like The following exception occurred while retrieving member “Create”: “The system cannot find the path specified.”

The reason for the error is that the tool assumes that you’re using Windows Server 2003 or newer – which implies IIS 6 or newer – all of which have the concept of IIS Application Pools.  Since IIS 5.1 (Windows XP) does not have AppPools, the Configuration Tool’s script blows up.

This is hardly a reason to keep us from using the ESB Toolkit 2.0 on Windows XP!  Who wants to create all of those vdirs and databases by hand?  Not I…  All that was necessary to make the tool work on XP was to slightly modify the built-in PowerShell scripts to avoid referencing IIS AppPools.  I decompiled EsbConfigurationTool.exe, tweaked the scripts, removed the strong name key (since it’s no longer signed by Microsoft) and recompiled the EXE.  Voila!  The tool now works perfectly on Windows XP.

I am attaching the modified version of the tool to this post in the hopes of saving some of you from the same hassle.  Just unzip and overwrite your existing EXE.  Enjoy!

Error Upgrading a Solution to BizTalk 2009: Child element <BIZTALK> of element <VisualStudioProject> is not valid

If you are planning to upgrade a BizTalk solution from 2006 to 2009 RTM, don’t expect that it will be simple. I recently took a good BizTalk 2006 R2 solution and opened it in VS2008 w/ BT2009, got the project upgrade wizard, stepped through it, and at the end of the process all of the BizTalk projects showed as “unloaded.” They all failed conversion with the error Error converting project file. Child element <BIZTALK> of element <VisualStudioProject> is not valid.

<VisualStudioProject><BIZTALK> etc. etc. is the normal, valid structure of an old btproj file!

I did some quick searches and other people had reported this during the beta. Microsoft did not offer any thoughtful, tested solutions to the problem (one solution was to make sure you are opening your actual BT2006 SLN file — duh.) They closed the bug report on Connect as “fixed.”

Some people reported problems with conversion when the project files were bound to source control. I don’t have the solution bound to source control and it still failed. I created a brand new SLN file in VS 2008 and added the projects to it, to no avail. Not wanting to waste any more time, I created a new SLN and all new project files, then copied over the BT2006 artifacts and included them in the new project files. Everything was OK after that, as one would expect.

I created a new issue on Microsoft Connect regarding this issue. If you are encountering it, please vote on it.

There’s no better way to put a sour taste in a customer’s mouth than to run into a barrier like this right out of the box.  Microsoft should not have shrugged this off so quickly when it was reporting during the beta period.

UPDATE: The most common reason for this problem is renaming the default project configurations Development and Deployment — a perfectly normal activity that can be done through Visual Studio. According to Microsoft, changing the names is unsupported for BizTalk projects before 2009. See related posts here.

Creating Services with Contract-First Design Using BizTalk Server 2006 R2 and WCF

.NET Developers Journal Logo

I neglected to post about this at the time, but back in June 2008 I had an article published in .NET Developer’s Journal titled “A Walk Through the Process: Creating Services with Contract-First Design Using BizTalk Server 2006 R2 and Windows Communication Foundation.”  The article is available on the .NET Developer’s Journal website and the sample code is attached to this post.

BizTalk makes a great platform for true contract-first service development because it is designed around messaging.  One of the first things one usually does on a BizTalk project is to load or create XML schemas.  With BizTalk Server 2006 R2’s support for Windows Communication Foundation, it’s a natural platform upon which to build services using contract-first design.

The article assumes that you have worked with BizTalk before, but otherwise it is a step-by-step walkthrough of the process to create schemas, create sample orchestrations to carry out the work behind the service interfaces and to publish the schemas as WCF services.


If Your Visual Studio Solutions Open Slowly, Check WebsiteCache

While tracking down an issue the other day, I stumbled across 25,000+ empty subdirectories inside a single folder: Documents and Settings\<username>\Local Settings\Application Data\Microsoft\WebsiteCache (or on Vista, Users\<username>\AppData\Local\Microsoft\WebsiteCache).  NTFS can technically handle this, but file system performance can slow down for a directory containing such a large number of subdirectories.

How did this happen?  I’ve been using the same XP workstation for BizTalk and some .NET development for one year, using Visual Studio 2005 SP1, BizTalk Server 2006 R2 and the Visual SourceSafe 2005 provider.  My BizTalk solutions include a C# web application project alongside numerous BizTalk projects.  After deleting everything in the WebsiteCache folder, I discovered that my BizTalk solutions opened noticeably faster.  Upon opening and closing the solution a few times, it turns out that Visual Studio was creating one empty subdirectory in WebsiteCache for most or all of my project files and items in Solution Items.  Each time I opened a solution around 15 new subdirectories were created, but never deleted.  Over the course of a year, I accumulated 25,000+.  Another developer found 33,000+ subdirectories in his WebsiteCache folder!

Opening the solutions was taking longer and longer as time went on.  By clearing out the WebsiteCache folder, the solutions (with VSS integration, and which contain around 12-15 projects) now open 10-15 seconds faster.

Other people have reported this issue to Microsoft Connect, but the issue was closed as “not reproducible.”

My Contributions to Popular BizTalk Server Tools

One of the things I’ve been doing over the last six months is enhancing two well-known BizTalk Server tools: the Deployment Framework for BizTalk and the GenerateTypedBAMAPI tool.  I also created a CodePlex project of my own, Environment Settings Manager, which was incorporated into the Deployment Framework and is very useful in its own right.

I never took the time to stop and mention all of the changes and new features, so here’s a summary:

Deployment Framework for BizTalk:

  • Contributed the Environment Settings Manager project, which includes an environment settings spreadsheet that looks like the original one from Loren Halvorson, but does not use any macros and supports saving as either binary XLS or XML (SpreadsheetML).  The companion command-line utility can take in either type of file and export the environment-specific XML settings files that the Deployment Framework uses to create environment-specific configuration files on the fly.
  • Added initial support for side-by-side deployment (multiple BizTalk app versions installed at once): added a “project” version property, added the version to the installer title and default install folder path, added version number to the BizTalk application name and SSO affiliate app name
  • Added initial support for deployment of BAM activity definitions
  • Updated WiX (for MSI generation) to 3.0.x, in the process drastically simplifying GenericBizTalkMSI.wxs and improving the MSI user interface
  • Modified the installer to completely clean up on uninstall, removing all dynamically generated files
  • Modified SetEnvUI.exe (the wizard) to open the file browse dialog in the current directory vs. C: and replaced a P/Invoke call with a Framework call
  • Modified the installer to install “for all users” vs. only for the current user
  • Simplified and improved the clarity of the checkbox captions in the server deploy/undeploy wizard
  • Added an attribute to the UpdateSSOConfigItem Nant task for the BizTalk Application name
  • Made minor documentation updates and replaced the HTML version of the help with a PDF version
  • Updated to NAnt 0.85 release from RC1
  • Included the Visual Studio Tools menu install scripts in the Sample ZIP file
  • Cleaned up the project a bit, removing unused files, etc.


  • Checked in the source code for the first time
  • Added support for a relative path to the Excel workbook vs. explicit path only
  • Added the partial keyword to the generated API class
  • Added a method to the activity classes to enable continuation and return a continuation ID
  • Added a command-line parameter to specify the .NET namespace of the generated code
  • Changed “ESApi” to EsApi to conform to .NET capitalization conventions
  • Added “Activity” to the end of the activity class names
  • Explicitly passed “en-us” culture info to the Excel methods to avoid a globalization bug reported by users
  • Made other minor code improvements, removed XSLT resource class in favor of Visual Studio’s built-in resource support

While I was at it, I added to the GenerateTypedBamApi project a completely new command-line utility program called ExportBamDefinitionXml that can extract the BAM definition XML from an XLS file and write it out to a file.  This utility can be used to automatically keep a BAM XML in sync with a BAM XLS file during local or automated builds.  The code reuses some of Darren’s code that was already present in GenerateTypedBamApi.

The majority of the changes listed above are not yet built into official “releases” on CodePlex, but hopefully that will happen soon — I just need to coordinate with the project owners.  In the meantime, hop over to the Source Code tabs and grab the latest from there.  Please feel free to enter new Issues and Discussions topics in the projects with your ideas and bug reports.


MCPD: Enterprise Application Developer and MCT: Enterprise Application Development

I finally had (made!) time to wrap up two certifications that I have wanted to complete for a long time.  One is the MCPD: Enterprise Application Developer, and I am also a Microsoft Certified Trainer (MCT) for Enterprise Application Development, which allows me to teach all Official Microsoft .NET Development and BizTalk Server courses.

I recently stumbled across an interesting Microsoft certifications page that includes the number of people worldwide who have each of the various certifications.  It’s pretty interesting.  At last update, there are just over 13,000 MCT’s worldwide, and only about 4,000 MCPD: Enterprise Application Developers worldwide!  I was really surprised at how low the numbers are for the three flavors of MCPD after two years of availability.

This gives me a great opportunity to put some graphics on this blog for a change!  🙂





AppDomainUnloadException from NUnit

In my current project I’m using Enterprise Library 3.1’s Caching block to cache data retrieved from web services.  The caching code is implemented in a regular C# class library, and I have NUnit 2.4 tests to test it.  In order to configure Enterprise Library at runtime I’m using Enterprise Library’s FileConfigurationSource to point to a separate configuration file.  Works great.

However, I discovered while running my unit tests that when I ran a test and then tried to close NUnit GUI or re-run a test, there was a 5-10 second delay before the IDE closed.  An AppDomainUnloadException was being thrown at the end of the delay.  When I commented out the code that created the Enterprise Library CacheManager object the delay disappeared, so clearly Enterprise Library was doing something to block the AppDomain from unloading.

After some digging I found the issue.  FileConfigurationSource creates a worker thread that monitors the associated configuration file for changes.  The factory objects, in this case CacheManagerFactory, hold a reference to the FileConfigurationSource object.  There is no way to explicitly dispose or clean up the FileConfigurationSource object itself.  NUnit loads the assembly to be tested into a new AppDomain, and when it shuts down or runs another test, it tries to unload the test AppDomain.  What ends up happening is that NUnit asks the AppDomain to unload, but the FileConfigurationSource’s file monitoring thread does not shut down.  As a result, the AppDomain cannot be unloaded and we see the delay and the AppDomainUnloadException.  Needless to say, this is REALLY annoying.

One partial solution that I found is the Enterprise Library 3.0+ method FileConfigurationSource.ResetImplementation().  If you create a FileConfigurationSource object and then immediately call the static FileConfigurationSource.ResetImplementation() method with the same file path, but pass false to the ‘refreshing’ parameter, the configuration file will not be monitored for changes.  This will have the effect of shutting down the monitoring thread and allowing the AppDomain to unload… but you lose auto-refresh of configuration.

I still haven’t found a real solution to this.  The ‘patterns & practices’ guys need to make FileConfigurationSource implement IDisposable or something.  In the meantime, I’m forcefully killing NUnit all the time or waiting out the delay, both of which are really a pain.

URL Case-Sensitivity on WCF Web Services Published from BizTalk 2006 R2 to IIS

BizTalk Server 2006 R2 makes it easy to expose WCF services from BizTalk’s messaging or orchestration engines via MSMQ, TCP or HTTP (or custom WCF bindings).  For SOAP web services, similar to the old Web Services Publishing Wizard, the WCF Service Publishing Wizard can be used to expose a schema or orchestration as a WCF Web service hosted in IIS.  The WCF service’s .svc file, written by the wizard and used by the WCF hosting support in IIS, always points to a common BizTalk WCF assembly (depending on choice of basic or WS-* binding) versus one specific to your BizTalk application.

Since the .svc file for the BizTalk WCF web service is “generic,” BizTalk needs a way to link the WCF Web service, hosted in IIS, to a port and receive location in the BizTalk messaging engine (in a different process).  This mapping is based on the service’s relative URL, the part after the domain name (like ‘/MyBTSWCFWebService/MyBTSWCFWebService.svc’).  If there is a mismatch in the virtual directory name or SVC file name in IIS vs. the relative URL string entered in the receive location in BizTalk, the two will not make the connection, and you will receive an error when you attempt to connect to the web service.  If you try to bring up the service in Internet Explorer, you’ll see an ASP.NET error similar to “Receive location for address “/MyBTSWCFWebService/MyBTSWCFWebService.svc” not found. (The BizTalk receive location may be disabled.)”.

The very important thing to note is that the URL matching is case-sensitive!

Not knowing this may lead to a scenario that can consume most of a day in frustration (trust me on this one).  Being unaware that the virtual directory and SVC filename are case-sensitive in BizTalk, let’s say that you create the virtual directory on a new BizTalk workstation with a different case than what is configured in your common port bindings XML file (assuming that you maintain one).  After deploying the BizTalk application and attempting to view the service description through Internet Explorer, you find that you receive an error stating that the receive location does not exist or is disabled.

Now, if you somehow realize that you need to correct the case, you go back and delete the virtual directory, recreate it with the correct case, and try to view the service again.  Unfortunately, you see the same error again!  Careful inspection will reveal that throughout the error page text, some occurrences of the virtual directory name are in the correct case, and others show up in the incorrect case of your original virtual directory name.

I can tell you that no amount of restarting IIS, redeploying the BizTalk application, re-creating the virtual directory, rebooting, or even un-configuring and re-configuring BizTalk will get you past this error!  It is really nasty.

As a last hope, we started a mass search of the registry and a complete text search of the entire hard disk — and that finally resulted in the answer: the ASP.NET Temporary Files cache (<windir>Microsoft.NETFrameworkv2.0.50727Temporary ASP.NET Files).  Through all of the re-creating, restarting and reinstalling, the same cached files were still being used every time!  Blowing away everything in the ASP.NET cache folder solved the problem.  My co-worker James ran the hard disk text search and discovered this when he came back the next morning and checked out the search results.

[In case you’re curious, the specific location of the bad vdir name in the cache is Temporary ASP.NET Files<vdirname><random alphanum><random alphanum><svcfilename>.svc.<random alphanum>.compiled.]

Hopefully this will save some of you many, many hours of frustration!

Moving to .NET 3.0/3.5 – What to re-write and what to leave alone?

Reader Ravindranath posed several questions today in a comment, and I think that they deserve a post of their own.  Here they are again:

  1. As a part of migrating from .Net 1.x to .Net 3.x, is it advisable to re-architect for the newer .Net 3.x features (WWF, WCF, WPF, etc)?
  2. When is it a MUST to re-architect and when is it optional?
  3. Are there any approach papers towards this?

There are two primary areas of benefit for those considering an upgrade from .NET 1.0/1.1 on Visual Studio 2002/2003 to .NET 2.0, 3.0 or 3.5: benefits resulting from IDE enhancements, and benefits resulting from .NET Framework enhancements.

First, let’s talk about IDE enhancements.  Today, your IDE of choice should be Visual Studio 2008, whether you are using .NET 2.0, 3.0, 3.5 or are considering an upgrade from .NET 1.0/1.1.  VS2008 is the first Visual Studio IDE for .NET that can target multiple versions of the .NET Framework, so if you are using .NET 2.0 today, you have nothing to lose and everything to gain by moving from VS2005 to VS2008.

Just a few of the benefits of Visual Studio 2008 include:

  • Completely new CSS-oriented ASP.NET designer, shared with Expression Web (formerly FrontPage)
  • Robust IntelliSense for JavaScript
  • Improved code analysis (FxCop) tools
  • Improved performance analysis tools
  • Team Explorer 2008 client for Team Foundation Server 2005/2008, with an improved Source Control Explorer

Since Visual Studio 2008 is still a new release, there are some Visual Studio IDE extensions that haven’t been upgraded yet.  Depending on how important those are to you, it’s possible that you could be forced to wait for updates.  Two notable examples are BizTalk Server 2006 R2, which requires VS2005 and has no announced timetable for a VS2008 update, and Microsoft’s Enterprise Library, which includes a configuration editor plug-in that is not VS2008-ready.  Enterprise Library has an easy workaround since you can either use the standalone editor or hop over to VS2005 for configuration tweaks, but BizTalk’ers are out of luck.

Now to move on to the main focus of Ravindranath’s questions: upgrade benefits resulting from .NET Framework enhancements.

The .NET Frameworks 1.0, 1.1 and 2.0 were completely isolated from each other, but that changed with .NET 3.0 and 3.5.  The .NET 3.0 and 3.5 Frameworks can be thought of as layers on top of each other.  In fact, as I’ve written about previously, .NET Framework 3.5 requires both .NET 2.0 SP1 and .NET 3.0 SP1.  ASP.NET has, in fact, remained at version 2.0.

Projects upgrading from .NET 1.0/1.1 to 2.0/3.0/3.5 will gain their major benefits not from features in 3.0 or 3.5, but from the CLR enhancements introduced back in Framework 2.0.  In most cases you will find immediate performance and memory usage benefits with a straight conversion to 2.0, making no code changes except in the rare cases where you might have used a method or class that had a breaking change in 2.0.

My answer to question #1 is generally No, and my answer to question #2 is that redesign is never required.  Now, of course, I have to qualify that with a couple of caveats, and put some logic behind my answers.

First, it really depends what kind of application is involved and what is important to the business behind it.  My primary example here is Windows Presentation Foundation (WPF).  If your application is a consumer-focused application where graphics and fancy look-and-feel are very important, then yes, it makes sense to take a very hard look at moving to WPF.  You will never reproduce what WPF can do in Windows Forms — although even that requires the caveat that WPF controls can be hosted inside a Windows Forms application!

If you really need the full power of WPF and your app is currently Windows Forms-based, you’re really looking at a rewrite, not an upgrade.  WPF carries with it a significant learning curve, immature tools and third-party libraries and a major time investment.  I do not discourage its use, but you do need to have good reasons and a real need for it, and know what you are getting into.  In another year or two, there will be no reason not to build all smart client apps with WPF, but we’re not there yet.

Second, there is often no good reason to rewrite your ASMX-based Web services with Windows Communication Foundation (WCF).  ASMX is still supported, and it will remain in the Framework into the future.

There are two main reasons to rewrite existing ASMX services with WCF:

  1. You have an explicit need for the WS-* features introduced in WCF and cannot get by with the WS-* subset in the Web Services Enhancements add-ons.
  2. You need the ultimate in performance from your service.

I recommend without qualification that all NEW services (which can be anything from an MSMQ listener to a web service to a self-hosted TCP endpoint) and service clients be written with WCF.  Once again, you will experience a fairly significant learning curve, but WCF is the communication framework of the future, so you’ll have to learn it eventually.  Of the major new subsystems in .NET 3.0/3.5, WCF is the one that most developers will use most often, and it is the first one to learn.

That leaves Windows Workflow Foundation (WF) and CardSpace, and these are the least common.  As with most security-related programming tools, CardSpace will never excite much developer interest.  I think it will remain a niche tool.  On the other hand, WF has a lot of potential, but it also takes the most time for developers and architects alike to fully comprehend how to put it to use.  One sample that is out demonstrates the automation of a Windows Forms form using nothing but the WF rules engine to drive validation and enabling/disabling controls as values and control focus changes.  Normally this would involve dozens of event handlers and many lines of code in even a relatively simple form, but this sample has almost no code behind the form.  That’s a pretty slick example of just the WF rules engine, which doesn’t even address the actual workflow engine.

So, to recap, in most upgrade scenarios from 1.1 to 3.0/3.5, I think you will be best served by a direct upgrade, not a rewrite.  Then evaluate, in order, where you might be able to put to use WCF, WF, WPF and CardSpace, but don’t rush to use any of them just because they’re there!  You will gain huge benefits just from the improvements in the 2.0 CLR and Framework and in the newer Visual Studio IDEs, so enjoy those improvements without too much worry about the 3.0 alphabet soup.  You’ll find a use for them when the time is right.

Finally, I am not aware of any specific papers including guidelines for when to re-design or not in these areas.  Generally, I would look to MSDN and primarily the patterns & practices team for this type of analysis, but I haven’t seen anything yet.  If any readers know of related papers, please feel free to post links in the comments.

%d bloggers like this: