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

Just when you thought automated deployments for BizTalk 2004 were safe, another update
to the “Deploy with NAnt” template comes along… 🙂 

This is a very worthwhile “upgrade” to consider taking advantage of.  One of
the big items is support for “configuration info within SSO”, but a complete list
of features/fixes, etc. is below. 

SSO Integration: If you are currently using the SettingsFileGenerator.xls spreadsheet
(discussed in previous entries) in conjunction with the XmlPreProcess tool
to handle “environment-relative” configuration – that is, to handle variations between
your dev/QA/production environments – you will be glad to know you can get more leverage
out of that process now…

To review, with this process, you use the names that are defined in the first column
of the SettingsFileGenerator spreadsheet (shown below) as “tokens” within your binding
file, as in: 

<!-- ifdef ${ xml preprocess} -->
<!-- <Address>${FileSendLocation}\%MessageID%.xml</Address> -->
<!-- else -->
<Address>C:\temp\BizTalkSample OutDir\%MessageID%.xml</Address>
<!-- endif -->



At install time, the value for FileSendLocation that is appropriate to the environment
you are deploying to is “plugged in” by XmlPreProcess (but
for developers, the file remains legal XML.)  The spreadsheet might look as follows:

(click)

Now, however, you can also put in name-value pairs (whether they vary
by environment or not) into the spreadsheet that you need access to at run time (i.e.
general configuration information.) 

The name-value pairs will be deployed into a newly created affiliate application within
the SSO, and can be read using the SSOSettingsFileReader class (which serves as a
cache, too – and is provided in the download.)  The static methods on this
class can be used from an orchestration expression shape, or from assemblies that
orchestrations call – as in string test = SSOSettingsFileReader.ReadValue(“BizTalkSample”,”SomeAppConfigItem”); 
(By the way, the “nested names” shown in the spreadsheet above are just
meant to suggest a partitioning mechanism you might want to use, rather than one flat
“namespace” of config data.)

Of course, the deployment scripts handle all the interaction with the SSO database
for deployments/un-deployments.  This whole mechanism (SettingsFileGenerator.xls,
XmlPreProcess, and now SSOSettingsFileImport.exe) is worth using even if you don’t
use the rest of this script infrastructure.  Note that Jon Flanders had a great
article on SSO-based configuration using a strongly-typed approach, where as this
approach is loosely-typed, but leverages a mechanism you might already be using (i.e.
the spreadsheet concept.)  (Note: Jon’s code for creating/deleting affiliate
apps helped me complete the SSOSettingsFileImport.exe utility quickly…) 

Other features/fixes: 

• Support for multiple schema assemblies, including the case where schema assemblies
  reference each other due to schema imports.  (Undeployments occur in reverse
  order of deployments.)
• Support for multiple orchestration assemblies, including the case where orchestration
  assemblies reference each other due to the use of Call/Start Orchestration shapes. 
  (Undeployments occur in reverse order of deployments.) 
• Support for multiple orchestration and port binding files (just list them as comma
  separated values in the orchBindings/portBindings properties.) 
• Fixed bug that occurred when undeploying ISAPI extensions in Windows 2003 / IIS 6. 
• Fixed bug in undeploying pipeline components (thanks to John Adams) 
• Added /NOFORCE flag to IISRESET calls in accordance with http://support.microsoft.com/kb/286196 
• New property “includeInstallUtilForComponents” was added, which can be set to ‘true’
  in your project-specific nant file.  This will cause your component assemblies
  to be called with “installutil.exe” (with the /u flag for undeployment.)  This
  is useful if you have .NET Installer-derived classes that need to get called for creating
  event sources, perf counters, etc.  (Yes, you could certainly argue these should
  be called by the WiX piece of the script infrastructure instead, but this method works
  and is more in keeping with the spirit of the entire process.)  Note there is
  no harm if a given component assembly listed in your components property does not have
  an installer class. 
