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

Well, its time for another revision of the BizTalk/NAnt deployment tools… 

For folks recently joining us, these tools allow you to quickly create both developer
workstation deployments (inside Visual Studio) and MSI-based deployments (for servers)
for BizTalk 2004 solutions.  Just about all aspects of BizTalk deployments are
handled, including items such as virtual directories, SOAP proxies, and WinXP/2k/2003

I get quite a few emails from people who are using these tools (which is great!) 
A couple folks have suggested that I start referring to the whole thing as a” p framework?. <

That sounds about right – like all frameworks, there is a core set of functionality
that takes care of quite a bit of work, and a given project can supply what needs
customization or what is missing. 

In this case, the core NAnt scripts, custom NAnt tasks, WiX generation, and other
custom tools form the framework itself – and a given BizTalk project can supply project-specific
details, what needs to be customized, and any missing functionality.   So
I’ll refer to this work as the “Deployment Framework for BizTalk” from now on… 

What has changed in this rev? 

  • When last
    posting on this topic, I should have been even clearer that as of the last release, the
    deployment framework requires NAnt .85.
  • The biggest improvement is the ability to use binding files as they are emitted by
    the BizTalk Deployment Wizard directly.  In the past, the framework had
    insisted that binding files be split between orchestration bindings and messaging
    bindings – this is no longer required.  I had several requests for this fix…Also,
    note that having multiple binding files is supported (like one for each of
    several assemblies.)  Now, if you wish to continue to use the “old style”
    split bindings, define the orchBindings property in your project NAnt file as shown
  • <property name="orchBindings" value="${nant.project.name}.OrchBindings.xml"
    overwrite="false" />

  • You can now set the value of NAnt properties from the SettingsFileGenerator spreadsheet.
     Recall that this spreadsheet is used (in conjunction with XmlPreProcess) to
    manage environment-relative configuration – that is, to manage those values that vary
    depending on whether you are in a development, QA, or production environment.  Until
    now, it has been difficult to use those configuration values within the NAnt deployment
    file!  You typically just used them in your binding files or other application-level
    XML files.  Now, however, you can define a property as shown below to make these
    values available as NAnt properties.  A good example usage is the case where
    you want the actual names of the SSO Application Users group and SSO Administrators
    group to be defined in the SettingsFileGenerator spreadsheet (because the group names
    may vary by environment you deploy to.)  Just define a property in your project
    NAnt file called “propsFromEnvSettings” with a comma-separated list of values you
    want pulled in.  (The sample has been updated to show this, too.)
  • <property name="propsFromEnvSettings" value="ssoAppUserGroup,ssoAppAdminGroup"/>

  • Many people had asked for the DeployResults.txt file (which is created in the DeployResults
    subdirectory during a deployment) to be available in a history log, so that it would
    be easy to walk up to a production server and determine what deploy/undeploy activity
    had taken place (especially useful for diagnosing any failures.)  To that end,
    the deployment framework will preserve past DeployResult.txt files with this convention:
    `DeployResults TRACESATURN_05032005_0922.txt’  Note that the machine name, date,
    and time are preserved – so you can gather these files across all the servers in a
    BizTalk group, if need be.
  • SSOSettingsFileReader class improvements: In the last
    release, I introduced the ability to manage settings within the BizTalk SSO using
    the SettingsFileGenerator spreadsheet that is also used for managing environment-relative
    configuration.  Part of that functionality included a class called SSOSettingsFileReader,
    used to retrieve settings at runtime.  This class now has some strongly typed
    accessors, and no longer sits inside a lengthy namespace, which means that in an orchestration
    expression shape you can simply do:
  • someVar = SSOSettingsFileReader.ReadString("BizTalkSample","SomeAppConfigItem")
    // or ReadInt32

  • Ben Cops had found that on large-scale
    deployments, it was useful to restrict which orchestrations were deployed/started
    to speed the development cycle.  So, he modified the orchestration NAnt task
    accordingly.  To use (if you need to), just set the orchestrationsToIgnore property
    in your project NAnt file with a comma-separated list that reflects what you are currently
    working on.  Make sure to copy BizTalk.NAnt.Tasks.dll to your program files\nant\bin
    directory again!
    (you’ll find it in the DeployTools directory in the download.)
  • A bug was fixed with undeployment for the case where an SSO affiliate app had already
    been deleted…
  • All references in NAnt files to xmlns=”http://nant.sf.net/schemas/nant-0.84.win32.net-1.0.xsd”
    were removed, because they were simply causing heartache (for many reasons.)  Remove
    this namespace in your project NAnt file when upgrading.
  • Rather than trying to keep the source for the C# tools (NAnt tasks, SetEnvUI, DeployBTRules,
    SSOSettingsFileImport\SSOSettingsFileReader, etc.) current within the GotDotNet workspace,
    I’m making them available as a zip. 

Remember, you do not need to piece together the current functionality set from past
blog entries – the complete documentation (in Word form) is in the download and separately here.

Some last thoughts:

  • Some folks have been reluctant to use the deployment framework because of its reliance
    on NAnt, and a worry over using NAnt in a server environment.  One thing to remember
    (that might allay this concern) is that a subset of NAnt is delivered with the generated
    MSI, and NAnt will not require a separate installation procedure by your production
    operations team.  Moreover, NAnt doesn’t create any kind of persistent service
    or footprint on the production machine (i.e. no automatic file associations that would
    cause scripts to run with a double-click or anything like that…)
  • Add a Visual Studio External Tool for the updateOrchestration target if you haven’t
    already!  This can speed your development cycle significantly.  See the tools
    zip for a script that creates all relevant external tools.
  • When using the WiX-based MSI generation, make sure your project NAnt file (for WiX
    generation, like BizTalkSample.WiXSetup.Build) is choosing “debug” or “release” based
    on what you want to put in the MSI.  See comments in that file for more detail,
    and Jon Flanders’ post
    on this topic

How do I upgrade?

  1. With a safe copy of your BizTalk solution, expand the “Core” zip contents right on
    your project directory, such that the core scripts will overwrite what you have now
    (but your project-specific scripts will be preserved.)
  2. Manually copy the WiX-related updates to your *.WiXSetup directory, since they will
    get unzipped to BizTalkSample.WiXSetup
  3. Remove xmlns=”http://nant.sf.net/schemas/nant-0.84.win32.net-1.0.xsd” from your project
    NAnt file
  4. Copy DeplyTools\BizTalk.NAnt.Tasks.dll to your program files\nant\bin directory
  5. Do a deployment on a developer workstation and a server to test things out…


  • You can always use the download links on this blog.
  • Full sample here,
    core scripts here,
    extra tools here. 
  • (But always check the download links to see if there has been an

  • Standalone documentation here (and
    diagram here.)
  • GotDotNet workspace here.