Deciphering the MSI Directory table, part 5 (the dot, colon and pipe)

It is time to pick up the story of the Directory table where we left it. I started this blog entry by going back and re-reading that which I had already written. The first paragraph of part 1 surprised me because it reminded me how long I've been operating under frustration. Then when I re-read part 4, I realized I left things hanging with a promise of good things to come. I can imagine you all are rather frustrated with me. <smile/>

So, let's dig into the DefaultDir column of the Directory table (we'll come back for TARGETDIR/SourceDir another day). In our previous examples, DefaultDir had simple content in it like "One" or "Two" or "ThreeToo". We saw that that content was stuck together to create directories like "SourceDir\One\Two\ThreeTwo\". If this doesn't seem familiar then go back and read part 4. We're going to do something a bit more complicated.

If you remember from part 1, one of the things I found most confusing was the dot, colon, and pipe characters that appeared in the DefaultDir column sometimes. Let's explain those away. First, we need some data. Here is a Directory table modified from our example in part 4.

Directory           Directory_Parent      DefaultDirs
s72 S72 l255
Directory Directory
FirstFolder TARGETDIR One
NoopFolder FirstFolder .
SecondFolder NoopFolder Two:.
ThirdFolder SecondFolder Three|The Three Directory
SecondThirdFolder SecondFolder ThreeToo|ThreeAsWell:32|Three Too

Remember, the first three lines of the IDT file describe the structure and name of the table. And as always we find the TARGETDIR as the root of the Directory structure (note the lack of a Directory_Parent). The "FirstFolder" is a simple Directory row that defines a directory named "One". Finally, at the "NoopFolder" we hit our first interesting character, the dot.

The dot - When the DefaultDir column contains a single dot (aka: period) the row does not define another directory. Essentially, the row is a "no operation" or a "no-op" (thus the name NoopFolder). In our example, this is pretty pointless because it means the NoopFolder is equivalent to the FirstFolder. As we'll see in a second, there are uses for the dot (especially in Merge Modules, which I won't be covering tonight).

Moving on, we can see in the "SecondFolder" uses not only the dot again (I promised we'd see it again soon) but the colon.

The colon - When the DefaultDir column contains a colon (and it can contain only one) the left-side of the colon specifies the target name and the right-side of the colon specifies the source name. Let's break those terms down. The target name is the name of the directory that will get created during installation on user's machine. The source name is the name of the directory on the source media (like CD or network share). For those of you that always cab up your files and/or never create administrative images the source name may seem unnecessary. However, consider the case that you have a setup.exe in the root of your installation that wants to read a file that also gets installed (maybe a splash screen graphic for both your setup and application). With the colon you can put that file in a different directory on the media from the directory the file gets installed to normally. With our example data above, the SecondFolder says the "Two" directory will exist in the "One" directory when installed but on the CD (or network share) there is no "Two" directory and all files will be found in the "One" directory. Is this useful? Definitely... sometimes. <smile/>

We hit our third special character by looking at the "ThirdFolder" row, the pipe (aka: vertical bar).

The pipe - When the DefaultDir column contains a pipe (and it can contain only one per side of the colon) the left-side of the pipe defines the short name and the right-side of the pipe defines the long name. After working with paths in the Windows Installer for a while, you'll quickly realize that the Windows Installer requires short names (aka: DOS names or 8.3 names) for all files and directories. This is annoying but fact. You'll notice in all of my examples (until now) that I was very careful to make sure the directory names never had more than 8 characters (and no spaces): One, Two, Three, ThreeTwo. When I wanted to define a directory with more than 8.3 characters or spaces I had to create a short name then a pipe and then use my long name.

Note: I highly recommend that you do not use the same pattern the file system uses to create short names (the LONGNA~1, syntax). There are cases that can occur where your made-up name will collide with a created short name. I've had more than three people tell me stories about how customers were reporting very bizarre install issues that turned out to be short name collisions. And, yes, I know that several major packaging vendors will create short names like "PROGRA~1" but it is still not a good idea (the WiX toolset actually warns about names like that).

Finally, the "SecondThirdFolder" row shows how you can put it all together. Hopefully, by now you can decipher the DefaultDir column of the Directory table yourself. Just in case there are still questions, I'll provide the target layout short, target layout long, the source layout short and the source layout long for our example data at the top.

Target layout (short)
FirstFolder = TARGETDIR\One\
NoopFolder = TARGETDIR\One\
SecondFolder = TARGETDIR\One\Two\
ThirdFolder = TARGETDIR\One\Two\Three\
SecondThirdFolder = TARGETDIR\One\Two\ThreeToo\
Target layout (long)
FirstFolder = TARGETDIR\One\
NoopFolder = TARGETDIR\One\
SecondFolder = TARGETDIR\One\Two\
ThirdFolder = TARGETDIR\One\Two\The Three Directory\
SecondThirdFolder = TARGETDIR\One\Two\ThreeAsWell\
Source layout (short)
FirstFolder = SourceDir\One\
NoopFolder = SourceDir\One\
SecondFolder = SourceDir\One\
ThirdFolder = SourceDir\One\Three\
SecondThirdFolder = SourceDir\One\32\
Source layout (long)
FirstFolder = SourceDir\One\
NoopFolder = SourceDir\One\
SecondFolder = SourceDir\One\
ThirdFolder = SourceDir\One\The Three Directory\
SecondThirdFolder = SourceDir\One\Three Too\

Mastering the dot, colon and pipe characters is the first key to deciphering the Directory table. To this day, I remember the ten minutes that Ben Chamberlain spent walking me through examples much like the one above. So much of the Directory table suddenly made sense. Hopefully, the discussion and examples above help unlock some of the secrets for you as well. Next time, we'll look at the power of the standard directories.

Tomorrow (or Sunday) I'm going to once again take a break from this thread and announce a very cool, very new addition to the WiX toolset.

Comments (2)

  1. Chui Tey says:

    Thanks, the syntax was cryptic, especially in the face of making everything SQL tables, this overloading of a single column made things so much more difficult.

  2. How to avoid overwriting files during administrative installations.

Skip to main content