Alex Shevchuk

Always listen to experts. They’ll tell you what can’t be done, and why. Then do it. - Lazarus Long

From MSI to WiX, Part 8 - Major Upgrade

From MSI to WiX, Part 8 - Major Upgrade

  • Comments 44
  • Likes
  • The main page for the series is here.

 

Introduction

A typical Major Upgrade removes a previous version of an application and installs a new version.  This blog will guide you through the process of creating Major Upgrade.

Source code for RTM version

Let's create a C# solution with two projects in it: library and console application.  Here is the code for the library:

using System;

using System.Collections.Generic;

using System.Text;

 

namespace TestLib

{

    public class TestClass

    {

        private string greeting;

 

        public TestClass()

        {

            greeting = "Hello, World!";

        }

 

        public TestClass(string greeting)

        {

            this.greeting = greeting;

        }

 

        public void WriteLine()

        {

            Console.WriteLine(greeting);

        }

    }

}

Here is the code for the console application:

using System;

using System.Collections.Generic;

using System.Text;

using TestLib;

 

[assembly: AssemblyVersion("1.0.0.0")]

[assembly: AssemblyFileVersion("1.0.0.0")]

 

namespace TestApp

{

    class Program

    {

        static void Main(string[] args)

        {

            TestClass test = new TestClass();

            test.WriteLine();

        }

    }

}

As you can see, console application is using default constructor, so calling WriteLine method of the TestClass class will print out "Hello, World!" message.

Source code for V2 version

For version 2 of our product we will change the console application to use a non-default constructor to pass the greeting string the the TestClass instance:

using System;

using System.Collections.Generic;

using System.Text;

using TestLib;

 

[assembly: AssemblyVersion("1.0.1.0")]

[assembly: AssemblyFileVersion("1.0.1.0")]

 

namespace TestApp

{

    class Program

    {

        static void Main(string[] args)

        {

            TestClass test = new TestClass("QFE version");

            test.WriteLine();

        }

    }

}

Our updated version of application will print out "QFE version" message instead of default "Hello, World!".  Notice also that AssemblyVersion and AssemblyFileversion have changed.

Installation Wix script with no Major Upgrade support

Typical installation script for such program would be something like this:

<?xml version='1.0' encoding='windows-1252'?>

<Wix xmlns='http://schemas.microsoft.com/wix/2003/01/wi'>

 

  <?define SkuName = "TestApp"?>

 

  <?define ProductVersion="1.0.0" ?>

  <?define UpgradeCode="{3485E6A2-A1F3-4329-8BB5-ED8FFCF283D4}"?>

  <?define Manufacturer="Acme Corp."?>

  <?define ProductCode="{5C32A3BD-3BA3-43AF-951F-1077E84B00DC}"?>

  <?define PackageCode="{????????-????-????-????-????????????}"?>

 

  <Product Id='$(var.ProductCode)'

           Name='ProductName'

           Language='1033'

           Version='$(var.ProductVersion)'

           Codepage='1252'

           Manufacturer='$(var.Manufacturer)'

           UpgradeCode='$(var.UpgradeCode)'>

 

    <Package Id='$(var.PackageCode)'

             Description="PackageDescription"

             Comments='Comments'

             Manufacturer='$(var.Manufacturer)'

             InstallerVersion='200'

             Languages='1033'

             SummaryCodepage='1252'

             Compressed='yes'

             AdminImage='no'

             Platforms='Intel'

             ReadOnly='yes'

             ShortNames='no'

             Keywords='Installer,MSI,Database' />

 

    <Media Id="1" Cabinet="$(var.SkuName).cab" EmbedCab="yes" />

 

    <Directory Id='TARGETDIR' Name='SourceDir'>

      <Directory Id='LocalAppDataFolder'>

        <Directory Id='INSTALLDIR' Name='TestApp'>

 

          <Component Id='$(var.SkuName)' Guid='{835A4136-B01E-4F8B-8EA7-5D6F69B07A83}'>

            <File Id='TestAppExe' DiskId='1' KeyPath='yes' Checksum='yes'

                  Vital='yes' Name='TestApp.exe' Assembly='.net'

                  AssemblyManifest='TestAppExe'

                  AssemblyApplication='TestAppExe'

                  Source='TestApp.exe' />

          </Component>

 

          <Component Id='TestLibDll_Component' Guid='{5BC55186-170E-475C-B77A-D80581FC88EC}'>

            <File Id='TestLibDll' Name='TestLib.dll' DiskId='1' KeyPath='yes'

                  Vital='yes' Assembly='.net' AssemblyManifest='TestLibDll'

                  AssemblyApplication='TestLibDll' Source='TestLib.dll' />

          </Component>

 

        </Directory>

      </Directory>

    </Directory>

 

    <Feature Id='Complete' Level='1'>

      <ComponentRef Id='$(var.SkuName)' />

      <ComponentRef Id='TestLibDll_Component' />

    </Feature>

 

  </Product>