• Eliminated the need for the includeCustomTarget property, and provided additional
  ways to supply custom functionality.  Project-specific nant file can now supply
  any or all of customDeployTarget, customPostDeployTarget, customUndeployTarget, customPostUndeployTarget
  — and they will be called if they are present. 
• Integrated the deployment of log4net-specific stuff, if the includelog4net property
  is set to true.  See the work on BizTalk/log4net
  integration for more information.  (Log4net sample usage is included in the
  new sample.)   
• Now using NAnt version .85 – so be sure to grab the latest NAnt/NAntContrib since
  the nant scripts are using .85-specific syntax to avoid “deprecated” warnings that
  were occurring otherwise.  Note that even once you have installed NAnt .85, you
  will still be able to deploy BizTalk projects that are using old versions of the deployment
  scripts.  Note also that this is a pretty basic port to .85 – there are no doubt
  more elegant ways of doing lots of things that I haven’t investigated yet, now that
  nant has expression support. 

Other notes 

The scripts like to see BizTalk projects using Debug and Release for target names. 
A long while back I had suggested a file-level search/replace within btproj files
to change these, but two more elegant options are available: 

• In project properties, change the output location for the “Development”
  configurations to “bin\debug” and output location of “Deployment”
  configurations to “bin\release”.
• (Via Puneet Gupta): Change the template for BizTalk projects, found in BTSApp.btproj
  file in %BizTalkInstallDir%\Developer Tools\BizTalkWizards\BTSApp\Templates\1033,
  to reflect Debug and Release targets. 

Another note: Lots of folks have noticed that XmlPreProcess can be used for a lot
more than port binding files!  Log4net config files, orchestration binding files,
you name it.  See the full Word documentation in the download for an example
of how to do this within customDeployTarget.

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. Do a deployment on a developer workstation and a server to test things out…

Downloading

• You can always use the right-hand links on this blog.
• Full sample here,
  core scripts here
• GotDotNet workspace here. 
  Because of issues with GotDotNet, I’m only going to be keeping the EXE utility
  source code up to date – not the entire sample & core tree.

 Enjoy – comments always welcome and appreciated.

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

Just when you thought automated deployments for BizTalk 2004 were safe, another update
to the “Deploy with NAnt” template comes along… 🙂 

This is a very worthwhile “upgrade” to consider taking advantage of.  One of
the big items is support for “configuration info within SSO”, but a complete list
of features/fixes, etc. is below. 

SSO Integration: If you are currently using the SettingsFileGenerator.xls spreadsheet
(discussed in previous entries) in conjunction with the XmlPreProcess tool
to handle “environment-relative” configuration – that is, to handle variations between
your dev/QA/production environments – you will be glad to know you can get more leverage
out of that process now…

To review, with this process, you use the names that are defined in the first column
of the SettingsFileGenerator spreadsheet (shown below) as “tokens” within your binding
file, as in: 

<!-- ifdef ${ xml preprocess} -->
<!-- <Address>${FileSendLocation}\%MessageID%.xml</Address> -->
<!-- else -->
<Address>C:\temp\BizTalkSample OutDir\%MessageID%.xml</Address>
<!-- endif -->



At install time, the value for FileSendLocation that is appropriate to the environment
you are deploying to is “plugged in” by XmlPreProcess (but
for developers, the file remains legal XML.)  The spreadsheet might look as follows:

(click)

Now, however, you can also put in name-value pairs (whether they vary
by environment or not) into the spreadsheet that you need access to at run time (i.e.
general configuration information.) 

The name-value pairs will be deployed into a newly created affiliate application within
the SSO, and can be read using the SSOSettingsFileReader class (which serves as a
cache, too – and is provided in the download.)  The static methods on this
class can be used from an orchestration expression shape, or from assemblies that
orchestrations call – as in string test = SSOSettingsFileReader.ReadValue(“BizTalkSample”,”SomeAppConfigItem”); 
(By the way, the “nested names” shown in the spreadsheet above are just
meant to suggest a partitioning mechanism you might want to use, rather than one flat
“namespace” of config data.)

