The Windows Home Server v1 extensibility framework missed out an important component; Microsoft implemented no upgrade capability for already-installed Add-Ins.

The “upgrade” process required that the user uninstall the old version of your Add-In, and then install the new version. If your installer wasn’t checking for existing versions of your Add-In users could easily find themselves with multiple instances your Add-In installed, with no way to remove them without manual registry editing.

Windows Home Server 2011 (and the other platforms that support the Windows Server Solutions SDK) now support Add-In upgrades properly. A user can now download a new version of your Add-In, install it from a client machine, and WHS and MSI will handle the upgrade process cleanly. Your users can even upgrade while the Dashboard is running (they’ll need to restart the Dashboard to see changes to any files that were in-use, of course).

As a developer you’ll need to do a bit of work to make this happen, but the result is well worth the effort.

I’m going to assume some prior knowledge here. You should know how to navigate around a WiX file, and the general concepts for packaging WSS Add-Ins. Also, as with any WiX article, do not use the GUIDs in the following code samples; GUIDs must be unique, and if you copy mine they won’t be!

Add-In Deployment Package Setup

The upgrade process works by comparing the version number of your Add-In. Well, it works by comparing a whole bunch of version numbers, in a bunch of different places. WHS 2011 and Microsoft Installer check these version numbers to see if any upgrades need to be performed when your Add-In is (re)installed.

It pays to set these version numbers up correctly when you’re first creating your deployment package so you’re ready to go for upgrades later.

These are the relevant sections of the AddIn.xml, <product>.wxs, and AssemblyInfo.cs files that make up a WSS Add-In package.

AddIn.xml

<?xml version="1.0" encoding="utf-8"?>
<Package 
  xmlns="http://schemas.microsoft.com/WindowsServerSolutions/2010/03/Addins" 
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Id>{6DA3406C-6527-4AA9-BAB3-6E1F508B39FA}</Id>
  <Version>1.0.0.0</Version>
  <Name>WssDeploymentTest</Name>
  <Allow32BitOn64BitClients>false</Allow32BitOn64BitClients>
  <ServerBinary>
    <File>
      <ProductCode>{59BD72A5-5DAB-4E6D-9B0A-980CB2A0D0BA}</ProductCode>
      <Version>1.0</Version>
      <Name>WssDeploymentTest.Deployment.msi</Name>
      <Filter>
        <Language>en-US</Language>
        <IsLanguageFallback>true</IsLanguageFallback>
      </Filter>
    </File>
  </ServerBinary>

The AddIn.xml file is parsed before running any MSI packages. WHS 2011 checks the Package ID, Package Version, and the Version of the ServerBinary File element.

The ProductCode must match the Product ID value defined in your <product>.wxs file; WHS 2011 queries Windows Installer for this value when installing and uninstalling your Add-In.

<product>.wxs

<?xml version='1.0' encoding='Windows-1252'?>
<Wix xmlns='http://schemas.microsoft.com/wix/2006/wi'>
  <Product
    Name='WssDeploymentTest'
    Id='{59BD72A5-5DAB-4E6D-9B0A-980CB2A0D0BA}'
    UpgradeCode='{38736351-4BFC-4B95-9A89-3FED2CBFAB19}'
    Language='1033'
    Codepage='1252'
    Version='1.0.0'
    Manufacturer='Tentacle Software Ltd.'>

Your WXS file is parsed by WiX and built into an MSI package (in this case, WssDeploymentTest.Deployment.msi). Note the “Version” number here. Also, remember that the Product ID value here must match the ProductCode in AddIn.xml.

AssemblyInfo.cs

This file represents the properties for the assembly you’re installing. You can manually edit the file, or use the Project Properties Assembly Information GUI wrapper.

image

If Windows Installer finds that one of the files you’re trying to install already exists, it will compare the version numbers of the two files.

Add-In Upgrade Process

We’ll assume you’ve got v1.0 of your Add-In installed already. You’ve built another version of your Add-In to fix some bugs and add a new feature, but what happens when you run the new deployment package?

WHS 2011 and Windows Installer go through a number of checks and gate the upgrade process depending on the version numbers they find at each step. At a high level, the process looks like this:

  1. WHS 2011 checks the Package ID in AddIn.xml. If we already have that ID installed we then compare the Package Version:
    1. If the version of our new Package is greater than what’s installed, we continue to Step 2.
    2. Or, the install stops with a message informing the user that our current version is newer or the same as the version we’re trying to install.
  2. If our Package Version is newer, WHS 2011 compares the ServerBinary File Version number in AddIn.xml with the currently installed version:
    1. If the version for ServerBinary File in AddIn.xml is greater than what’s installed, we continue to step 3.
    2. Or, no upgrade of the ServerBinary is performed and we skip the MSI entirely.
  3. If our ServerBinary File Version is newer, WHS 2011 executes the MSI package. If Microsoft Installer detects that you’re overwriting an existing file, the file versions are compared:
    1. If the version of our new file is greater than the existing file, we attempt to overwrite the existing file.
    2. Or, no upgrade of the existing file is performed.

“You must restart the server”

If you’re attempting to upgrade a file that’s currently locked, the WHS 2011 Add-In install wizard will prompt the user to restart the server. Most of the time (unless you’re doing something crazy), the files will only be locked by the Dashboard itself, so restarting the Dashboard allows the files to be overwritten successfully.

Because the “must restart” message will persist through subsequent Add-In installs, it’s a good idea to encourage the user to either close the Dashboard before installing a new version of your Add-In or reboot the server as prompted.

Changing your Deployment Package to Support Upgrades

So, what do you need to do in order for your new deployment package to successfully upgrade existing installations of your Add-In? What values must be changed to make sure your new files overwrite old versions?

Here’s the cheat sheet:

  1. Increment the Package Version in AddIn.xml
  2. Increment the ServerBinary File Version in AddIn.xml
  3. Increment the Product Version in <product>.wxs (optional, but recommended for sanity)
  4. Increment the Assembly File Version and Assembly Version in AssemblyInfo.cs

If you’re releasing version 1.1 of your Add-In, you’d want something similar to the following (see the changed “Version” numbers in each sample).

AddIn.xml

Note the changed “Version” elements at lines 6 and 12.

<?xml version="1.0" encoding="utf-8"?>
<Package 
  xmlns="http://schemas.microsoft.com/WindowsServerSolutions/2010/03/Addins" 
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Id>{6DA3406C-6527-4AA9-BAB3-6E1F508B39FA}</Id>
  <Version>1.1.0.0</Version>
  <Name>WssDeploymentTest</Name>
  <Allow32BitOn64BitClients>false</Allow32BitOn64BitClients>
  <ServerBinary>
    <File>
      <ProductCode>{59BD72A5-5DAB-4E6D-9B0A-980CB2A0D0BA}</ProductCode>
      <Version>1.1</Version>
      <Name>WssDeploymentTest.Deployment.msi</Name>
      <Filter>
        <Language>en-US</Language>
        <IsLanguageFallback>true</IsLanguageFallback>
      </Filter>
    </File>
  </ServerBinary>

<product>.wxs

Note the changed “Version” elements at line 9.

<?xml version='1.0' encoding='Windows-1252'?>
<Wix xmlns='http://schemas.microsoft.com/wix/2006/wi'>
  <Product
    Name='WssDeploymentTest'
    Id='{59BD72A5-5DAB-4E6D-9B0A-980CB2A0D0BA}'
    UpgradeCode='{38736351-4BFC-4B95-9A89-3FED2CBFAB19}'
    Language='1033'
    Codepage='1252'
    Version='1.1.0'
    Manufacturer='Tentacle Software Ltd.'>

AssemblyInfo.cs

Note the changed “Version” elements below.

image

Next Steps

This whole process is very manual, especially if you’re releasing a lot of builds, and if you miss one version number your upgrade isn’t going to work.

The solution is, as always, to automate the crap out of things. For File and Assembly Versions, I’m a big fan of the Build Version Increment Add-In for Visual Studio. I’ve also posted previously about automating version numbers in WiX projects.

I’ll write about my solution for changing values in a random XML file post-build (AddIn.xml in this case), and how to tie all the wonderful automation together, in a later post. In the mean time, go test your new upgradable Add-In!

posted on Tuesday, May 31, 2011 7:00 PM | Filed Under [ Windows Home Server Development WSSX ]

Comments

Gravatar
# re: WHS 2011 Add-In Deployment Package Upgrades (Al West @ 6/2/2011 8:42 AM)

Great guide. Many thanks, will be using this on my upcoming Add-in

Post Comment

Title *
Name *
Email
Url
Comment *  
Remember me
Please add 3 and 5 and type the answer here:

Search

Site Sections

Recent Posts

Archives

Post Categories

WHS Add-In Tutorial

WHS Blogs

WHS Development