Derek Cicerone Installing...

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

Wednesday, June 21, 2006

NGen support in WiX

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 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?
  1. 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 ...
  2. Add the extension namespace to your WiX source file:
    • <Wix xmlns="" xmlns:netfx="">
  3. Add a <NativeImage> element under each <File> you'd like to NGen:
    • <File Id="MyAssembly">
      <netfx:NativeImage Id="MyNGenImage" />
  4. 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: