Before You Create Your Upgrade, part 1

Before you begin making upgrades, there are a few things you should understand and a few decisions to make. With this article I intend to cover the essentials that I’ve identified in summary form, with a few hopefully amusing references to our favorite mythical software manufacturer, AcmeSoft (resemblance to any existing companies or products in purely intentional, no doubt).

Part 1: Prerequisite Understanding

Understanding the Four GUID codes

Windows Installer uses alphanumeric codes (called GUIDs, or Globally Unique Identifiers) such as “{7B7996D0-440C-4309-A35C-E5B873A1ED33}” to uniquely identify MSI packages, components and such. These 128-bit numbers are generated randomly by your development machine and, in theory, there’s such a small chance that a number will be repeated that each one is unique-that’s the idea anyway. For the most part when repackaging you don’t much worry about the GUIDs, because the Wise and InstallShield tools do much of the work for you. However, when making upgrades, you need to understand four important GUIDs and when you need to change them.

Product Code
The Product Code should identify the software program and possibly it’s major revisions. AcmeSoft’s TypeWriter and SpreadIt programs would have different Product Codes (or else they couldn’t be installed on the same machine at the same time). In a similar manner, TypeWriter 4.0 and TypeWriter 5.0 could have different Product Codes because of the difference between the versions, as would SpreadIt Homey Edition and SpreadIt Recessional Edition, due to their inherent differences. However, BlamePoint 4.0 and 4.1 would share the same Product Code, because they are just minor updates.
In WPS Windows Installer Editor (WIE) or Wise for Windows Installer (WfWI), you can find the Product Code on what you usually see as the first screen: the “Installation Expert” pane, “Project Definition” box, “Product Details” page; in the middle of the page there’s a box labeled “Product Identification” which has the Product Code and a “Generate” button to create a new one (see picture).
Upgrade Code
Unlike the Product Code, the Upgrade Code sticks with an application for its lifetime. For example, if you ever expect your customers to want to upgrade from BusySlow Charts 2000 to BusySlow Charts 2004, the packages better share the same Upgrade Code, because that’s what Windows Installer uses to see if your upgrade MSI applies to the old version which is (presumably) already installed. Suffice it to say that if you’re creating an upgrade MSI, it should have the same Upgrade Code as the old version(s) it’s meant to update.
In WIE or WfWI, you can find the Upgrade Code on the “Setup Editor” pane, “Product” tab; select the “Properties” item from the list on the left, and double-click the UpgradeCode property (you’ll get a dialog box with another “Generate” button in case you need it, see picture).
Package Code
You should tag each of your MSIs with their own Package Codes, in order to distinguish between them with something other than the date stamp and version number (you did use a good version numbering scheme, right?). Even a minor upgrade-in-place (where you reinstall and re-cache the newer version of the MSI over an already installed one) MSI should have a new Package Code.
To change the Package Code in WIE/WfWI, go to the “Setup Editor” pane and the “Product” tab, select “Summary” on the left and double-click the “Package Code” item on the right, where again you’ll be greeted by a friendly and useful “Generate” button (see picture).
Component ID
Okay, so I lied a bit about there being only four important GUIDs in your package; actually, there’s a separate Component ID for each component in your MSI. And if you’re following Microsoft’s Component Rules, there probably are a lot of components in there. Somewhere in the registry, Windows Installer records the Component ID for each component in each MSI installed on your PC. If two different applications with two different Product Codes share a component in common-for example, a DLL used by all your company’s products and installed in the Common Files directory-then the system doesn’t have to install it twice. In fact, if your MSI tries to install a component with a Component ID that’s already on the system, it won’t even try (unless it’s a versioned file and you’re installing a newer version). Thus, in our hypothetical example world, AcmeSoft’s “Speler” component might have originally been installed with AcmeSoft Prospect, but AcmeSoft FontAge could use it to without having to install it again.
Now maybe you are beginning to understand the importance of unique Component IDs, but there’s one more important point: if you are creating an upgrade package and you want it to upgrade features and components that were installed with the previous version, each upgraded (or unchanged) component in your upgrade package must have the same Component ID that its complement component did in the old version. Otherwise, Windows Installer would try to leave the old component installed and install the new one on top of it, which is going to cause some self-healing nightmares because it’s not supposed to work that way.
The Component IDs can be viewed in WIE or WfWI by going to the “Setup Editor” pane and the “Components” tab; right-click and choose “Details…” on one of the components, and you’ll see the GUID and the “Generate” button in the dialog box (see picture).

Okay, so you may be asking: when do I need to change what GUID again? Well, thankfully, Stefan Krueger created this handy-dandy table at InstallSite.org:

Update Type Package Code Product Version Product Code Upgrade Code
Small Update change don’t change don’t change don’t change
Minor Update change change don’t change don’t change
Major Upgrade change change change don’t change

(Notice that Component IDs are not listed here, because you are not changing them in the upgrade process. Got that?)

For further details and better explanations, check out the article entitled Component, package, product and upgrade codes in Windows Installer at InstallSite.org and Microsoft’s MSI SDK article on Changing the Product Code.

[Continue on to Part 2…]