Grant Holliday

In my previous post I described how you can use MSI Transform (*.mst) files to separate environment-specific configuration settings from a generic MSI package.

Although this provides a level of flexibility in your configuration, there are two down-sides of Transform files:

1. They’re a binary format
2. You can’t “edit” or “view” a transform file. You have to apply it or re-create it to see what changes it includes.

Fortunately we can use the Microsoft Windows Installer Object Library (c:\windows\system32\msi.dll) to open MSI “databases” and create transform files.

Credits go again to Alex Shevchuk - From MSI to WiX - Part 7 - Customising installation using Transforms for showing us how to achieve this with VbScript. Essentially all I’ve done is taken Alex’s example and using Interop.WindowsInstaller.dll I’ve implemented an MSBuild task.

The <GenerateMsiTransform> MSBuild Task

Download the source code & example transforms.xml here (~7Kb Zipped VS2008 Solution)

The <GenerateMsiTransform> MSBuild task generates MSI Transform (*.mst) files with updated configuration properties for a specified MSI package from an XML configuration file.

This removes the need to manually create transforms using the ‘Orca’ MSI editing tool.

Since the generation of transforms can now be automated, it also means that environment configurations can be stored & versioned under source control.

How it works

Because the WindowsInstaller is an unmanaged COM object and there’s no functionality to “close” a database, the file handle remains open. To work around this we have to create temporary copies of the original MSI file. The workflow goes something like this:

• Read each <transform> element from the ConfigFile
• For each transform:
  • Make the changes to a copy of the original MSI file
  • Copy the MsiFile to a temporary file
  • Update the properties / values with the values from the current <transform> element
  • Save the changes
  • Copy the resultant MSI to a new temporary file
• Diff the changed MSI with the original MSI
  • Open original MSI
  • Open changed MSI
  • Generate a transform file by diff’ing the two

Using the task

Although the task could be used as a stand-alone task invoked by msbuild.exe, the ideal place for it is part of a Team Build script.

By overriding the “AfterCompile” target in TFSBuild.proj, you can create the Transform files just after the installer is built & it will get copied up to the Team Build drop directory.

<UsingTask TaskName=”GenerateMsiTransform” AssemblyFile=”$(MSBuildExtensionsPath)\GenerateMsiTransformTask.dll” />

<Target Name=”AfterCompile”>

  <PropertyGroup>

    <MsiFile>$(Outdir)\Project.Deployment.msi</MsiFile>

    <TransformConfigFile>$(SolutionRoot)\transforms.xml</TransformConfigFile>

  </PropertyGroup>

  <GenerateMsiTransform MsiFile=”$(MsiFile)” ConfigFile=”$(TransformConfigFile)”>

    <Output ItemName=”TransformFiles” TaskParameter=”Transforms” />

    <Output ItemName=”TempFiles” TaskParameter=”TemporaryFiles” />

  </GenerateMsiTransform>

  <Message Text=”Created transform files: @(TransformFiles)” />

  <Message Text=”Created temporary files: @(TempFiles)” />

</Target>

Available Properties

Transform Configuration File (transforms.xml)

The Transform configuration file is designed to be as simple as possible. Each <property /> element specifies a key name & value. Here’s an example:

<?xml version=”1.0″ encoding=”utf-8″?>

<transforms>

  <transform name=”Development”>

    <property name=”CONFIG_CONNSTRING” value=”Data Source=DEVSQLSERVER;Initial Catalog=HelloWorldDevelopment;Integrated Security=True” />

    <property name=”CONFIG_DEBUGENABLED” value=”True” />

  </transform>

  <transform name=”Test”>

    <property name=”CONFIG_CONNSTRING” value=”Data Source=TESTSQLSERVER;Initial Catalog=HelloWorldTest;Integrated Security=True” />

    <property name=”CONFIG_DEBUGENABLED” value=”True” />

  </transform>

</transforms>

I hope this helps somebody out there - please leave a comment if you find it useful or extend it in interesting ways. For more interesting Team Build recipes like this, be sure to have a look at TFSBuild.com

In the different applications development areas that I’ve worked in, the typical process for getting a product installed is something like this:

1. Developers are responsible for building the installation package (a WiX MSI is preferred)
2. Then it’s left up to IT to update the config files
3. And IT deploy the installer to a server or end-users.

Step #2 is where things usually come undone. Some common mistakes I’ve seen people make are:

• There’s no configuration screens in the installer to specify configuration.
• Sometimes the IT guys rip apart the package and re-package it.
• Sometimes the installer doesn’t deal with configuration at all - and the IT guys are left hand-editing XML configuration files on servers.

One of the really nice ways you can avoid these mistakes is to make use of Windows Installer Transform Files for environment-specific configuration settings.

A transform is a collection of changes applied to an installation. By applying a transform to a base installation package, the installer can add or replace data in the installation database.

Credits go to Alex Shevch’s blog post - From MSI to WiX, Part 7 Customising installation using Transforms for describing this technique in detail.

A typical output from the developers now looks like this:

Step 1 - Parameterising your WiX script

Within your WiX script, you can refer to properties by placing square-brackets around them. e.g. [CONFIG_CONNECTIONSTRING]

<util:XmlFile Id=”SetConnString” Action=”setValue” ElementPath=”//appSettings/add[\[]@key=’MyConnectionString’[\]]/@value” Value=”[CONFIG_CONNECTIONSTRING]” File=”[INSTALLDIR]ConsoleApp.exe.config” />

Now that a property is defined in the MSI, we can set it from the command line like so:

msiexec.exe /i MyInstaller.msi CONFIG_CONNECTIONSTRING=”Data Source=(LOCAL);etc…”

By default, Windows Installer doesn’t do any verification of properties. If a property isn’t set, then it will just replace it with nothing when it comes across it. If you want to ensure that all your required properties are set, you can use a launch condition. e.g.

<Condition Message=”CONFIG_CONNECTIONSTRING variable is not set. Try setting the property from the command line or using a transform.”>Installed OR CONFIG_CONNECTIONSTRING</Condition>

Step 2 - Creating a transform file

If you were to create a transform manually, the tool you would use is ORCA. (Not to be confused with “Orcas” - the code name for Visual Studio 2008). Orca is distributed in the (large >1GB) Platform SDK download. Fortunately Aaron Stebner has made just the ORCA installer available through is blog.

Aaron Stebner’s blog - Download Orca install package (direct)

You can quickly access Orca by right-clicking any MSI file and selecting “Edit with Orca” from the context menu:

Once you’ve opened the MSI editing utility, select the “Property” table and have a look at the different properties you can set. If you’ve configured your WiX script correctly, you should be able to see the properties that you made available.

Step 2a - Manually creating a transform

• From the menu, select Transform | New Transform
• Make changes to any properties with your environment-specific configuration
• select Transform | Generate Transform…
• Type the filename of the *.mst file you want to save your differences as
• Repeat the process for each transform/environment that you need to

Now when you run your installation, you specify the transform file as a parameter:

msiexec.exe /i MyInstaller.msi TRANSFORMS=Development.mst

Conclusion

This is an excellent way to reuse a single MSI as you promote it through your dev/test/qa/prod environments, without having to know the values up-front and embed them in the MSI.

In my next post I show you how I’ve extended this technique to automatically generate transform files based on an XML configuration file using the Windows Installer COM Automation object and an MSBuild task.