Converting the Q sample application setup to use WiX v3.0 and Votive

 

I previously posted an example of how to use WiX to build an MSI-based installer for a Windows Media Center application.  In that example, I created an installer for the Q podcast and video blog client sample application that is included in the Windows Media Center SDK for Windows Vista, and I used WiX v2.0.

Since then, I have been asked by a few customers about how to create an equivalent installer using WiX v3.0.  I decided to try converting the sample installer files for the Q sample application that are installed by the Windows Media Center SDK to WiX v3.0 format to determine what work would be required.  There are several changes required to get everything working correctly in WiX v3.0, so I am going to post an updated set of setup files, scripts and instructions to demonstrate how to create an MSI-based installer for a Windows Media Center application using WiX v3.0.

One of the biggest additions in WiX v3.0 is MSBuild integration for the Votive Visual Studio add-in for WiX.  This means you can create a Visual Studio project (named a .wixproj), add it to the solution with the Q sample application, and directly build an MSI for your applications after building the binary files that make up your application.  You can also use MSBuild command lines to build your binaries and MSI directly without using the Visual Studio UI.

Votive (like all Visual Studio add-ins) is only supported on Visual Studio 2005 standard edition and higher, so I am going to post 2 separate sets of instructions - one that is similar to the instructions in the Windows Media Center SDK and uses a batch file to build the MSI using WiX tools (so that you can build an MSI using Visual C# 2005 Express Edition if desired); and the other that uses Votive to create a .wixproj and build the MSI using MSBuild within the Visual Studio IDE.

Building an MSI for Q by calling WiX tools directly

The following steps can be used to build an MSI for the Q sample application from Visual C# 2005 Express Edition or Visual Studio 2005 by adding a post-build step that executes a batch file that will call the WiX compiler (candle.exe) and linker (light.exe):

  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 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 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 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).

How to add a .wixproj to an existing Windows Media Center application solution

If you would like to add a .wixproj to your own Visual Studio 2005 solution, you can use steps similar to the following.  These are the steps I used to create the project files used in the steps above:

  1. Install Windows Vista Home Premium or Ultimate Edition
  2. Install Visual Studio 2005 standard edition 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. Right-click on the shortcut for Visual Studio 2005, choose Run as administrator and click Continue to launch Visual Studio with elevated privileges
  6. 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
  7. Right-click on the Q solution and choose Add | New Project...
  8. In the Add New Project dialog, click on the WiX item in the Project types list and select WiX Project in the Templates list
  9. Click on the Browse button and browse to the location of the Q project so that the WiX project will be created in a sub-directory under the Q project folder. 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
  10. Click OK to add the new WiX Project to the Q solution
  11. In the new WiX Project you created, right-click on References and choose Add Reference...
  12. In the Add WiX Library Reference dialog, click on the Browse tab, select the item named WixUIExtension.dll and click Add
  13. Select the item named WixUtilExtension.dll and click Add
  14. Click OK to dismiss the Add WiX Library Reference dialog
  15. Double-click on the WiX source (WXS) file that was added to the new WiX project by default, select all of the text in the file and delete it
  16. Add the contents of the updated Q WXS file from this location
  17. Right-click on the WiX project and choose Add | New Item...
  18. In the Add New Item dialog, select WiX Localization File and click Add to add a new localization file
  19. Double-click on the WiX localization (WXL) file that was added to the project in the previous step, select all of the text in the file and delete it
  20. Add the contents of the updated Q_en-us.wxl file from this location
  21. Right-click on the WiX project and choose Project Dependencies...
  22. In the Project Dependencies dialog, click on the Dependencies tab, select the WiX project in the Projects dropdown, and check the box for Q in the Depends on list box. This will cause the Q binaries to be rebuilt each time you rebuild the MSI
  23. Right-click on the WiX project and choose Properties
  24. Click on the Compiler tab
  25. In the Configuration dropdown, select Debug
  26. Add the string BuildType=Debug to the Define constants text box
  27. In the Configuration dropdown, select Release
  28. Add the string BuildType=Release to the Define constants text box
  29. Click on the Linker tab
  30. In the Configuration dropdown, select All Configurations
  31. Add the string en-US to the Cultures text box
  32. In the Visual Studio File menu, choose Save All
  33. In the Visual Studio Build menu, choose Batch Build...
  34. Select the configurations you want to build and click the Rebuild button to build them

The above steps will produce an MSI in %programfiles%\Microsoft SDKs\Windows Media Center\v5.0\Samples\Windows Media Center Presentation Layer Samples\Q\<your WiX project name>\bin\release (or \bin\debug\ for the Debug version of the Q application).

Changes made to Q setup to convert the setup files from WiX v2.0 to v3.0

If you are interested, the following is a summary of the changes that I made to convert the WiX setup files for the Q sample application from v2.0 format to v3.0 format:

  1. Converted WixUI and WixCA to use new WiX v3.0 extensions named WixUIExtension.dll and WixUtilExtension.dll; as part of this, I added 3 WiX variables to provide customized setup UI bitmaps and a customized license agreement
  2. Created a new component named QShortcut that is used to install the shortcuts to the Q application.  This new component has a HKEY_CURRENT_USER registry value as a keypath and a RemoveFolder entry.  This new component resolves ICE43, ICE57 and ICE64 errors that would otherwise occur while validating Q_Podcast_Client.msi.  Because the Q MSI sets the ALLUSERS property to 1, these 3 ICE validation failures would likely not cause any functional problems to end users, but WiX v3.0 performs ICE validation during the linking phase of the setup build process by default, and I preferred to present a sample that did not rely on suppressions for these ICE validation errors.
  3. Updated some attributes whose names have changed between WiX v2.0 and v3.0 (such as Source instead of src, RegistryValue instead of Registry, Name instead of LongName because WiX v3.0 performs automatic short filename generation, etc)
  4. Added culture information to the WiX localization (WXL) file, and added a command line parameter to light.exe to specify the en-US culture
  5. Updated the WiX xmlns statement to use the WiX v3.0 schema instead of the WiX v2.0 schema
  6. Updated source file locations to use relative paths so the build scripts no longer had to copy all of the source files to a single directory; as part of this, I added a WiX preprocessor variable named BuildType to allow the build process to dynamically pick up debug or release binaries depending on which configuration is built; this step was not technically necessary to convert the files to WiX v3.0 format, but makes the setup build process cleaner and easier to understand

<update date="1/23/2007"> Removed Visual C# Express from the list of possible Visual Studio versions in the steps for using Votive to build the Q installer. The Visual Studio 2005 Express Editions do not support installing add-ins, so Votive (like all Visual Studio add-ins) requires Visual Studio 2005 Standard Edition or higher. </update>