Creating a Typical Upgrade MSI with the WPS UpgradeSync Tool

This is the most difficult upgrade method, but when it works right it could be the most rewarding. Sadly, if you are not the developer who made both the old/original MSI and the new one, then there’s little chance that all of your components and features line up with the same names, locations and GUIDs.

Then again, the WPS tool UpgradeSync aims to make this possible for you, maybe even if both your old and new packages were created from SetupCaptures. But be warned that as much as this program will automate for you, changing the Component IDs and such, it will also leave a lot of changes for you to do manually, such as adding all the new files, registry entries, etc. to new features and components.

Required Reading

Before you continue reading this tip, take a look at the UpgradeSync tool documentation that comes with Wise Package Studio. This is probably located in your installation under the Wise Share Point\Workbench directory, e.g. “C:\Wise Share Point\Workbench\Tool – UpgradeSync.htm”.

Step-by-Step

  1. Create, edit and test your package for the new version of the program as you normally would (from a SetupCapture, transform, etc.). All your edits from this point on will go in this new package, not in the old one. Oh, and may I suggest making a backup copy of your clean, new MSI before you run UpgradeSync on it? You may find you need to start over at some point…
  2. From the WPS Workbench, run UpgradeSync from the “Tools” tab.
  3. In the first dialog, it will ask you to “Specify the installation file on which you want to run UpgradeSync…” This message is not quite clear, so let me clarify: what they mean is browse to the newer, upgrade MSI, which is what UpgradeSync will edit. (It doesn’t make any sense to change the old one, of course.)
  4. The second dialog asks you for the Previous MSI path. (Thankfully, this one’s a little more clear.) Note that for some silly reason the “Browse…” dialog defaults to looking for .MSI files, but you probably want to use the .WSI file so it doesn’t have to do a time-wasting administrative install.
  5. Next, you have the choice of “Small Update”, “Minor Upgrade”, or “Major Upgrade”; this mainly tells UpgradeSync which GUIDs it should change. (I’m assuming here you’re doing a major upgrade.) Hopefully, if you’ve set your Version fields right in both the old and new packages, they will populate themselves correctly here (if you need to, you do have the opportunity to change the version of your upgrade MSI with the “Current Version” field).
  6. The next dialog is titled “Upgrading/Patching Issues,” and is the meat of the upgrade process. By default, all the things which UpgradeSync can fix for you (such as changing Component IDs, etc.) should be checked, but you might want to hit the “Select All” button just to make sure. Also, before you continue, click the “Save to File…” button and save this listing to a text file, for future reference.
  7. When you click the “Finish” button, it’ll take a minute to save the changes to the upgrade MSI.
  8. Now I’m going to suggest something which sounds kind of odd at first, but it will make sense in a moment: go back and run UpgradeSync again, from steps 1 to 5, just like before. What’s different this time is that the upgrade MSI has already had all the automatic changes, so when you get to the “Issues” page the only issues listed are the ones you have to do by hand. Save this to a text file with a different name: this is the one you will need to work from from this point on.
  9. Print out or open that log file and start reading up on the changes you need to make. Basically, you’ll just follow the directions. In most cases, you’ll need to create new Features and Components to hold the new values-see the other article “Creating a Minor Update MSI Manually” for help with this. Some lines you might see include the following:
    • Registry key ‘RegistryXX’ is a new resource that needs to be added to a new component and assigned to a new subfeature.
    • File ‘YYYY.dll’ is a new resource that needs to be added to a new component and assigned to a new subfeature.
    • Component ‘ZZZZ’ exists in the previous version and the keypath does not exist in the current install. The component’s contents will be deleted during an upgrade. (In this case, you probably don’t have to do anything, unless you need that component to stick around, or UpgradeSync didn’t realize that component has a new name/location in the upgrade MSI.)
  10. After you make your changes, I’d suggest you re-run UpgradeSync in the same manner to see if there are new warnings or tasks. When the issues list is clean, chances are good that your upgrade MSI is ready to go.
  11. Don’t forget: test, test, test. Test it when the old version is not installed; test it when the old version is installed; test is when the old version is partially messed up. Try to pre-guess any “gotchas” that could happen when this upgrade goes live.
  12. When your upgrade MSI does hit prime-time, don’t blame yourself if it’s not perfect, because it’s bound to happen sometimes (especially with the relatively young Windows Installer technology). Learn from your mistakes.