NAnt for BizTalk 2004…

(Update: See the latest on the Deployment Framework here.)

One of the more complicated aspects for a developer using BizTalk 2004 is the large
number of steps required during the edit/run/debug cycle.  Since your BizTalk
artifacts can’t be run “in place” (that is, where they were compiled) but must instead
be deployed to a local (or remote) BizTalk server, life can get quite complicated.

If you have done much BizTalk 2004 development, you know the routine quite well at
this point.  If you have orchestrations, schemas, transforms, pipelines, and
(say) C# components all partitioned into separate assemblies – and you have a
number of orchestrations with “Call/Start Orchestration” shape dependencies that introduce
specific start/stop-ordering – you can spend a lot of time doing the whole stop/unenlist/undeploy/redeploy/enlist/start/bounce
BizTalk routine. 

Worse, you might not get it right – which can lead to hours spent debugging problems
(over the course of your project) that don’t really exist.

To alleviate this problem, it can be quite helpful to use a tool like NAnt to
coordinate the “update my BizTalk server” process that must occur after each build. 
(NAnt is a large topic – suffice to say it is an Xml-driven software build system.) 
As long as your NAnt build file (and BizTalk bindings file) are kept up to date, the
whole process can be reduced to:

  1. Comple your solution (which might have multiple orchestrations, schemas, transforms,
    pipelines, and external components in separate assemblies)

  2. Choose “Deploy to BizTalk” from your Tools menu.

  3. Wait 60 seconds or so, enjoying the feeling that you have a consistent & reliable
    deployment mechanism.

In addition, you can of course use NAnt to kick off full unattended builds for nightly
builds or continuous integration systems (like Cruise
).  Since Visual Studio.NET is the only
supported way
to build BizTalk projects – despite that tempting XSharpP.exe file
sitting in your BizTalk installation directory – this part of your NAnt build file
must defer to calling devenv.exe in command-line fashion.  (A short “getting
started” for NAnt & directions for using with a VS external tool can be found here.)

So, how about a sample that shows using NAnt to coordinate a reasonably complex deployment
of inter-related BizTalk projects?  Available for
download is a zip of a BizTalk solution that contains the following projects:

  • BizTalkSample.Components (a C# project, with a class called from orchestration)
  • BizTalkSample.Orchestrations (that contains two orchestrations, one which calls
    the other via a Call Orchestration shape)
  • BizTalkSample.Pipelines (a send and receive pipeline, which are not needed but
    included to illustrate the deployment aspects)
  • BizTalkSample.Schemas (which includes two schemas)
  • BizTalkSample.Transforms (which contains a single transform used by one of the

The item I hope you will find most interesting, however, is a file
called  This is a NAnt build
that has a deployment target which captures the following
dependency tree (only partially blown out here, for brevity – but this no doubt seems
familiar to you if you’ve been using Biztalk 2004 for awhile…)

   Deploy Schemas
      Undeploy Schemas
         Undeploy Orchestrations
            Unenlist Orchestrations
               Stop Orchestration
         Undeploy Transforms
            Undeploy Orchestrations
   Deploy Components
   Deploy Pipelines
      Undeploy Pipelines
         Undeploy Orchestrations
   Deploy Transforms
      Undeploy Transforms
         Undeploy Orchestrations
   Deploy Orchestrations
   Bounce BizTalk

Perhaps more illustrative is the output of the deployment itself – a sample of which
can be seen here.  Note that the NAnt script
relies heavily on the EnlistOrch.vbs and StopOrch.vbs script files that ship as samples
with BizTalk 2004, as well as the BTSDeploy command line utility.

The script included in the download should represent
a BizTalk project organization of sufficient complexity to act as a template for your
own projects.  You will want to maintain the list (and correct ordering!) of
the names of your orchestrations within the build targets for “deploy.orchestrations”
and “unenlist.orchestrations” (this isn’t deriveable automatically…)

Note that the build script relies on a set of naming conventions that will be evident
once you spend some time with it – namely, that directory names correspond to assembly
names.  In addition, the standard “Development” and “Deployment” configurations
in BizTalk projects have been replaced with “Debug” and “Release”, in order to not
create inconsistencies with standard .NET projects (and allow for one “Configuration”
property within the build script.)  This replacement was accomplished with a
file-level search/replace.

There is probably room for more sophistication in this build file.  It takes
a somewhat pessimistic view of what must happen for each edit/run/debug/deploy cycle,
but I’ve found that despite the 60 seconds spent executing the script, your net productivity
gain will be quite high given the time you won’t waste trying to figure out what aspect
of your deployment isn’t correct.  Leave comments with suggestions for improvements,
if you like.

UI Process Block: Let me help you

I’ve noticed a number of referrals from Google from people looking for help with the UI Process block.

Having spent some time with the UI Process Block I’d like to share my experiences, but to do that I would like to know what information people are after. Please leave me a comment below, or contact me directly using the “Contact” link above and I’ll try to come up with some suitable articles.

Finally the obligatory plug: If you are looking for help with UI Process Block implementation, especially on projects that also involve BizTalk, my employer ( specialises in BizTalk and .NET implementations so feel free to make an approach to learn more about us and (I hope) engage us commercially.

IMPORTANT UPDATE: I haven’t worked with the UI Process Block for almost a year, so it’s increasingly hard to devote time to looking into these issues. Please feel free to continue using my comments section to ask questions – but it’s unlikely that I’ll be able to chip in with answers. Don’t forget the Got Dot Net workspace.

IMPORTANT UPDATE #2: I’ve now closed comments on this entry; please direct your questions to the official Got Dot Net workspace.

IMPORTANT UPDATE #3 :): Closing comments meant they weren’t displayed any more; that was unintentional and seems to be a limitation of the .Text blog engine. Comments are open again so that you can see the old content :).