Derek Cicerone Installing...

Retiring from the WiX community

2006-09-15T17:25:00.000-07:00

After over 3 years of working on WiX, I've decided its time to pursue other interests. It has been a true pleasure to work with this incredible community of volunteers. In fact, I likely would have stopped working on WiX a very long time ago if not for all your support. Thank you all for the good memories and I wish you the best of luck for the future.

Automatically generating component GUIDs

2006-09-08T17:32:00.000-07:00

Yes, this change is exactly what you think it is: automatically generating component GUIDs. We believe that we may have come up with a safe way to automatically generate component GUIDs each build and ensure that component rules will not be broken (easily). If this idea works, it will obviously have a huge impact on the way that setup is authored for Windows Installer since it may become possible to generate authoring each build instead of maintaining it by hand.

Due to the nature of this feature, I’d like to ask the community for help. If you can do any of the following, it would be greatly appreciated:

1. Review the overall design for this feature. Do you see any scenarios in which it will allow the component rules to be violated?
2. Try it out. Are you able to accidentally cause component rule violations? Do shared components properly share their component guids as well?

A component with a generated component GUID will look like this (note the asterisk in the Guid value):

</Component>

Here’s how it works:

Canonicalize the target path to the key path file by:

Lowercasing all the characters in the path except for the standard directory identifier which must start all paths (since the file system is case-insensitive).
Ignore any blank directory entries (those with “.” in the DefaultDir column). This prevents paths like “Root\.\file.txt” and “Root\file.txt” from getting different component guids.
Always begin a path with a standard directory identifier (such as “ProgramFilesFolder”). This eliminates differences in how source images are laid out in various products.

Create a version 3 UUID based on a pre-determined WiX namespace Guid and the path to the file.

Why these are legal guids?

This implementation follows the RFC 4122 specification for a version 3 MD5-based UUID (you can verify this because the first number of the third set of hex digits in the guid will always be ‘3’, like this: {xxxxxxxx-xxxx-3xxx-xxxx-xxxxxxxxxxxx}). In case you are wondering, guidgen creates version 4 UUIDs (based on randomly pseudo-randomly generated data). There is also a version 5 UUID which uses SHA-1 hashing, but I chose MD5 because it had an example implementation which allowed me to verify that my port of the code is correct.

Limitations:

Only supports one file per component, which must be the key path.
No ODBCDataSource children allowed (but there can be registry values and any other type of child).
Does not support multiple components installing the same file – a collision of the component guids will occur (this is caught by ICE validation).
Guids cannot be generated until the binder because that’s when all localization and wix variables are resolved.
Files must be rooted under a well-known Windows Installer standard directory (such as “ProgramFilesFolder”).

Here is an example of a canonicalized path which is hashed to create the component GUID:

ProgramFilesFolder\my product\some file.exe

Torch and Pyro

2006-09-08T17:11:00.000-07:00

Although the WiX toolset has been out for quite a while now, one very elusive area which has not been tackled is transform and patch support. With the addition of a new tool called "Torch", WiX will now have transform creation support.

How is the tool used?
Here's a sample command line: "torch.exe target.msi updated.msi -out transform.mst". This command will create a transform.mst file which will transform target.msi into updated.msi.

Does torch support special WiX xml file formats like the .wixout file format?
Yes, the .wixout file format has been extended for transform support. This provides full round-tripping support in conjunction with dark's new -xo command line option. You could create a transform with torch, then "decompile" it with dark into a .wixout file, then re-build the transform file by passing the .wixout file into torch. Although this is a pretty impractical series of tasks, there are likely scenarios in which an advanced user would want to examine a transform in an xml format (you could easily diff two transforms) or build a transform solely from xml.

What features would likely be added in the future?

Create a transform from two .wixout files.
Create a transform from two .wxl files (and a .wixout file) in order to create a language transform.

What about patch creation support?
Although it won't be supported at this time, the transform support is a key piece of the infrastructure needed to make progress towards patch creation support. There is a new tool called "Pyro" which contains the engine for patch creation but not the nice user-interaction necessary to make it usable. With a bit more work, Pyro should one day be the WiX tool for creating patches.

NGen support in WiX

2006-06-21T09:00:00.000-07:00

