Using Common SettingsFileGenerator File With BizTalk Deployment Framework

One of the great features of the BizTalk Deployment Framework is the ability to use a SettingsFileGenerator file to set your environment specific settings in an excel file, and use this in your other files, so you can have generic files like portbindings and BRE rules, being updated with the correct settings for the environment we’re working on, like DEV, TEST or PROD. If you are like me, you will probably also have placed a lot of common settings which are used accross all your applications in this file, like SSO user groups, host instance names, common endpoints, webservice users, etc. This means we end up with a lot of duplicate settings accross our environment settings files, which becomes cumbersome to maintain. Fortunatly, there is a way to work around this.

Common SettingsFileGenerator

The BTDF has a nice option which we can use, to have a single SettingsFileGenerator file for all our applications. In this example we have two applications, with a couple of common settings, as well as some application specific settings. The applications were already set up with BTDF, so we already have all necessary placeholders in the PortBindingsMaster file. Lets start by creating a CommonSettingsFileGenerator file which has all these settings in one place. To do this, copy the SettingsFileGenerator from one of my projects to a general Tools directory, rename it, and update it with all the common and application specific settings.

Common SettingsFileGenerator

For easy access to this common file, we can add it to our solution by going to Add -> Existing Item and selecting the file we just created. Also, if you still have the old SettingsFileGenerator file in your solution, make sure to delete it, so we don’t use that by accident when updating our settings at a later time.

Add Common SettingsFileGenerator to solution

Now open your btdfproj file, and in the first PropertyGroup add the next line at the bottom.

<SettingsSpreadsheetPath>EnvironmentSettings\MergedSettingsFileGenerator.xml</SettingsSpreadsheetPath>

Add SettingsSpreadsheetPath

Now when you use BTDF to deploy your solution locally, or you build an MSI for remote deployment, our CommonSettingsFileGenerator will be used for our settings.

Merged SettingsFileGenerator

Now this is really nice, as we only have a single place to maintain our settings, but if you have a lot of applications with a lot of application specific settings, this does make our SettingsFileGenerator quite large. It would be even better if we could have one settings file for our common settings, and another settings file for our application specific settings. Luckily, we also have this option, thanks to Giulio Vian. On my search for an easy way to merge two setting files, I came accross this post about a SettingsMerger project, where Giulio mentions the tool has been merged into Environment Settings Exporter, the tool which the BTDF uses to do all its goodness with the environment settings. At this moment, Giulio’s changes are not part yet of the Environment Settings Exporter which is shipped with BTDF, but we can download and build the code ourselves (or you can download the built exe from here) and use it from a custom target in our btdfproj file. The BTDF comes with a couple of custom targets out of the box, which gives us the ability to run custom commands at certain stages of the deployment or build of the MSI.

For this example we are going to use another application which has already been set up with the BizTalk Deployment Framework, so it already has the PortBindingsMaster file configured, as well as a SettingsFileGenerator with the application’s settings as well as the common settings. Make sure you have the new version of Environment Settings Exporter which we downloaded or built earlier on in your Tools directory. Now copy the application’s SettingsFileGenerator file to our Tools directory as well, and rename it to CommonSettingsFileGeneratorMerge. Now in the application’s SettingsFileGenerator remove all the common settings so this only has the settings intended for that application, and in CommonSettingsFileGeneratorMerge remove all the application specific settings so this now has the common settings which we want to use accross multiple applications.

CommonSettingsFileGeneratorMerge

Application specific SettingsFileGenerator

For easy access to the common file, we can also add it to our solution by going to Add -> Existing Item and selecting the file we just created, placing it alongside SettingsFileGenerator in our solution.

Add both Application specific SettingsFileGenerator's to the solution

Now open your btdfproj file, and in the first PropertyGroup add the next line at the bottom (if you allready added this line in the previous part, just update its value).

<SettingsSpreadsheetPath>EnvironmentSettings\MergedSettingsFileGenerator.xml</SettingsSpreadsheetPath>

Set SettingsSpreadsheetPath

Next place the following code in the btdfproj file after <Import Project="$(DeploymentFrameworkTargetsPath)BizTalkDeploymentFramework.targets" />.

<!-- Merge the settings file in case of local deployment -->
<Target Name="CustomPreExportSettings" Condition="$(Configuration) != 'Server'">
<Exec Command='C:\Projects\Tools\EnvironmentSettingsUtil.exe Merge /input:C:\Projects\Tools\CommonSettingsFileGeneratorMerge.xml /input:.\EnvironmentSettings\SettingsFileGenerator.xml /output:.\EnvironmentSettings\MergedSettingsFileGenerator.xml' />
</Target>
<!-- Merge the settings file in case of building MSI for remote deployment -->
<Target Name="CustomPreRedist">
<Exec Command='C:\Projects\Tools\EnvironmentSettingsUtil.exe Merge /input:C:\Projects\Tools\CommonSettingsFileGeneratorMerge.xml /input:.\EnvironmentSettings\SettingsFileGenerator.xml /output:.\EnvironmentSettings\MergedSettingsFileGenerator.xml' />
</Target>

Add custom targets

This will use the EnvironmentSettingsUtil to merge the common settings and application specific settings into a new file, which we earlier told BTDF to use in our deployments.
Now when you use BTDF to deploy your solution locally, or you build an MSI for remote deployment, you will find that the application will have access to all the common settings, as well as it’s application specific settings.

Merged SettingsFileGenerator

The code for the examples can be downloaded here.

Leave a Reply

Your email address will not be published. Required fields are marked *