How to NGEN files in an MSI-based setup package using WiX

  • Article

As described in this blog post, a set of custom actions was added to the WiX toolset last year to make it easy to create native images for managed assemblies in an MSI-based setup using the .NET Framework 2.0 version of NGEN.exe.  Native images are created to improve the performance of managed applications, and some of the details about the benefits they provide can be found in this MSDN Magazine article.

Prior to these WiX custom actions, it was relatively difficult and error prone to add NGEN to an MSI-based setup, but it is simple and straightforward now.  I wanted to demonstrate just how easy it is to use the WiX NGEN custom actions to encourage setup developers to use WiX and the NGEN custom actions for managed assemblies.

For this demonstratation, I'm going to modify the sample WiX files for the Q sample application that is shipped in the Windows Media Center SDK for Windows Vista.  I'm going to use the WiX v3.0 files that I introduced in this blog post as the basis for adding NGEN functionality.  Please note that the NGEN custom actions exist in both WiX v2.0 and WiX v3.0 so you are not limited to using WiX v3.0 in this scenario even though that is what I chose to demonstrate.

How to add NGEN custom actions to a WiX-based setup project

At a high level, you must make the following changes to your WiX project in order to add NGEN custom actions to an MSI built with WiX:

  1. Add a reference to the extension named WixNetFxExtension.dll, either by adding it to the References list in the Votive Visual Studio add-in or by passing it to candle.exe and light.exe directly using the -ext command line argument
  2. Add an XML namespace declaration that refers to the WiX NetFxExtension.  For example: xmlns:netfx="https://schemas.microsoft.com/wix/NetFxExtension"
  3. Add NativeImage elements as children of any files that you want to create native images for using NGEN.exe.  For example:  <netfx:NativeImage Id="q.dll" Platform="32bit" Priority="1"/>

WiX NativeImage configuration options

I created an updated set of WiX source files that include custom actions to run NGEN for Q.dll and Interop.Microsoft.Feeds.Interop.dll, and you can download them from this location - https://play.mediacentersandbox.com/tools/qsetup_wixv3_with_ngen.zip. 

This example includes only 32-bit NGEN, so you will need to update the Platform attribute if you want to create a 64-bit installer.  Also, this example performs synchronous NGEN by setting the Priority attribute to 1.  This will cause setup to wait for each native image to be generated before continuing with installation.  It is possible to change the Priority value to 3 to schedule an NGEN action to occur in the background using the NGEN service after setup completes.  This will speed up installation performance, but the native images will be compiled at some later point by the NGEN service on the system, which means that the native images may not be present the first time a user launches your application after installing it.

You can find full documentation about the attributes that can be set for NativeImage elements in the WiX documentation (wix.chm that is installed as part of the WiX toolset) or by using IntelliSense within the Visual Studio IDE after installing the WiX toolset.

The steps below will allow you to create an MSI for the Q sample application that includes NGEN functionality for the managed assemblies that are installed as a part of Q setup.

Building an MSI for Q that contains NGEN functionality by calling WiX tools directly

  1. Install Windows Vista Home Premium or Ultimate Edition
  2. Install Visual C# 2005 Express Edition or Visual Studio 2005 standard or higher
  3. Install the Windows Media Center SDK for Windows Vista
  4. Install the latest version of WiX 3.0 from https://sourceforge.net/project/showfiles.php?group_id=105970&package_id=168888. You need to install the ProjectAggregator2 MSI and then the WiX 3.0 MSI
  5. Download this zip file with updated Q setup files and extract the contents to the Q project directory. The Q project will be installed to %programfiles%\Microsoft SDKs\Windows Media Center\v5.0\Samples\Windows Media Center Presentation Layer Samples\Q if you installed the Windows Media Center SDK to the default location
  6. Right-click on the shortcut for Visual Studio 2005 or Visual C# 2005 Express Edition, choose Run as administrator and click Continue to launch Visual Studio with elevated privileges
  7. Open Q.sln - it will be installed to %programfiles%\Microsoft SDKs\Windows Media Center\v5.0\Samples\Windows Media Center Presentation Layer Samples\Q if you installed the Windows Media Center SDK to the default location
  8. Right-click on the Q project in the Solution Explorer and choose Properties
  9. Select the Build Events tab
  10. Add a new entry to the Post-build event command line text box that says "$(ProjectDir)\SetupWiXv3\build_q.bat" $(ConfigurationName)
  11. Click on the File menu and choose Save All
  12. Click on the Build menu and choose Rebuild Solution to build the Q binaries and then run build_q.bat

The above steps will produce an MSI named Q_Podcast_Client.msi that includes NGEN custom actions in %programfiles%\Microsoft SDKs\Windows Media Center\v5.0\Samples\Windows Media Center Presentation Layer Samples\Q\bin\release (or \bin\debug\ for the Debug version of the Q application).

Building an MSI for Q that contains NGEN functionality using Votive

The following steps can be used to build an MSI for the Q sample application directly from Visual Studio 2005 using the Votive WiX add-in:

  1. Install Windows Vista Home Premium or Ultimate Edition
  2. Install Visual Studio 2005 standard or higher
  3. Install the Windows Media Center SDK for Windows Vista
  4. Install the latest version of WiX 3.0 from https://sourceforge.net/project/showfiles.php?group_id=105970&package_id=168888. You need to install the ProjectAggregator2 MSI and then the WiX 3.0 MSI
  5. Download this zip file with updated Q setup files and extract the contents to the Q project directory. The Q project will be installed to %programfiles%\Microsoft SDKs\Windows Media Center\v5.0\Samples\Windows Media Center Presentation Layer Samples\Q if you installed the Windows Media Center SDK to the default location
  6. Right-click on the shortcut for Visual Studio 2005, choose Run as administrator and click Continue to launch Visual Studio with elevated privileges
  7. Open QWiXv3.sln - it will be installed to %programfiles%\Microsoft SDKs\Windows Media Center\v5.0\Samples\Windows Media Center Presentation Layer Samples\Q if you installed the Windows Media Center SDK to the default location
  8. In the Visual Studio Build menu, choose Batch Build...
  9. Select the configurations you want to build and click the Rebuild button to build them

The above steps will produce an MSI named Q_Podcast_Client.msi that includes NGEN custom actions in %programfiles%\Microsoft SDKs\Windows Media Center\v5.0\Samples\Windows Media Center Presentation Layer Samples\Q\QWiXv3\bin\release (or \bin\debug\ for the Debug version of the Q application).