(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 behavior.
• 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 have…)

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 script. 

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