Why does changing the name of your MSI file require a Major Upgrade?

I skipped out on blogging this last Monday night to chill out with Jenny and watch some Firefly.  Last night I spent the whole evening fixing bugs in the WiX toolset like this and this.  So tonight, I thought I’d take a few minutes and answer a question that was asked on the wix-users mailing list this week.

Don Pratt asked:

Not a WiX question so much as a MSI question, but what is the reasoning behind the ‘rule’ that says that if you change the name of the MSI file you have to do a major upgrade?  If I keep the upgrade code the same, why does the MSI file name matter?

I knew that Don was referring to this page from the Windows Installer SDK.  Unfortunately, I didn’t know the answer, but thought it was a great question.  So I asked around the Windows Installer team and found an answer.  The issue comes down to what I consider one of the Windows Installer weaker areas, handling of the source media.

In this case, the reason the name of the MSI file cannot change without changing the ProductCode (the Product/@Id attribute for those of you using the WiX toolset) is due to the fact that the PackageCode (the Package/@Id attribute in the WiX toolset) and the name of the MSI file are used to verify the correct MSI is found on the source media (i.e. the CD or original installation source).  At first glance, this makes some sense.  Whenever the Windows Installer needs to prompt the user for the source media during an install or repair or (heaven forbid) patch or (please, no) uninstall operation, the Windows Installer needs to know the name of the MSI file.  Those of you who have dealt with CD-ROMs know that searching all over a CD for a file is not only slow but can be very error prone (accounting for a user pushing the eject button at any second generally proves to be really annoying).  So, the Windows Installer remembers the name of the MSI file and the PackageCode for that MSI file to avoid searching and to verify the right file is found once the source media is provided and the MSI file located.

With a bit deeper inspection though, the current behavior doesn’t seem necessary.  Since you must change the PackageCode every time you build a new MSI file (at least every time you release one externally) then technically speaking once you apply a Small Update or Minor Upgrade the old media will not be able to satisfy the media request no matter what the MSI file name.  Of course, the Windows Installer would have to allow the Small Update or Minor Upgrade to update the MSI file’s SOURCELIST.  Maybe there are some complications doing that.

In any case, during my inquiry I received an email from a Product Support Engineer who filed a bug against the Windows Installer because of this behavior.  He was quite passionate about the bug and really wanted to see it fixed.  The response to this bug that I saw from the Windows Installer team seemed to indicate that they chose to focus on vastly improving the Patching story for Windows Installer 3.0 instead of incrementally improving the re-cache/reinstall behavior.  Honestly, that seems like the right trade off to me.

So why are Major Upgrades allowed to change the name of the MSI file?  I didn’t actually ask this part of the question, but my educated guess is that the MSI file name can change because each Product (identified by a unique ProductCode) gets its own SOURCELIST.  Based on my understanding from above, the MSI file name is required to be the same across all of the sources in a single SOURCELIST.  Now, how do I know each Product has its own SOURCELIST?  I don’t, but my educated guess is based on the first parameter to the MsiSourceListAddSource() function is szProduct, the ProductCode.

Hopefully, that plus all of the links to the Windows Installer SDK answers the question, "Why does changing the name of your MSI file require a Major Upgrade?"

Comments (5)

  1. Hm..seems fair enough. But I wonder why this bit was never documented. Also <a href="http://support.microsoft.com/?kbid=884016">Windows Installer 3</a> does seem to have new SourceList API to get around the disgusting Source Not Found dialogs.

  2. Vagmi,

    What I’ve found is that typical documentation is focused on the "What" of the technology and not the "Why". If you look at most of my blog entries, I try to get more into the "Why" because I think that information provides much more insight into the design. "Why" doesn’t seem to translate well into reference documentation (like MSDN, where you really just want the "What" for a particular function call). But, I’m not a technical writer, so my observations may not be accurate.

    Finally, the new SourceList API functions do not directly prevent the Source Resolution dialog boxes. The Windows Installer 3.0 is better about avoiding Source Resolution but it is not because of those APIs.

  3. Ian Baird says:

    Hey Rob, I was in Michelle Gawer’s CS153 class at Rolla (which you graded for). How’s life? My email address is ibaird@spotconsult.com.

  4. And thats the precise reason why I dont miss reading your blog. 🙂

  5. Imagine a blog entry where I talk about my first thoughts of CodePlex Beta that went live yesterday.