</Wix>

Aside from UpgradeCode that script does not have any support for major upgrades.

Preparing an application for future major upgrades

Here is what needs to be done from purely MSI standpoint in order to support major upgrades:

  • Add a record to the Upgrade table to detect if installed on the system application has older version than current installation package.  We need this in case we need to apply conditions for upgrade only.  For example, we may update some configuration file during regular install and skip updating during upgrade thus preserving changes users might add to the configuration file after the original install.  This record should have the following values for columns:
    • UpgradeCode is set to the UpgradeCode property value
    • VersionMin is set to RTM version of the product
    • VersionMax is set to the current product version
    • Language can be set to a product language or empty
    • Attributes is set to msidbUpgradeAttributesVersionMinInclusive
    • Remove is empty
    • ActionProperty is set to the name of the public property which FindRelatedProducts action will set to the product code of already installed related product.  Suggested name for this property is UPGRADEFOUND.
  • Add a record to the Upgrade table to detect if current installation package contains an older version of an application.  We need this to prevent downgrading installed application to older version.  This record should have the following values for columns:
    • UpgradeCode is set to the UpgradeCode property value
    • VersionMin is set to current product version
    • VersionMax is empty
    • Language can be set to a product language or empty
    • Attributes is set to msidbUpgradeAttributesOnlyDetect
    • Remove is empty
    • ActionProperty is set to the name of the public property which FindRelatedProducts action will set to the product code of already installed related product.  Suggested name for this property is NEWPRODUCTFOUND.
  • Custom action Type 19 should be scheduled in both InstallExecuteSequence and InstallUISequence tables.  This action should be conditioned on NEWPRODUCTFOUND property.
  • MigrateFeatureStates action should be scheduled in both InstallExecuteSequence and InstallUISequence tables.  This action sets the feature states on installed application to reflect the feature states of already installed application.
  • RemoveExistingProducts action should be scheduled in InstallExecuteSequence table. This action removes the installed product or only updated files depending on where this action is scheduled in the InstallExecuteSequence table.
  • Both UPGRADEFOUND and NEWPRODUCTFOUND public properties  must be added to the SecureCustomProperties property.
  • Change ProductCode, PackageCode, and ProductVersion properties.
  • Important:  Product language defined in the Language attribute of <Product> element must be one of the languages listed in the Languages attribute of the <Package> element.

Here is how these items translates to Wix:

<Upgrade Id="$(var.UpgradeCode)">

  <UpgradeVersion Minimum="$(var.ProductVersion)"

                  IncludeMinimum="no"

                  OnlyDetect="yes"

                  Language="1033"

                  Property="NEWPRODUCTFOUND" />

  <UpgradeVersion Minimum="$(var.RTMProductVersion)"

                  IncludeMinimum="yes"

                  Maximum="$(var.ProductVersion)"

                  IncludeMaximum="no"

                  Language="1033"

                  Property="UPGRADEFOUND" />

</Upgrade>

Id attribute of the <Upgrade> element is set to a value of UpgradeCode property (UpgradeCode attribute of <Product> element) and will be added to the UpgradeCode column of every record in the Upgrade table.

