Video Screencast Help
Symantec to Separate Into Two Focused, Industry-Leading Technology Companies. Learn more.

Handling Upgrades and Patches with Wise Package Studio

Created: 28 Mar 2007 • Updated: 11 Jun 2007 | 6 comments
Language Translations
DavidLockwood's picture
+1 1 Vote
Login to vote

Wise Package Studio is a pretty amazing tool when it comes to helping out with upgrades and patches. Packaging guru David Lockwood dives into the deep end of the pool and comes up with excellent information and some tried and trusted best practices.

Types of Windows Installer Upgrade

There are three types of upgrade possible with Windows Installer:

Small update, Minor Upgrade and Major Upgrade.

A Small Update would be used to make very small changes that do not warrant a new version number. Only the package code is changed. In practice, this should not be used because every time a new version of an application is rolled out I want the precise version of this application to be clearly visible. A small update does not clearly represent this version and is not recommended.

A minor upgrade is used to make small changes. For instance, you might upgrade a DLL to a higher version or install a new file. With a minor upgrade the package code changes and the version number, as defined by the ProductVersion property, is modified.

A major upgrade is used to make, wait for it, major changes to an installed MSI. With a major upgrade you could add a new top-level feature and install many files. If you are rolling out a whole new version of an application with lots of extra functionality it would be a major upgrade. With a major upgrade the Product Code and Package Code change and the Product Version is incremented.

In summary, a minor upgrade installs on top of an existing version and makes a few small changes. A major upgrade uninstalls a previous version and replaces it with a new version. There are no limits on the changes which can be made with a Major Upgrade. A Small Update should not be used because it does not modify the visible version of the installed application.

The Three Codes

In order to understand Windows Installer upgrades you need to understand three codes present in every Windows Installer database.

The Upgrade Code

The Upgrade Code is a GUID which identifies a set of related products. If we have different versions of the same product they should share the same Upgrade Code. This allows any later version of a product to find previous versions and to replace them. Never change this code within the same family of products.

The Product Code

The Product Code is a unique GUID identifying the individual product being installed. This code must be unique on the workstation. If you try to install two packages containing the same Product Code you will see the following error:

The Package Code

The Package Code uniquely identifies the Windows Installer database. It should be changed each time the database is modified. No two non-identical Windows Installer packages should share the same package code. The package code is stored in the Summary Information Stream.

How the Codes Change

  Upgrade Code Product Code Package Code Product Version
Minor Upgrade Do not change Do not change Change Increment
Major Upgrade Do not change Change Change Increment

Where to find the Codes

All the codes are Windows Installer properties, found under the Property table, apart from the PackageCode which is found in the Summary Information Stream.

UpgradeCode  -  Property table
ProductCode  -  Property table
ProductVersion  -  Property table
PackageCode  -  Summary Information Stream
Note: The Summary Information Stream can be found by right-clicking an MSI and choosing properties. The package code is found under the Summary tab, you might then have to click advanced. It is referred to as the 'Revision Number'.

Within the Wise for Windows Installer Editor the PackageCode can be found under the Setup Editor > Product tab > Summary. Within Orca the PackageCode can be found under the View menu and the Summary Information option.

When to Choose Minor or Major Upgrade.

The general rule is to create a Minor Upgrade for small changes and anything else would be a major upgrade. To be more precise in the following scenarios a major upgrade would be required and a minor upgrade would not work.

  • A new top-level feature is being added
  • A component code has been modified. A minor upgrade must never change the name of a component’s key file because this would require the component code to change.
  • The name of the MSI file must not be modified. If you did do this you would see strange ‘network errors’ at installation time.
  • A component is removed from an existing feature.

How to Apply a Minor Upgrade

A Minor Upgrade MSI can not be installed by double-clicking the MSI. The only way to install a Minor Upgrade is by specifying the following command line:

Msiexec /i myminorupgrade.msi REINSTALL="ALL" REINSTALLMODE=vomus

REINSTALL is a public property which specifies a list of features to be reinstalled. Setting this to “ALL” means all features will be reinstalled. REINSTALLMODE is a public property which defines which defines which resources will be reinstalled during the upgrade.

The meaning of the REINSTALLMODE switches

v This tells windows installer to run from the original source then re-cache the package. This is very important. If you did not specify the v switch then the package would not run from the MSI you have double-clicked on but rather from the cached copy under the %WinDir%\Installer folder.
o Reinstall files if the file is missing or an older version is present.
m Reinstall the machine part of the registry.
u Reinstall the user part of the registry.
s Reinstall shortcuts.

How to Create Upgrades with Wise

The UpgradeSynch tool is used to correctly synchronise the required codes to create upgrades. You specify the latest version of the package and a previous version, then you select which type of upgrade you want to create. The tool will automatically modify the UpgradeCode, ProductCode, PackageCode and ProductVersion so that the correct Minor or Major Upgrade is created. Note that the UpgradeSynch tool will not create the entry in the Upgrade table, used by Major Upgrades, which is responsible for removing the previous version.

For Major Upgrades, after you have used the UpgradeSynch tool to synchronise codes you must then go to the Upgrades view under the Installation Expert within the Wise for Windows Installer Editor in order to add the correct Upgrade table entry to remove the previous package.

Options in the Upgrade View

The Upgrade view in the Installation Expert provides a means to automatically populate the Upgrade table.

