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

It has been several months since I initially posted on
the topic of using NAnt to coordinate the deployment of BizTalk 2004 solutions, with
updates here and here. 
Since that time, I’ve been heads-down in a BizTalk project and have had a chance to
refine the practice quite a bit.

So, I took the opportunity to introduce quite a few improvements into the sample I
had previously released – hopefully turning it into a “template” that can be used
on your projects more easily.  To that end, I’ve created a GotDotNet
workspace where you can download the current version of the build template, and
I invite any feedback/suggestions/participation.

The major changes I’ve introduced can be categorized as follows:

  • Split binding files: On a BizTalk project with multiple developers, I believe it is
    beneficial to split your binding files into content related to orchestrations vs.
    content relating to “everything else” (send ports, receive ports, etc.)  The
    new build template sample does just that.
  • Improved scripts: Many of the WMI-related scripts I relied on in the past were from
    BizTalk SDK samples.  These were modified to get better/different error handling
  • More generic handling of send ports, receive ports, receive locations, etc. in the
    script – though it still requires some maintenance.
  • Better NAnt citizen: I’m still not a NAnt expert by any stretch, but thanks to Duncan
    Millard I realized that I had been remiss in applying quotes to a good deal of
    the text names I was using (i.e. &quot).  In addition, I started using built-in
    NAnt tasks for at least a few items where I had overlapped functionality, though not
    in cases where I needed slightly different behavior.  Finally, the build file
    naming convention proposed by the build template is “BizTalkSample.sln.deploy.build”
    (rather than “BizTalkSample.sln.build”) to avoid conflicting with a NAnt file that
    would actually be used to build the project (e.g. with Cruise Control), as opposed
    to deploying it.
  • Use of “Deploy with NAnt” in an MSI scenario: This is the biggest (and I believe
    most useful) change…Let me explain further.

As you study the build script, you will notice that it now also tackles such tasks
as deploying virtual directories and applying permissions to them, patching binding
files to match “local conditions”, etc. The initial goal here is to ensure
that in a team development scenario, the amount of “out of band” setup
required for any given developer to establish their BizTalk 2004 project environment
is minimal – and that the current topology for the project is communicated
efficiently (i.e. through the build file, as opposed to email or word-of-mouth.)

After a development team has spent weeks or months with this build script, refining
it to represent their exact situation and deployment needs, a question might arise:
Why not take this well-tested script and use it for production (or just non-development-machine)
deployments as well?

To do this, it is helpful to agree that a two-phase deployment of BizTalk-related
projects is both acceptable and useful. The first phase is an MSI-based installation
that simply installs all of the BizTalk-related assets in a specific directory, but
doesn’t deploy them to the BizTalk server. The second phase occurs when the
user goes to the Start-Programs-YourProjectName menu, and chooses “Deploy YourProjectName”.
The user also has the option to un-deploy (leaving the assets still on the file system
until the MSI is uninstalled) or redeploy (to support the case where a single file
is “patched”.)  See a picture of the
Start menu created by the build template’s MSI file.

The reason that two phases are useful is that if the deployment to BizTalk fails,
we would like a complete log of the results (which in this sample occurs in the DeployResults
directory) for analysis/diagnostics, and we would rather not have the MSI simply roll
back. The same holds true of un-deployment.

Dual-purposing the NAnt file you have been maintaining for “real” deployments
can be summarized as follows:

  • Use the build template’s approach (see BizTalkSample.sln.deploy.build in the
    download) for the “server.deploy” and “server.undeploy” targets,
    which make the build file able to work with “co-located” binaries in addition
    to the standard developer tree.
  • Create a Visual Studio Setup project that deploys your BizTalk assemblies according
    to the pattern shown in the BizTalkSample.Setup project. Notice that this setup project
    includes the NAnt build file, the “DeployTools” directory (with our scripts),
    as well as a subset of NAnt in a subdirectory of our installation (so that we don’t
    rely on NAnt being present on the target server.)  It also includes a few convenience
    batch files referenced by our Start menu entries for invoking NAnt with specific targets.

The BizTalkSample.Setup project in the build file can be built, installed, and deployed
to try this out.  (You will want to make sure you haven’t already deployed in
“developer” mode, because the “Deploy BizTalk Deployment Sample” passes a flag to
the NAnt script that will skip the undeploy phase in order to speed up “clean” installations.)  Note
that as your deployment grows more sophisticated – multiple hosts, servers, etc. –
you will find the NAnt script requires additional properties to govern these variations
between server deployments and developer-desktop deployments.

The build template sample also discusses the use of NUnit as a post-deployment verification
process.  See the documentation in
the sample for a full discussion —  basically all we are doing is making sure
our MSI includes a subset of our unit tests, NUnit, and appropriate test files. 
This is then wired up to the “Verify Deployment” Start menu option.  This can
be an extremely effective means of ensuring your operations team has a means of testing
the system interactively (not to replace standard automated heartbeat tests you might

Peter Provost proposed
a great generic approach to building BizTalk NAnt files a couple of weeks ago – and
I shamelessly stole his approach to reverse the “orchestration ordering” property
(very slick!)  If you do not wish to pursue the MSI option just discussed, and
you do not wish to integrate the “out of band” setup actions discussed above (i.e.
virtual directory creation, etc.), you might prefer his approach or you might want
to push the build template sample provided here in that direction (i.e. more property
driven.)  However, I believe tackling the kinds of concerns that we do here will
generally mean that a real-world project will no longer have a generic-looking NAnt

Again, you can download the build template sample here. 
Enjoy, and I hope you find it useful.