when setup isn't just xcopy

Component Rules 101

I've been debating with myself for the last week wether I really wanted to write this blog entry about the Component Rules. The Windows Installer SDK has some decent documentation about what can go wrong when the rules are broken. But right when I had just about decided to write about something more pleasant, on the walk back from lunch yesterday, Robert suggested that I write this entry anyway to put a more emphasis on this topic that has easily sucked up months of my life. Then today there was yet another email thread at work that demonstrated people still don't understand the Component Rules. So, on the drive home tonight when I heard that C89.5 was going to play the entirety of Basement Jaxx's new album Kish Kash, I decided I would sit down and write the blog entry about the Component Rules. So here we are and here we go.

In a previous blog entry I talked about the basics of Windows Installer Components. If you haven't read that entry you should do so before continuing on here. Done? Great, let's continue.

At the end of that previous blog entry, I hinted at a flaw in the way the Windows Installer reference counted Components and the Resources contained in them. Rather than give the answer right away, I'll start building up an example then walk through the problem step by step and we'll see how quickly you can jump to the conclusion.

Note, I'm going to pretend to use a bit of set notation here but I can't find my discrete mathematics book right now so I apologize now if I butcher the syntax.

First, remember that every Component in the Windows Installer has a Globally Unique Identifier (GUID) that I called the ComponentId. Also remember that the Windows Installer tracks (reference counts) Components only by their ComponentIds. I like examples so let's say we have three Components with their ComponentIds like:

 C1 - ComponentId = "{0F794AC3-F266-4238-BC59-4AD641DD5F8F}"
 C2 - ComponentId = "{5B2390D5-C8D0-43b0-980F-01A872E809C4}"
 C3 - ComponentId = "{0F794AC3-F266-4238-BC59-4AD641DD5F8F}" 

Now to us, it looks like there are three Components listed. However, the Windows Installer would only see two Components because C1 and C3 have the same ComponentId (trust me, I cut'n'pasted them). Okay, so now, let's say I also have three Resources:

 R1 is a Registry Key = "HKLM\Software\Microsoft\Wix\Data=example.wxs"
 R2 is a Registry Key = "HKLM\Software\Microsoft\Wix\Version=2.0.0.0"
 R3 is a File = "[ProgramFilesFolder]\Wix\candle.exe" 

I probably only need two Resources for the example, but electrons are cheap. Anyway, the actual types of Resources listed above don't matter. I just wanted to make the example a little more concrete since I know I don't like it when people start hand waving at abstract concepts.

Now, that we have some Components and Resources, let's run through some simple logical statements. For the rest of this entry, the symbol "==" means "is equivalent to" and the symbol "!=" means "is not equivalent to". Okay? Okay.

 C1 == C1
 C1 != C2
 C1 == C3
 C3 == C1
 R1 == R1
 R1 != R2
 R1 != R3
 C1 != R1 (and some people would argue this is a nonsensical thing to do anyway
 since Resources aren't Components to begin with and discussing their
 equivalency is pointless!) 

All I'm trying to show is that the Components with the same ComponentId are identical and the Resources provided are all unique. Now that we have some building blocks for a setup, let's put them together for our first scenario

 C1 = { R1 }
 C2 = { R2, R3 }
 C3 = { R1 } 

What I've tried to represent in set notation is that Component 1 contains Resource 1, Component 2 contains Resources 2 and 3, and Component 3 contains Resource 1. Nothing magical here. Again, if we do the equivalency tests on the contents Components the following should all still be true:

 C1 == C1
 C1 != C2
 C1 == C3
 C3 == C1 

But enough truth statements, I'm here to talk about installation. So let's pretend that we had the Windows Installer install each of those three Components on a "clean machine" (a machine that has never had these Components installed before). We're talking about reference counts a lot in this blog entry, so let's take a look at the reference counts on the ComponentIds and Resources after the installation is complete:

[ten after midnight and the DJ has started playing Basement Jaxx, sweet...]

 {0F794AC3-F266-4238-BC59-4AD641DD5F8F} - 2 (C1 and C3)
 {5B2390D5-C8D0-43b0-980F-01A872E809C4} - 1 (C2)
 R1 - 2
 R2 - 1
 R3 - 1 

What does this mean? Let me try to represent the lines above in English. "The ComponentId {0F794AC3-F266-4238-BC59-4AD641DD5F8F} has been installed on the machine twice, once by Component 1 and again by Component 3. The Component 2 with its GUID has been installed on the machine once. The Windows Installer only reference counts Components but if we were to apply the reference counts from the Components to their contained Resources we'd notice that Resource 1 has a reference count of two while all the other Resources have a single reference count."

Now let's say we were to uninstall Component 1 and Component 2. The resulting reference counts would look like this:

 {0F794AC3-F266-4238-BC59-4AD641DD5F8F} - 1 (C3)
 R1 - 1 

Notice that Component 2 and its Resources are gone. That's because their reference count reached zero and were thus removed from the machine. Component 1 was emoved so the count on the ComponentId it shared with Component 3 was reduced by one but did not hit zero so the Component is still there. If we remove Component 3 now then all of our Resources would be removed from the machine.

So far so good, so let's move on and introduce a new scenario with just Components 1 and 2 like thus:

 C1 = { R1 }
 C2 = { R1 } 

Now, Resource 1 is installed by two different Components.So if we go back to our clean machine and install each of these Components the resulting reference count on the Components and Resources would look like this:

 {0F794AC3-F266-4238-BC59-4AD641DD5F8F} - 1 (C1)
 {5B2390D5-C8D0-43b0-980F-01A872E809C4} - 1 (C2)
 R1 - 1 

See the problem? No, that's not a typo. Let's try it in English, "The ComponentId {0F794AC3-F266-4238-BC59-4AD641DD5F8F} has been installed once by Component 1 and the ComponentId {5B2390D5-C8D0-43b0-980F-01A872E809C4} has been installed once by Component 2. The Windows Installer only reference counts Components but if we were to apply the reference counts from the Components to their contained Resources we'd notice that Resource 1 gets a count of one from two different Components. Unfortunately, that isn't additive so the Resource 1 ends up with a reference count of one."

So what happens when you uninstall Component 1 (or Component 2, it doesn't matter)? Yep, you guessed it:

 {5B2390D5-C8D0-43b0-980F-01A872E809C4} - 1 (C2) 

Resource 1 has been removed prematurely from the machine. Yes, this is wrong. Yes, this is the way the Windows Installer really works. Yes, there are variations on the scenario that result in Resources being "orphaned" (left behind) after uninstall and Resources not being installed on the machine when a Component tries to install them.

The thing I find interesting is that if you take the first logical statement about the Windows Installer's view of equivalency between Component 1 and Component 2 and compare that to the mathematical equivalency of the sets that represent Component 1 and Component 2 in the last scenario you get this:

 C1 != C2 where "{0F794AC3-F266-4238-BC59-4AD641DD5F8F}" != "{5B2390D5-C8D0-43b0-980F-01A872E809C4}"
 C1 == C2 where { R1 } == { R1 } 

While not quite as profound as Russell's Paradox, if you're using the Windows Installer this design flaw is something you should definitely be aware of when putting Resources in Components. Hopefully, it also demonstrates that you should never put someone else's Resources in one of your Components.

C89.5 has finished playing the new Basement Jaxx CD and I have a flag football game in 8 hours (we have the early game this weekend) so I'm going to wrap this blog entry up here. If people want, I can drill into more detail about the Component Rules in future blog entries. However, I think we have enough information here to understand the problem and provide justification for Merge Modules thus unlocking new branches in my thought tree.

Until next time.