I'm very happy to announce that we're releasing a new extension today which will allow you to easily run NGen as part of your WiX-based setup. This functionality will be part of the newly created WiX NetFx Extension which can now be found in the latest weekly builds at http://wix.sourceforge.net/releases. Although the NGen support looks simple, it was actually sizable project for the WiX team and was only possible due to the significant contributions and insights of members from the NGen and Visual Studio teams. I'd like to thank Surupa Biswas, Sameer Garde, and Peter Marcu, for all their effort in designing and reviewing this extension and Scott Kurtzeborn for doing the coding of the Windows Installer custom actions.

Will the .Net Framework 1.1 be supported?
No. Unfortunately, at this time we will only support the .Net Framework 2.0+. There is actually a very simple reason for why 1.1 support was left out - it's much more difficult to support for rollback. The NGen update feature really was key to properly supporting NGen inside of Windows Installer's transaction model. It enables robust rollback behavior by supporting the capability to rebuild native images that may have existed on the machine prior to an installation failure (in the case of collisions). Unfortunately, since this feature wasn't available in the first version of NGen, it would make handling rollback much more difficult. If there is enough demand, we could look at adding support for the .Net Framework 1.1, however, it would likely be less than the usual quality you've come to expect from WiX due to the limitations mentioned above.

Will this work with WiX 2.0?
Yes. Unlike most recent WiX toolset improvements, since this is a new extension, we were able to provide it for both WiX 2.0 and WiX 3.0. However, you will need to update to the latest WiX 2.0 build in order to use the extension. This is necessary because the <File> element previously did not allow extension child elements.

How do I use it?

Inform Candle, Lit, and Light of the new extension.

In WiX 2.0, you need to specify the following for each tool:

candle -ext "Microsoft.Tools.WindowsInstallerXml.Extensions.NetFxCompiler, WixNetFxExtension" ...
lit -ext "Microsoft.Tools.WindowsInstallerXml.Extensions.NetFxCompiler, WixNetFxExtension" ...
light -ext "Microsoft.Tools.WindowsInstallerXml.Extensions.NetFxCompiler, WixNetFxExtension" <path to netfx.wixlib> ...

In WiX 3.0, its much simplier:

candle -ext WixNetFxExtension ...
lit -ext WixNetFxExtension ...
light -ext WixNetFxExtension ...

Add the extension namespace to your WiX source file:

<Wix xmlns="http://schemas.microsoft.com/wix/2003/01/wi" xmlns:netfx="http://schemas.microsoft.com/wix/NetFxExtension">

Add a <NativeImage> element under each <File> you'd like to NGen:

<File Id="MyAssembly">
<netfx:NativeImage Id="MyNGenImage" />
</File>

That's it - just build everything and it should work.