Of course, the deployment scripts handle all the interaction with the SSO database
for deployments/un-deployments.  This whole mechanism (SettingsFileGenerator.xls,
XmlPreProcess, and now SSOSettingsFileImport.exe) is worth using even if you don’t
use the rest of this script infrastructure.  Note that Jon Flanders had a great
article on SSO-based configuration using a strongly-typed approach, where as this
approach is loosely-typed, but leverages a mechanism you might already be using (i.e.
the spreadsheet concept.)  (Note: Jon’s code for creating/deleting affiliate
apps helped me complete the SSOSettingsFileImport.exe utility quickly…) 

Other features/fixes: 

• Support for multiple schema assemblies, including the case where schema assemblies
  reference each other due to schema imports.  (Undeployments occur in reverse
  order of deployments.)
• Support for multiple orchestration assemblies, including the case where orchestration
  assemblies reference each other due to the use of Call/Start Orchestration shapes. 
  (Undeployments occur in reverse order of deployments.) 
• Support for multiple orchestration and port binding files (just list them as comma
  separated values in the orchBindings/portBindings properties.) 
• Fixed bug that occurred when undeploying ISAPI extensions in Windows 2003 / IIS 6. 
• Fixed bug in undeploying pipeline components (thanks to John Adams) 
• Added /NOFORCE flag to IISRESET calls in accordance with http://support.microsoft.com/kb/286196 
• New property “includeInstallUtilForComponents” was added, which can be set to ‘true’
  in your project-specific nant file.  This will cause your component assemblies
  to be called with “installutil.exe” (with the /u flag for undeployment.)  This
  is useful if you have .NET Installer-derived classes that need to get called for creating
  event sources, perf counters, etc.  (Yes, you could certainly argue these should
  be called by the WiX piece of the script infrastructure instead, but this method works
  and is more in keeping with the spirit of the entire process.)  Note there is
  no harm if a given component assembly listed in your components property does not have
  an installer class. 
• Eliminated the need for the includeCustomTarget property, and provided additional
  ways to supply custom functionality.  Project-specific nant file can now supply
  any or all of customDeployTarget, customPostDeployTarget, customUndeployTarget, customPostUndeployTarget
  — and they will be called if they are present. 
• Integrated the deployment of log4net-specific stuff, if the includelog4net property
  is set to true.  See the work on BizTalk/log4net
  integration for more information.  (Log4net sample usage is included in the
  new sample.)   
• Now using NAnt version .85 – so be sure to grab the latest NAnt/NAntContrib since
  the nant scripts are using .85-specific syntax to avoid “deprecated” warnings that
  were occurring otherwise.  Note that even once you have installed NAnt .85, you
  will still be able to deploy BizTalk projects that are using old versions of the deployment
  scripts.  Note also that this is a pretty basic port to .85 – there are no doubt
  more elegant ways of doing lots of things that I haven’t investigated yet, now that
  nant has expression support. 

Other notes 

The scripts like to see BizTalk projects using Debug and Release for target names. 
A long while back I had suggested a file-level search/replace within btproj files
to change these, but two more elegant options are available: 

• In project properties, change the output location for the “Development”
  configurations to “bin\debug” and output location of “Deployment”
  configurations to “bin\release”.
• (Via Puneet Gupta): Change the template for BizTalk projects, found in BTSApp.btproj
  file in %BizTalkInstallDir%\Developer Tools\BizTalkWizards\BTSApp\Templates\1033,
  to reflect Debug and Release targets. 

Another note: Lots of folks have noticed that XmlPreProcess can be used for a lot
more than port binding files!  Log4net config files, orchestration binding files,
you name it.  See the full Word documentation in the download for an example
of how to do this within customDeployTarget.

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. Do a deployment on a developer workstation and a server to test things out…

Downloading

• You can always use the right-hand links on this blog.
• Full sample here,
  core scripts here
• GotDotNet workspace here. 
  Because of issues with GotDotNet, I’m only going to be keeping the EXE utility
  source code up to date – not the entire sample & core tree.

 Enjoy – comments always welcome and appreciated.