Derek Cicerone Installing...

WiX, Setup, and trying to make it all easy, not just easier

Wednesday, April 05, 2006

heat.exe - making setup easier

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.


At Wednesday, April 05, 2006 10:07:00 AM, Anonymous Rob Mensching said...

WiX toolset's two year anniversary.

At Wednesday, April 05, 2006 11:20:00 AM, Anonymous Fredrik Grohn said...

Wow, now I have even more stuff on my COM+ CA to-do list. >_<

Way to go guys!

At Thursday, April 20, 2006 8:37:00 AM, Anonymous Dana said...


I'm very excited about the heat functionality. One of my biggest problems with WiX has been the learning curve especially with the elements that use Custom Actions (SqlDatabase, Website stuff, etc...).

I tried Heat out on a directories and it worked like a charm. When I tried to point it at a local Website to see what sort of code it would generate, I just got a System.InvalidOperationException. The command line I used was heat website websitename -out outfile.wxs. When you have time in busy schedule, could you post the correct way to harvest an IIS site? Maybe I misread the information about heat and this isn't supported yet.


At Friday, April 21, 2006 1:47:00 PM, Blogger Derek Cicerone said...

Hi Dana, the posted instructions for harvesting a website with heat should be correct. Could you please send an e-mail to in order to get a discussion going on the topic?

Also, I made some more changes in this week's release that tied up some of the loose ends in the website harvesting such as filling in the proper MSI identifiers and avoiding harvesting directories multiple times. I doubt this will fix the issue you encountered, but it might be worth a shot to try out the latest release.

At Tuesday, May 02, 2006 11:15:00 PM, Blogger Paula said...

This comment has been removed by a blog administrator.

At Friday, May 05, 2006 6:07:00 AM, Blogger Thomas said...

Is it possible, to include the
UIRef Id='WixUI' in the autogenerated (-template:product) Product-element?

Where can I find a listing of existing templates?

Thanks a lot!

At Friday, May 05, 2006 6:37:00 AM, Blogger Derek Cicerone said...

Hi Thomas, since Heat is not meant to auto-generate your setup every single time but just the first time, it shoul d be trivial to just add a UIRef by hand once you have the generated authoring. However, if the wixui support was changed to an extension instead just being a wixlib as it is today, we could easily add a mutator to the UI extension that would have options for heat to generate a UIRef automatically. In fact, this is probably a good feature request to make on the SourceForge site if you'd like to open it.

The documentation for the template option is currently very sketchy since its under development. We support values of "product" and "module" at this time. Additional templating options should probably be exposed as separate command line options (for example, wix ui could add an option ui="featuretree|mondo|installdir|...").

At Tuesday, May 09, 2006 2:33:00 AM, Anonymous Thomas said...

In contrast to tallow, heat generates for every single file a single component, although it could collect all files of a directory together in one component. I think this is introduced to have an option to define a features components more precise. Is this a feature, that can be disabled and let heat do like tallow did?

At Tuesday, May 09, 2006 9:12:00 AM, Blogger Derek Cicerone said...

Hi Thomas,

The reasoning behind only allowing one file per component is very simple actually - this is the safest way to generate a setup. By keeping each file in its own component, its much easier to avoid accidentally breaking component rules (for instance - you can't accidentally remove a file from a component after its shipped if the component only contained one file to begin with). Since heat is used for many scenarios and often in ways which we advise against (like generating setup every time), we have to make it as conservative as possible in how it generates its setup to help people avoid problems. The decision to always put one file per component should not affect the functionality of your setup (though it may impact the perf slightly). If you find that the number of components is unmanagable, please consider breaking up the generated authoring into groups that make more sense for your purposes and using ComponentGroup and ComponentGroupRef to organize your components more broadly into their parent features.

To get more background info on this decision and the component rules in general, please feel free to send mail to with any followup questions you might have.


Post a Comment

<< Home