Every <UpgradeVersion> element adds a new record to the Upgrade table.

Minimum attribute of the <UpgradeVersion> element sets the value of VersionMin column.

Maximum attribute of the <UpgradeVersion> element sets the value of VersionMax column.

Property attribute of the <UpgradeVersion> element sets the value of ActionProperty column.

Here is the relationships between flag bits in Attributes column of the Upgrade table and attributes of the <UpgradeVersion> element:

Flag Attribute Description
msidbUpgradeAttributesMigrateFeatures MigrateFeatures Enables the logic of MigrateFeatureStates action of migrating feature states.
msidbUpgradeAttributesOnlyDetect OnlyDetect Detects products and applications but does not remove.
msidbUpgradeAttributesIgnoreRemoveFailure IgnoreremoveFailure Continues installation upon failure to remove a product or application.
msidbUpgradeAttributesVersionMinInclusive IncludeMinimum Detects the range of versions including the value in VersionMin.
msidbUpgradeAttributesVersionMaxInclusive IncludeMaximum Detects the range of versions including the value in VersionMax.
msidbUpgradeAttributesLanguagesExclusive ExcludeLanguages Detects all languages, excluding the languages listed in the Language column.

<!-- Prevent downgrading -->

<CustomAction Id="PreventDowngrading"

              Error="Newer version already installed." />

<InstallExecuteSequence>

  <Custom Action="PreventDowngrading"

          After="FindRelatedProducts">NEWPRODUCTFOUND</Custom>

  <RemoveExistingProducts After="InstallFinalize" />

</InstallExecuteSequence>

 

<InstallUISequence>

  <Custom Action="PreventDowngrading"

          After="FindRelatedProducts">NEWPRODUCTFOUND</Custom>

</InstallUISequence>

Here is an updated installation script:

<?xml version='1.0' encoding='windows-1252'?>

<Wix xmlns='http://schemas.microsoft.com/wix/2003/01/wi'>

 

  <?define SkuName = "TestApp"?>

  <?define RTMProductVersion="1.0.0" ?>

  <?define ProductVersion="2.0.0" ?>

  <?define UpgradeCode="{3485E6A2-A1F3-4329-8BB5-ED8FFCF283D4}"?>

  <?define Manufacturer="Acme Corp."?>

  <?define PackageCode="{????????-????-????-????-????????????}"?>

 

  <Product Id='{8EEB7D19-F7F4-4218-93B9-BBEAAA4C2E2D}'

           Name='ProductName'

           Language='1033'

           Version='$(var.ProductVersion)'

           Codepage='1252'

           Manufacturer='$(var.Manufacturer)'

           UpgradeCode='$(var.UpgradeCode)'>

 

    <Package Id='$(var.PackageCode)'

             Description="PackageDescription"

             Comments='Comments'

             Manufacturer='$(var.Manufacturer)'

             InstallerVersion='200'

             Languages='1033'

             SummaryCodepage='1252'

             Compressed='yes'

             AdminImage='no'

             Platforms='Intel'

             ReadOnly='yes'

             ShortNames='no'

             Keywords='Installer,MSI,Database' />

 

    <Media Id="1" Cabinet="$(var.SkuName).cab" EmbedCab="yes" />

 

    <Upgrade Id="$(var.UpgradeCode)">

      <UpgradeVersion Minimum="$(var.ProductVersion)"

                      IncludeMinimum="no"

                      OnlyDetect="yes"

                      Language="1033"

                      Property="NEWPRODUCTFOUND" />

      <UpgradeVersion Minimum="$(var.RTMProductVersion)"

                      IncludeMinimum="yes"

                      Maximum="$(var.ProductVersion)"

                      IncludeMaximum="no"

                      Language="1033"

                      Property="UPGRADEFOUND" />

    </Upgrade>

 

    <Directory Id='TARGETDIR' Name='SourceDir'>

      <Directory Id='LocalAppDataFolder'>

        <Directory Id='INSTALLDIR' Name='TestApp'>

 

          <Component Id='$(var.SkuName)' Guid='{835A4136-B01E-4F8B-8EA7-5D6F69B07A83}'>

            <File Id='TestAppExe' DiskId='1' KeyPath='yes' Checksum='yes'

                  Vital='yes' Name='TestApp.exe' Assembly='.net'

                  AssemblyManifest='TestAppExe'

                  AssemblyApplication='TestAppExe'

                  Source='TestApp.exe' />

          </Component>

 

          <Component Id='TestLibDll_Component' Guid='{5BC55186-170E-475C-B77A-D80581FC88EC}'>

            <File Id='TestLibDll' Name='TestLib.dll' DiskId='1' KeyPath='yes'

                  Vital='yes' Assembly='.net' AssemblyManifest='TestLibDll'

                  AssemblyApplication='TestLibDll' Source='TestLib.dll' />

          </Component>

 

        </Directory>

      </Directory>

    </Directory>

 

    <Feature Id='Complete' Level='1'>

      <ComponentRef Id='$(var.SkuName)' />

      <ComponentRef Id='TestLibDll_Component' />

    </Feature>

 

    <!-- Prevent downgrading -->

    <CustomAction Id="PreventDowngrading" Error="Newer version already installed." />

 

    <!-- Sequences -->

    <InstallExecuteSequence>

      <Custom Action="PreventDowngrading" After="FindRelatedProducts">NEWPRODUCTFOUND</Custom>

      <RemoveExistingProducts After="InstallFinalize" />

    </InstallExecuteSequence>

   

    <InstallUISequence>

      <Custom Action="PreventDowngrading" After="FindRelatedProducts">NEWPRODUCTFOUND</Custom>

    </InstallUISequence>

  </Product>

</Wix>

How upgrade works

  • The FindRelatedProducts action runs through each record of the Upgrade table in sequence and compares the upgrade code, product version, and language in each row to products installed on the system. When FindRelatedProducts detects a correspondence between the upgrade information and an installed product, it appends the product code to the property specified in the ActionProperty column of the Upgrade table (Property attribute of the <UpgradeVersion> element).

For FindRelatedProducts to work correctly, the package author must be sure that the ProductLanguage property in the Property table is set to a language that is also listed in the Template Summary Property.

FindRelatedProducts should be authored into the InstallUISequence table and InstallExecuteSequence tables.  The FindRelatedProducts action must come before the MigrateFeatureStates action and the RemoveExistingProducts action.

  • MigrateFeatureStates reads the feature states in the existing application and then sets these feature states in the pending installation. The method is only useful when the new feature tree has not greatly changed from the original.

MigrateFeatureStates action runs through each record of the Upgrade table in sequence and compares the upgrade code, product version, and language in each row to all products installed on the system. If MigrateFeatureStates action detects a correspondence, and if the msidbUpgradeAttributesMigrateFeatures bit flag is set in the Attributes column of the Upgrade table, the installer queries the existing feature states for the product and sets these states for the same features in the new application. The action only migrates the feature states if the Preselected property is not set.

The MigrateFeatureStates action should come immediately after the CostFinalize action. MigrateFeatureStates must be sequenced in both the InstallUISequence table and the InstallExecuteSequence table.

  • The RemoveExistingProducts action goes through the product codes listed in the ActionProperty column of the Upgrade table and removes the products in sequence by invoking concurrent installations. For each concurrent installation the installer sets the ProductCode property to the product code and sets the REMOVE property to the value in the Remove field of the Upgrade table. If the Remove field is blank, its value defaults to ALL and the installer removes the entire product.