Is NGen 2.0 queuing supported?
Absolutely. For those who are not aware of this great new feature - with NGen 2.0, you can now queue an assembly to be NGen'ed at a later time. This is great for setups because it allows the installation to happen very quickly without typing up the user's machine doing expensive NGen operations. Then, after the install is complete, the NGen service will detect when the computer is idle and automatically begin performing the queued NGen tasks. By default, all NGen operations performed by WiX recieve the lowest priority, NGen on idle, to ensure the quickest setup experience. However, this is fully configurable via the NativeImage/@Priority attribute. Values range from 0 (NGen syncronously - this does not use queuing, the assembly is NGen'ed immediately) to 3 (NGen on idle). You can use these settings to very granularly control the NGen behavior of your setup.

Are other NGen options like /AppBase, /Debug, ... supported?
Most NGen 2.0 options are also supported, please see the documentation for the <NativeImage> element for more details on how to use them.

Where can I find the documentation for the NGen functionality?
The NGen functionality is documented under the "NativeImage Element" topic of WiX.chm.

How does the NGen functionality actually work?
Is actually very simple. There are two main custom actions: NetFxScheduleNativeImage and NetFxExecuteNativeImageCommit (NetFxExecuteNativeImage merely provides support for scenarios in which rollback is disabled). The first custom action is the scheduler. It looks at the NetFxNativeImage table to determine which actions need to be performed. It then builds up a list of command lines for calling NGen.exe (which must be installed on the machine prior to installation). The second custom action then calls the NGen.exe command lines. So basically, all the WiX custom actions do are wrap up calls to the NGen.exe tool.

Why is the extension called WixNetFxExtension?
The word "NetFx" is the codename for the group that works on the .Net Framework technologies. This extension was given a very broadly applicable name because we'd like it to support much more than just NGen in the future. Already, you may have noticed that the extension contains some very useful locators for finding the .Net Framework 1.1 and 2.0 installation directories and SDK directories.

How do I use the new .Net Framework locators?
The locators can be used by simply creating a reference to the appropriate <Property> which you would like to use in your setup. For example, to get the directory in which the .Net Framework 1.1 SDK is installed on the user's machine during setup, add <PropertyRef Id="NETFRAMEWORK11SDKDIR"> to your authoring and use the property as you would any other. Check out the file NetFxExtension.wxs in the WiX sources to see what other properties are supported. Please note that these property names are subject to change as this support is very new.

Where can I find more information about using NGen?
To find out more information on using NGen (which will help with using the WiX functionality as well), please see the following article by Surupa: http://msdn.microsoft.com/msdnmag/issues/06/05/CLRInsideOut/default.aspx.

MSI Validation in WiX

2006-04-21T13:38:00.000-07:00

One of the most frequently overlooked steps in building a Windows Installer setup is validation. Validation is very important; it finds all sorts of problems with per-user installations, collisions between installed files, and other common authoring mistakes that are hard to catch until the complete MSI or MSM file is built. Often, when debugging a setup problem, I've found that just running validation would quickly find the mistake(s).

Ok, so if validation is so important, why doesn't everyone run it? There's a few reasons: some people simply aren't aware of MSI validation, others are lazy, and the grand majority of people simply just forget because its an optional step.

With WiX 3.0, running validation is now easier than ever because its integrated directly into Light.exe. Just keep using the WiX tools like you always have in the past. If Light finds any validation problems while linking your MSI or MSM file, it will simply display a warning or error message. It's really that simple. Best of all, Light will even display source line information about where an ICE error or warning came from when it's available.

With the addition of the validation infrastructure to Light in WiX 3.0, we thought it would also be useful for the users of WiX 2.0 and other installation creation programs to have a simple way to run validation on their MSI or MSM files from the command line. So, we're also releasing a new tool called Smoke which can run validation on any MSI or MSM file and reports errors and warnings in the same convenient command-line format as the other WiX tools.

What if I don't want to run validation?
If you would like to suppress validation, simply supply the option -sval to light.exe. However, this is strongly discouraged since it means that you won't automatically get validation coverage on your setup.

Can I suppress an individual Internal Consistency Evaluator (ICE)?
Absolutely, just pass -sice: on the command line. For instance, to suppress ICE33, you would pass -sice:ICE33.

Are there any downsides to running validation in Light?
Yes, running validation will make your builds a bit slower. However, due to the benefits, the time spent validating is a very good trade-off in comparision to time wasted debugging issues that could have been caught simply by keeping validation on.

Do I really need to run validation?
Running validation is a very important step in insuring that you are creating a quality setup experience for your users. With this new validation feature, we were finally able to test our own MSI packages and we were shocked at the number of issues it found (since we'd like to consider ourselves somewhat experts in the setup area). This resulted in several improvements to Candle and some of the extensions, but even with these improvements, we'll never be able to guarantee the coverage provided by simply running validation.

Is there any documention on validation from the Windows Installer team?
There are several good articles on MSDN about using validation:

Internal Consisteny Evaluators
ICE Reference - very useful for finding out what a particular ICE does
Merge Module ICE Reference - for finding out about merge module ICEs

Where do ICEs come from?
ICEs are nothing more than custom actions which run against a database and display warnings and errors based on what they find. Since they are merely custom actions, they are not surprisingly packaged into special Windows Installer database files with a .cub extension. The extension may seem a bit arbitrary until you learn one vital piece of information: the true extension of these files is "cube" - "cub" is merely an 8.3 compliant name. It's a play on words because the tests are called ICEs (ice cubes - get it?).

The Windows Installer team distributes several cube files. The two most notable files are darice.cub and mergemod.cub. These cube files contain, respectively, the ICEs for MSI and MSM files.

Which ICEs will WiX run against my MSI or MSM file?
For MSI files, WiX will run all the ICE tests found in darice.cub. For MSM files, WiX runs mergemod.cub. Please note that ICE33 has been disabled by default because it forces authors to use the advertised COM tables instead of normal registry keys whenever possible. Due to problems with using advertised COM registration in certain scenarios (like repair), the WiX team does not suggest this practice and thus has disabled the ICE by default.

How does WiX run validation?
WiX uses the method outlined here. Basically, Light takes your MSI file, merges a .cub file into it, registers an external UI handler (like its going to run an installation), and then runs the custom action sequence found in the _ICESequence table (ignoring the ICEs you chose to suppress of course).

So, if an ICE is nothing more than a custom action, can I make my own?
You can create your own ICE custom action and package it into a cube file, just like the standard cube files. However, at this time, Light and Smoke do not support passing custom cube files into the validation engine. If you would like this feature to be added, please open a request on SourceForge.

Why is Smoke called "Smoke"?
It's another play on words. Because the smoke program essentially tests an MSI or MSM file for problems, its like a "smoke test".

heat.exe - making setup easier

2006-04-05T08:18:00.000-07:00

Today is April 5, 2006 – the 2 year anniversary of the WiX Open Source Project!

What better way to celebrate the anniversary of the WiX Toolset than by releasing a new tool? Today, I'm proud to announce the availability of Heat in WiX 3.0. Heat is very similar in functionality to Tallow or the engine inside of ClickThrough: it has the capability to quickly capture files and directories from a computer and turn them into WiX authoring. However, the functionality of heat goes well beyond what either of these tools could provide for capturing WiX authoring. A big thanks goes to Reid for helping me make Heat a reality - he came up with a lot of the original ideas for this project and was a huge help with the harder design and naming issues.

Heat is our attempt to create an entire ecosystem of what we're calling "harvesters" and "mutators" (more on the mutators later). Harvesters are essentially WiX extensions which enable a developer to "harvest" any information into WiX authoring. For example, we've just released a new WiX extension called the WixUtilExtension. This extension contains a harvester that enables you to very quickly harvest an entire directory of files and any self-registration inside of those files. So if you have an entire directory of DLL files which each use self-reg for their COM registration, you no longer need to run Tallow on each individual file. You can now just run "heat.exe dir C:\directory -out sourceFile.wxs" and do this all automatically.

Unlike Tallow, Heat is optimized for working with WiX 3.0. This means that it does not create Id attributes on Registry elements and doesn't set short file names. Instead it relies on the auto-generation capabilities of Candle wherever possible. When Heat cannot rely on Candle to generate an identifier, it does its best to create a unique one based on the name of the file or directory that is being harvested. So if you harvest a file called "foo.dll", unless there is a collision with other files captured at the same time, its File/@Id will be "foo.dll" and the name of the component containing that file will be "foo.dll". This should make it much, much easier to capture individual parts of your setup and paste them together into your product with minimal identifier collisions.

Heat makes creating simple setup authoring faster than ever before with a templating capability. In the past, each time you create a new setup, you also had to create new Product, Package, etc... elements. Or if you're like me, I'm guessing you just copied another WiX source file and tweaked it to make your setup. With Heat, this is no longer necessary. Just run Heat with the "template" command line option like this: "heat.exe dir C:\directory -out sourceFile.wxs -template:product". This will do the normal harvesting, but then wrap the output up in a Product element. Additionally, it will hook up your root directories under TARGETDIR and put your components under a default feature. All you need to do is replace a few placeholders like "PUT-PRODUCT-NAME-HERE" with the actual values for your product and compiler/link. It's literally that easy. Just in case you are wondering, we still support auto-generation of guids - just use the -gg option. It will even generate the ProductCode. Of course, if you'd like to create a merge module quickly, you can just run with the -template:module option.

If you've read this far, there's a very good chance that you're either excited by all the new functionality in Heat or a bit disappointed because nothing in there seems to be ground-breaking. Well of course, I've saved the best part for last. Heat is not a super-tallow or command line version of ClickThrough. It's an engine for harvesting information into WiX authoring. Although all my examples so far have dealt with files and directories, there's nothing about how Heat works that prevents it from capturing more interesting things. Although its a bit under construction, Heat has the capability, today, to capture IIS web sites. Simply run 'heat.exe website "My WebSite Name" -out sourceFile.wxs' to harvest a web site and all its files. You can then compile and link with the WixIIsExtension to create an entire web site setup in minutes! Please note: there are currently a few missing bits for this feature, like it doesn't set all the Id attributes yet (I'll try to get this done for next week). Once this feature is completely finished, since Heat can set all the identifiers for you uniquely, generate all the guids, and wrap everything in a Product element with the nececessary ComponentRef elements, all you have to do is fill in a few placeholders like "PUT-PRODUCT-NAME-HERE"

I mentioned the idea of mutators earlier but didn't really go into what it meant. Mutators are a new class of functionality within WiX similar to the compiler or linker. A mutator is simply a class which takes a WiX CodeDOM object as its input and mutates it. Mutating is essentially like running a transform on XML, but since its a WiX CodeDOM, its strongly-typed and much easier to work with versus XML transforms. Mutators are the secret behind why Heat is so simple and powerful. In the past, if a harvesting tool (like Tallow) had options for tweaking its output by using fragments or wrapping the output in a Product element, the code doing the actual harvesting needed to be aware of those settings. This made adding new functionality very cumbersome because each new extension had to be aware of all the options it should be support. Even in Tallow, you may notice that depending upon how registry keys are harvested (from a .reg file or a self-reg capture), the output may differ. In Heat this is not a problem - harvesters just capture the very simplest information possible, then rely upon the mutators to mutate the output to reflect the specific options the user wants.

In later posts, I'll go into the details about how Heat works and how you can very easily write your own extensions to harvest whatever you find interesting. As you might imagine, Heat can do much, much more than I'd want to talk about in this introductory post. I hope to more fully explain its capabilities in later posts.

How does this affect ClickThrough?

ClickThrough will be refactored to use the harvesters and mutators of Heat as its new engine for capturing files from your machine. There are currently a few issues with the internal WiX authoring created by ClickThrough - this will address those issues and ensure that future versions of ClickThrough remain more in-sync with any changes made to the WiX source schema.

How does this affect Tallow?

Tallow will no longer exist in WiX 3.0. Tallow will continue to be released as part of WiX 2.0. The code for Tallow in WiX 2.0 and 3.0 is identical, so if you prefer to use Tallow instead of Heat, you can simply grab it from WiX 2.0.

Why doesn't Heat allow me to specify the text for the placeholders on the command line so that I can generate my setup every time?

Heat is designed to allow a setup author to very quickly generate their setup authoring the first time. From then onward, the authoring should be maintained manually to ensure that guids and identifiers remain stable and component rules are not broken. In order to use Heat to generate setup every time, it would be necessary to create a database which tracks the components, their guids & identifiers, and their files for every release of your product. We call this a component catalog. Heat does not provide a component cataloging capability - however - it does expose the necessary functionality so that anyone could write a component catalog, hook it into heat as an extension, and generate their setup automatically without breaking component rules.

Where should I mail Heat bug reports or feature requests?

Please submit bug reports or feature requests to the WiX site on SourceForge. I've created new categories for Heat/harvester - please use them to ensure the bugs or feature requests are properly assigned.

Are there any other planned features for Heat right now?

Sure, I think it would be nice to harvest a SQL database. There have also been a lot of ideas floating around about working with Visual Studio projects. I'm sure people will come up with lots of cool new things to do with Heat.

Auto-generation of short file and directory names

2006-02-13T01:45:00.000-08:00

Auto-generation of short file and directory names has finally been checked into WiX 3.0. This feature should be available in the very next release!

Will this feature be ported back to WiX 2.0?

Unfortunately, this feature will not be ported back to WiX 2.0. It is simply too disruptive (it modifies the schema for and elements) and dangerous for the stable 2.0 codebase.

Should I upgrade to WiX 3.0 to take advantage of this feature?

This is a decision that each individual team should make for themselves, but we do have some recommendations based on what features your group is using and when you expect to ship.

First off, if your product is shipping in 2006, please do not use WiX 3.0. We simply cannot guarantee with any certainty that WiX will be stable and bug-free enough in time for you to ship your product. We also reserve the right to continue deprecating and replacing certain functionality in WiX 3.0 as well as create incompatibilities between versions of WiX 3.0. For example, so far we’ve deprecated FragmentRef, deprecated all src attributes (in favor of more descriptive attributes like SourceFile), broken backwards compatibility for wixout files, completely re-vamped the WiX extensions and how they are packaged, etc…

If you are shipping in 2007 or later, then WiX 3.0 may be appropriate for your group. We hope to have WiX 3.0 entering lockdown sometime near the middle to end of this year (more likely at the end). For comparison, WiX 2.0 entered lockdown in the fall of 2005, so we like to spend about a year on stabilization. Some of the things to look at for your group are whether you can tolerate the need to infrequently update your source code whenever features are deprecated or re-named. We have a tool called WixCop which will automatically update most wix source code the latest schemas, however, it currently also re-formats code to a very strict standard of 2-space indentation and double-quotes for attribute values. For groups willing to adopt this standard, wixcop makes it trivial to keep up-to-date and also police the style of source code in your organization. Sometimes features are deprecated with no replacement (like FragmentRef). In these cases, significant re-design by hand may be needed (currently we only anticipate one more breaking change like this: we will no longer support nested elements, instead, this functionality will be replaced by , , … elements with much more explicit usage).

I’m using WiX 3.0, how do I migrate my authoring to the new schema?

If your group can use WixCop, that is definitely the preferred route since it will automatically update all your sources (hopefully) without mistakes. As I mentioned before, the downside is that it also re-formats code to 2 space indenting.

To migrate elements manually, do the following:

Change this:

To this:

Change:

Name -> ShortName

LongName -> Name

LongName is now deprecated.

Migration of elements is a bit more complicated.

Change:

Name -> ShortName

LongName -> Name

SourceName -> ShortSourceName

LongSource -> SourceName (note that this is a bit weird because the old name was missing “Name”)

LongName and LongSource are now deprecated.

I’m using WiX 3.0 how do I take advantage of this feature and stop specifying short names?

For existing authoring, after migrating to the new schema as outlined above, remove the Short* attributes. WiX will then automatically generate the short names for you.

For new authoring, just stop specifying the Short* attributes. So for a file, just specify File/@Name. For a directory, just specify Directory/@Name (and the optional Directory/@SourceName if necessary).

How do I specify a file name that is already short?

If you have a file name that is already short and 8.3-compliant, like file.txt or example.doc, you just specify this file name in the Name attribute (not the ShortName attribute). WiX will automatically determine that you’ve specified a valid short file name and suppress generating a short name. The idea here is that you should never have to specify anything other than the Name attribute, regardless of whether the desired name is long or short.

How does WiX create the short file and directory names?

The short file names are created using the following algorithm:

Create a string by concatenating “File” + ‘|’ + <parent> + ‘|’ + <lowercase filename>. The pipe characters (‘|’) are necessary for canonicalization. The “File” at the front allows us to expand this feature in the future to cover or other short file names we’d like to generate under components. The parent component identifier is used instead of the file identifier because someday I’d like to add the feature of automatically generating the file identifier as well. The long file name is lowercased for canonicalization purposes. Canonicalization for short file names basically means that we’d like to see a collision of generated short file names whenever we can expect to see a collision of long file names within a single component.
MD5 hash the string into a 128-bit hash.
Convert the hash into a base64 string and replace illegal file name characters with appropriate alternatives. Specifically, we replace ‘/’ with underscore (‘_’) and ‘+’ with dash (‘-‘).
Lowercase the entire base64 string and truncate it to 8 characters in length.
If an extension existed for the original long file name, append up to 3 characters from that extension onto the end of the new string from the last step. For example, if the long file name was “sources”, then no extension is added, if the long file name was “text.txt”, append “.txt”, and if the long file name was “my project.csproj”, append “.csp”.

The algorithm for creating short directory names is very similar. The only differences are that we use the directory’s identifier instead of the parent file identifier in step 1 and there is no extension handling for step 5.

How will using generated short file and directory names affect patching?

Since the generated short file and directory names are actually hashes of the user-specified long file and directory names, these names should remain consistent as long as the file names and relevant identifiers included in the hash (see previous question for more info about which identifiers are included in the hash) do not change.

What happens if I move a file containing a generated short file name to another component?

The generated short file name will likely change since the parent component identifier is part of the hash which defines the generated short file name. This is expected behavior and by design.

What if I use the same long file names in many components; will the generated short file names collide?

We’ve tried very hard not to prevent short file names for colliding when appropriate. The only time that we’d like generated short file names to collide is when the same long file name is duplicated in a single component (since this makes the installer attempt to install multiple files to the same file name on the target machine). Since the hash used to generate the short file names includes the parent component identifier of the file, theoretically, re-using the same long file name in multiple components should not be a problem.

What happens when a generated short file name collides with another generated short file name(s)?

Light.exe has now been updated to detect collisions of generated short file names across all files in a single msi/msm file. It does not take into account directories since it’s possible to re-map almost any directory to any path on the target machine.

If a collision is detected before you ship your product for the first time, you can update any or all of the colliding files by manually specifying the ShortName attribute. Unfortunately, it’s not possible for WiX to automatically resolve collisions since that would not result in 100% stable generated short file names (depending upon whatever else you compiled with, names may differ across products or merge modules). So these collisions must always be resolved by hand. In testing, we found collisions to be quite rare (in fact we were never able to create one).

If a collision is detected while patching an older product or while creating a minor product update, it is very important to only specify ShortName on the newly added files for the patch or update. This will keep the previously shipped file names consistent. Please remember that although you may not anticipate your customer ever installing to short file names, it is almost always possible that they did.

What happens when a generated short directory name collides with another generated short directory name(s)?

Currently: nothing. If this is a problem, we can attempt to detect this scenario in the future.

When will the File/@LongName and other deprecated attributes be removed from WiX?

We usually keep deprecated features in for about a year or so to allow everyone time to update. The deprecated attributes will likely work until at least 2007.

I’m using WiX 3.0, do I have to update my schema? Do I have to use the auto-generated short names?

No and no. As long as support for the deprecated attributes remains (until 2007), you don’t need to update. However, we strongly encourage updating since the deprecated attributes will eventually be removed entirely.

You never need to use the new auto-generated short names feature if you don't want to use it. Simply begin specifying the new ShortName attributes to continue manually specifying short file names.

Candle (part 1)

2006-01-09T01:16:00.000-08:00

The core of the WiX toolset primarily consists of a compiler and a linker. The compiler is called candle and the linker is called light (here's an explanation of how these names came about). The functionality provided in each of these tools seems to be a source of constant debate by many users of WiX. I've even been confused about whether a certain operation was performed in the compiler or linker from time-to-time. For this post, I'd like to talk about candle. Parsing The guts of candle are basically implemented in two classes: preprocessor.cs (the preprocessor) and compiler.cs (the compiler). Let's leave a discussion of preprocessor.cs for another time. The class Microsoft.Tools.WindowsInstallerXml.Compiler in compiler.cs is nothing more than a simple recursive-decent parser. Although the formal definition seems to make this seem complicated, it really isn't. An example will probably be the easiest way to illustrate how simple the parsing code is. Here's the contents of a simple WiX source file (let's call it example.wxs):

The compiler will begin parsing this file by looking at the element first. This is done by calling ParseWixElement. Inside the method ParseWixElement (which can be found in compiler.cs), there is a foreach loop for processing each of the child elements under a Wix element. In fact, here's a simplied version of what that code looks like: ///
/// Parses a Wix element.
///
/// Element to parse.
private void ParseWixElement(XmlNode node)
{
foreach (XmlNode child in node.ChildNodes)
{
if (XmlNodeType.Element == child.NodeType)
{
switch (child.LocalName)
{
case "Fragment":
this.ParseFragmentElement(child);
break;
case "Product":
this.ParseProductElement(child);
break;
default:
this.core.UnexpectedElement(node, child);
break;
}
}
}
} Since the first child element of the element is a element, the compiler will then call ParseFragmentElement. This method would then call ParsePropertyElement. There is a Parse*Element method for each of the elements supported by WiX in its source files. Each element roughly corresponds to a particular table in an MSI file. So, in the example above, we'd be creating a single row in the Property table by writing a element. To be continued...