Upgrade Code: The FindRelatedProducts action will search all packages on the target machine in order to find any where the UpgradeCode property matches this value.
Minimum Version: The minimum version to search for. Any packages containing the specified UpgradeCode but with a version lower than this will not be detected.
Major Upgrade: The maximum version to search for. Any packages containing the specified UpgradeCode but with a version higher than this will not be detected.
Language: You can search only for specific language versions. If this is left null all languages will be detected.
Features to remove: You can choose to only remove certain features specified on this field. If this is left blank all feature will be removed.
Action Property: The property which will be created if a package is detected.
Continue installation after a removal failure: Will continue the install if the removal of the base application fails.
Migrate feature states: Feature states, such as advertised, will be migrated to the upgraded version.
Do not uninstall previous version: The previous version will not be installed.

Location of the RemoveExistingProducts Action

During a Major Upgrade two actions, which can be seen in the InstallExecuteSequence table, are important – FindRelatedProducts and RemoveExistingProducts.

The FindRelatedProducts action is responsible for finding any currently installed MSI packages which have the UpgradeCode defined in the UpgradeCode column of the Upgrade table. This be limited further by only looking for a specific version. The version information is found in the VersionMin and VersionMax columns of the Upgrade table.

When the FindRelatedProducts action finds a version installed corresponding to the specified UpgradeCode it creates the property specified in ActionProperty column of the Upgrade table. This has a default value of ‘Upgrade_1’. This means you could use this functionality to search for an installed package and then make use of the specified property in a condition on another action or component.

For instance, perhaps you to search for an installation of Adobe Acrobat and if you find it install a DLL file. If you do not find it you do not wish to install the file. You could create an Upgrade table entry with the UpgradeCode for Adobe Acrobat, {A6EADE66-0000-0000-484E-7E8A45000000}. If you did not want to automatically remove Acrobat then you could add the flag for this (msidbUpgradeAttributesOnlyDetect) to the Attributes column of the Upgrade table. Then you could take the property defined in the ActionProperty column and use this as a condition on the component containing the file you wish to install.

The RemoveExistingProducts action is responsible for removing any previous version which has been found. By default this action is scheduled at the very end of the install after the InstallFinalize action. This means that the new version will be installed on top of the original base version and then the original base version will be removed. This method relies entirely on a component codes being synchronised between both versions which will generate a correct reference count.

If the base version installs X.DLL in a component with the component code {789E883C-76E7-47B4-974E-D9A8B577098C} then if the upgraded version installs the same file it must be in a component with an identical component code. This will create a correct reference count and will prevent the file being uninstalled when the RemoveExistingProducts action removes the base version and the latest version has been installed on top. Fortunately the UpgradeSynch tool checks that all component codes between base and upgrade versions are correctly synchronised and will automatically modify them if they are not.

It is also possible to move the RemoveExistingProducts action to earlier in the sequence so that the base application is first removed, leaving a clean machine, and then the upgraded version is installed. This takes away any requirement for synchronising component codes as far as the upgrade is concerned. The RemoveExistingProducts action should be moved to just after the InstallValidate action in the InstallExecuteSequence.

Real world example:

A customer contacted me to explain that his upgrades were not working. When he installed the upgrade it did not remove the previous version. Both versions were visible in Add/Remove programs.

After a quick look at the MSI the issue was clear. The VersionMin and VersionMax columns of the Upgrade table contained entries which did not include the version to be removed.

If your upgrade does not work as expected you should check that everything makes sense in the Upgrade table.

Comments 6 CommentsJump to latest comment

rpfenninger's picture

Hi David

Thank you for posting this interesting and informative article here.
It helps me preparing for my WPS 7 exam as there are always one or two questions regarding Upgrades ;-)

Cheers

0
Login to vote
erikw's picture

This is a good addition working with Wise packaging studio.

Thnxssss

Regards Erik www.DinamiQs.com Dinamiqs is the home of VirtualStorm (www.virtualstorm.org)

*************************************************************
If your issue has been solved, Please mark it as solved
***********

0
Login to vote
ianatkin's picture

Hi David,

I just found this article after googling a problem I had with one of my package upgrades. Needless to say your article is fab and my problem now resolved. Good work!

Kind Regards,
Ian./

Ian Atkin, IT Services, Oxford University, UK

Connect Etiquette: "Mark as Solution" those posts which assist you most in resolving your problem, and give a thumbs up to useful articles and downloads

0
Login to vote
ash786's picture

Hi David.

Thanks for your post, very informative.

i am very very new to Wise product and in middle of creating a Mojor MSI but one of the requirement is to upgrade from previous version to latest version. I have followed your instruction but I am getting the following problem, I hope you can guide me?

 

When I execute my major upgrade MSI the older version [4.4.6.0, 4.4.7.0] gets removed from Add/Remove programs and new entry is created [4.5.0.0]. BUT upon installation completion the MSI removes all the installed files, which left INSTALLDIR with no files. I am really confused why this is happening.

If I do normal install (no upgrade) the files get installed and everything works OR if I run repair after install the files get installed.

Note: The different between older version files and current version file is as follow

Old version             Current version

4x0Config.Dll        450Config.dll

 

Rest of the files had major components changed and has newer version.

e.g (In 4.4.6.0 ems96.exe had xyz BUT in ems96.exe new functions had been introduced and the file version changed from 4.4.6.0 to 4.5.0.0)

0
Login to vote
AngelD's picture

To solve this just follow the below section extracted from the article

It is also possible to move the RemoveExistingProducts action to earlier in the sequence so that the base application is first removed, leaving a clean machine, and then the upgraded version is installed. This takes away any requirement for synchronising component codes as far as the upgrade is concerned. The RemoveExistingProducts action should be moved to just after the InstallValidate action in the InstallExecuteSequence.

 

For more information regarding placement check: RemoveExistingProducts action

0
Login to vote
ash786's picture

thanks for your help. don't know how I missed that information.

0
Login to vote