The RemoveExistingProducts action must be scheduled in the action sequence in one of the following locations.

    • Between the InstallValidate action and the InstallInitialize action. In this case, the installer removes the old applications entirely before installing the new applications. This is an inefficient placement for the action because all reused files have to be recopied.
    • After the InstallInitialize action and before any actions that generate execution script.
    • Between the InstallExecute action, or the InstallExecuteAgain action, and the InstallFinalize action. Generally the last three actions are scheduled right after one another: InstallExecute, RemoveExistingProducts, and InstallFinalize. In this case the updated files are installed first and then the old files are removed. However, if the removal of the old application fails, then the installer rolls back both the removal of the old application and the install of the new application.
    • After the InstallFinalize action. This is the most efficient placement for the action. In this case, the installer updates files before removing the old applications. Only the files being updated get installed during the installation. If the removal of the old application fails, then the installer only rolls back the uninstallation of the old application.

Windows Installer sets the UPGRADINGPRODUCTCODE Property when it runs this action.

 

Comments
  • Hello, I have a question.

    Suppose that version 1 of your  application (Wix script with no Major Upgrade support) is installed on a system, is it possible to update it with version 2 or a similar implementation without having to manually uninstall first?

    Thanks!

  • That's a really good post Alex. I've used your content to add a major install to my language pack and i'm not sure i could have done it without you page to reference/copy.

    Thanks for the effort.

    Greg.

  • Great post Alex. I successfully used your code for implementing a major upgrade.

    It all worked fine until I had to change my product name.

    Since my product name has changed, it seems that FindRelatedProducts does not find the older version, and after performing the upgrade I find 2 entries in add/remove programs (the old and new name). Do you possibly know how to solve this issue?

  • Thank you so much for this brilliant post, you can't imagine how much time I was losing trying to get an upgrade to work!  

  • Just a note to warn others: if the version number is supplied as four components (x.x.x.x), the fourth component will be IGNORED. Therefore, in order for a version to be considered new by Windows Installer, at least one of the initial three components must change. I burned a whole day on this one. :P

  • @lupetti: Make sure the UpgradeCode is the same for both the old and new version (in the Upgrade table) and (as I just posted), the change in version number is one of the first three components of the version. Also make sure you haven't changed the per-machine/per-user setting as this can throw things off as well.

  • I'm with Ramon - If an UpgradeCode wasn't included in version 1, will an upgrade easily be detected for a version 2 that includes an UpgradeCode? Or is there additional code to write?

    Your site is a fantastic resource btw!

  • I'm also in with Ramon's question. I need always perform an auto uninstall of a previous version whether its major or monor.

    Any suggestions Alex?

  • Regarding Ramon's question on missing UpgradeCode in Version 1.  Unfortunately, I don't think anything can be done to allow automatic major upgrade.

    To enable major upgrade Windows Installer requires UpgradeCode, ProductVersion and ProductLanguage properties identified in the installation package.  That is why the Best Practice with any installation package is to always assign values for these properties.

  • I followed the same steps as indicated above and i have created an updated MSI package to update the program and also the script in the database, but when i install the updated MSI package the SQL statements are not updated in the database

    An ideas?

  • Hi Prabhakaran,

    Without knowing specifics it is hard to say why SQL statements are not updated. It could be an issue with when RemoveExistingProducts is scheduled to run (keypath for component is the same if REP is scheduled too late) or problem could be in the way how you install SQL statements.

    Alex

  • Hi Alex,

    Thanks for the prompt reply. I have fixed the database update issue which i mentioned earlier. Now i have got a new issue i have 2 MSI packages, Error MSI and Fixed MSI. I would upgrade my Setup package using the Fixed MSI but again if i run the Error MSI the Setup package turns back again to the older version.

    Is there anything to stop this or any suggestions?

  • Hi Prabhakaran,

    If I understood you correctly, you are having downgrading issue.  Search for "PreventDowngrading" in the post above.

  • Hi Alex,

    You are right i am having the downgrading issue i am using the same steps as mentioned above but it still downgrades.

    I am using the following line to start the updated MSI package

    msiexec /i Fixed.msi REINSTALL=ALL REINSTALLMODE=vomus

    Am i right or going wrong somewhere i dont know where it is. If needed i can post you both the source files.

  • This command is for minor updates. To apply major upgrade simply install new msi:

    msiexec /i Fixed.msi

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment