Creating an installer that includes a Visual Studio bootstrapper package and an MSI built with WiX 3.0

  • [アーティクル]

A few days ago, I wrote a blog post describing how to create an MSI-based installer for a Windows game created with XNA Game Studio 3.0.  In that post, I described how to create custom actions in the MSI to check for system-level prerequisites (the .NET Framework and the XNA Framework Redistributable) and block the MSI from installing if they are not installed on the user's system.

Adding a bootstrapper to your game installer

The next thing I want to demonstrate is how to expand on the steps in that blog post to create an installer that will do all of the following:

  • Check for the presence of prerequisite components for the game on a user's system.
  • Download and install any prerequisites that are missing.
  • After prerequisites are installed, trigger the installation of the game MSI.

Visual Studio includes a bootstrapper that can do all of the above, and XNA Game Studio 3.0 includes a prerequisite package for the XNA Framework Redistributable 3.0 that integrates with the Visual Studio bootstrapper.  As a result, you can use the Visual Studio 2008 or Visual C# 2008 Express Edition IDE to create an installer for your game for both ClickOnce packages and VS setup/deployment projects, and I have previously posted steps for doing this in this blog post.

If you want to create an installer that uses the Visual Studio bootstrapper along with an MSI built with WiX instead of an MSI build with a VS setup/deployment project, you need to perform a couple of additional steps:

  1. Create an MSBuild project that contains information about the prerequisites you want to include for your game and also contains a GenerateBootstrapper task with the settings that you want to use for your installer.
  2. Build your MSI with WiX using the steps from my previous blog post.
  3. Build the bootstrapper for your game by running MSBuild for the project you create in step 1.

Updated sample that builds an MSI and a bootstrapper

I have posted a sample at https://cid-27e6a35d1a492af7.skydrive.live.com/self.aspx/Blog%7C_Tools/WiX%20Samples/wix%7C_sample%7C_xgs30%7C_game%7C_with%7C_bootstrapper.zip that extends my previous sample so you can use it to create a bootstrapper in addition to an MSI.  It includes the following additions/changes from the previous sample:

  • The file wix_sample_xgs30_game_bootstrapper_netfx35.proj is an MSBuild project file that will create a bootstrapper for a game that will install the .NET Framework 3.5 and the XNA Framework Redistributable 3.0 as prerequisites.
  • The file wix_sample_xgs30_game_bootstrapper_netfx20.proj is an MSBuild project file that will create a bootstrapper for a game that will install the .NET Framework 2.0 and the XNA Framework Redistributable 3.0 as prerequisites.
  • The file build_wix_sample_xgs30_game.bat has been updated to compile the MSI using WiX v3.0 and then run MSBuild for wix_sample_xgs30_game_bootstrapper_netfx35.proj to create a VS bootstrapper setup.exe package.

How to use the updated sample

To try out this updated sample, you can use the following steps:

  1. Install Visual Studio 2008 or Visual C# 2008 Express Edition and XNA Game Studio 3.0.
  2. Install the latest build of WiX v3.0 from https://wix.sourceforge.net/releases/.
  3. Open Visual Studio and create a project using the Platformer Starter Kit (3.0) project template that is included as a part of XNA Game Studio 3.0.
  4. Build the x86 release version of the project.
  5. Download the sample from https://cid-27e6a35d1a492af7.skydrive.live.com/self.aspx/Blog%7C_Tools/WiX%20Samples/wix%7C_sample%7C_xgs30%7C_game%7C_with%7C_bootstrapper.zip.
  6. Create a sub-folder named Setup in the Platformer game project that you created above.
  7. Extract the contents of wix_sample_xgs30_game_with_bootstrapper.zip to the Setup folder.  You should end up with a folder structure like c:\Users\myusername\Documents\Visual Studio 2008\Projects\Platformer1\Platformer1\Setup with the contents of the .zip file in there.
  8. Run the script named build_wix_sample_xgs30_game.bat from the Setup folder to invoke the WiX toolset and build an MSI for the game and then invoke MSBuild to build the bootstrapper setup.exe.

After doing the above, you can copy setup.exe and wix_sample_xgs30_game.msi from the Setup sub-directory to a server and run setup.exe to install your game and its prerequisites on another computer.

Advanced scenario - building an MSI with WiX by using a .wixproj file

Note - it is also possible to create an MSBuild project file to build an MSI using WiX instead of using a batch file that calls the WiX tools directly.  I have included a sample MSBuild project file named wix_sample_xgs30_game.wixproj in the new sample that I have posted.  It was created by using the Votive Visual Studio package that is a part of the WiX toolset, and it can be built by invoking msbuild.exe directly or by opening the .wixproj file in Visual Studio 2005 or 2008 standard edition or higher on a system that also has WiX v3.0 installed.  Keep in mind that Votive is a Visual Studio add-in package, so it can only be installed for use in Visual Studio standard edition or higher.  You cannot use it if you only have Visual C# 2008 Express Edition.  You can create and build .wixproj files by hand outside of Visual Studio if you only have an Express Edition installed though.

<update date="3/21/2009"> Fixed broken link to sample installer files. </update>

Comments

  • Anonymous
    November 21, 2008
    PingBack from http://blogs.msdn.com/astebner/archive/2008/10/31/9027445.aspx

  • Anonymous
    December 03, 2008
    We're back from stuffing ourselves with...well...stuffing and turkey and the like for Thanksgiving and

  • Anonymous
    December 15, 2008
    Aaron Stebner が XNA Game Studio 3.0 を用いた Windows ゲーム 用 インストーラーの作成 に関する記事 ( 英語 ) を 2 つ投稿しています。 Shawn Hargreaves

  • Anonymous
    February 02, 2009
    Hi Aaron. Great post, exactly what I need.  I've had this bookmarked for a while, and I'm finally implementing it for my game's ("Air Legends") Windows installer. I am stumped by one bizzare problem though.  I'm using Winzip Self-extractor to package the bootstrap EXE & MSI into a single downloadable install file. I have done this before with good success, but for some reason I am now having a problem I've not seen before.  After the bootstrapper finishes and launches my MSI, I am finding the Temporary extracted files are often getting removed before the MSI is complete so the install fails.   I can reliably make it fail by simply taking a few seconds before clicking through the first of the MSI setup pages. What puzzles me the most is I am using exactly the same version of Winzip Self-extractor as in a previous project which never seemed to have this problem. Has something changed about the newer versions of Wix 3 that might cause this?  e.g. for instance, would older versions have had the running MSI file locked so it didn't prematurely get deleted from Temp?

  • Anonymous
    February 03, 2009
    Hi Sharky - Thanks for the feedback on this blog post.  I'm glad to hear it has been helpful so far.  I think the behavior difference is the result of a change in the VS bootstrapper setup.exe itself (as opposed to anything in WiX).  I talked to some folks who work on the VS bootstrapper, and they indicated that there was a launching behavior change in the VS bootstrapper setup.exe introduced in VS 2008 that is intended to make it work better with UAC on Vista but that inadvertantly breaks the self-extracting EXE scenario that you're trying to implement. Overall, they didn't intend to specifically support a self-extracting EXE scenario but it happened to work up until VS 2008.  They intend for web download scenarios to use just the setup.exe and have the setup developer author their package to download all payload from the Internet.  They intend for CD or UNC file share scenarios to include the package payload in relative paths instead of packaging them into a single EXE.

  • Anonymous
    February 03, 2009
    Thanks Aaron. That would certainly explain it, though I really don't like the new behaviour. For the full version of my game I definitely don't want the MSI part of my installer available for FREE download. I had planned on putting the single-exe (self-extractor) install behind a password protected part of my blog. Only people that donate would get the password. Is it possible to have the bootstrapper download the MSI from a password protected location?

  • Anonymous
    February 04, 2009
    Hi Sharky - The bootstrapper does not support authentication-based downloads.  There are a couple of options you could explore as workarounds:

  1.  Write a lightweight .exe that is launched by the self-extracting process and that in turn will launch the VS bootstrapper setup.exe.  It can be made to monitor both the setup.exe process and the MSI that setup.exe will spawn.  You can make that lightweight .exe return only when both processes are complete.
  2.  Use VS 2005 instead of VS 2008 to create the bootstrapper setup.exe.  You would still need to use VS 2008 to create your game since it is based on XNA Game Studio 3.0, but you could follow the steps in this blog post on VS 2005 instead of 2008 and it will produce a setup.exe that does not have the behavior problem that you've been experiencing.  WiX 3.0 will work in VS 2005 or 2008, and you can create the setup.exe in the free VC# 2005 Express Edition, so you wouldn't need to buy an additional copy of VS to accomplish this. Hopefully one of these will help!

  • Anonymous
    February 07, 2009
    Thanks for the suggestions Aaron. I'm guessing the option #1 lightweight .exe could not be done in C# .NET - because if the PC running it doesn't have the framework installed it simply wouldn't work.  It's a chicken and egg situation.  ;) So I'm going to have a go with the #2 option. Do you think this is something Microsoft will address in the future, because it seems kind of ridiculous to have to go to these lengths?  There must be a huge number of installers out there that use the self-extracting+bootstrapper approach. And if they move to VS 2008 they're going to get a rude surprise when their setups fail to work. Most of us can't afford big-name installer packages like InstallShield, Wises etc... Plus I really like WiX.

  • Anonymous
    February 07, 2009
    p.s. I found some discussion and more possible workarounds here... http://social.msdn.microsoft.com/forums/en-US/winformssetup/thread/3731985c-d9cc-4403-ab7d-992a0971f686/#page:1 Interestingly, I can no longer find VS 2005 C# Express available for download on the Microsoft site. It seems to have been replaced with 2008 express. Fortunately I found the installer on my drive somewhere.  Phew.

  • Anonymous
    February 08, 2009
    Hi Sharky - You're right - you would need to write the simple EXE in C++ so that it won't depend on the .NET Framework. It looks like this self-extracting behavior bug in the VS bootstrapper will be fixed in the next version of Visual Studio.  There is a comment in the Connect bug at https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=369138 that states that it is fixed in Dev10. Also, in case you need it in the future, the download location for the VS 2005 Express Editions is located at http://www.microsoft.com/express/2005/download/default.aspx.

  • Anonymous
    February 20, 2009
    A while back, I posted a set of steps that you can use to create an MSI with WiX and combine it with

  • Anonymous
    March 22, 2009
    The comment has been removed

  • Anonymous
    March 23, 2009
    Hi Business Software Dorset - I'm glad you were able to find the sample files - sorry for the hassles with my old file server being dead. You can do items 1 and 2 directly in your MSI by using WiX.  I posted some info about how to check pixel shader and vertex shader versions at http://blogs.msdn.com/astebner/archive/2008/06/05/8576818.aspx.  Checking OS version is straightforward in an MSI, and there is information in the WiX docs for that. For items 3 and 4, you'll need a bootstrapper that will install the required prerequisites and then run your MSI afterwards.  The VS bootstrapper can do that, but you have limited flexibility in terms of what UI it can show.  If you want to use the VS bootstrapper, the information in this blog post will help you achieve that.  The file wix_sample_xgs30_game_bootstrapper_netfx35.proj includes the .NET Framework 3.5, but you can easily change that to .NET 3.5 SP1 if you want to.  Let me know if you have any trouble figuring out how to do that. If you want fancier UI than what is offered by the VS bootstrapper, then your best bet will be to write your own bootstrapper UI and have it chain .NET 3.5 SP1, XNA Framework 3.0 and then your product MSI. #6 is problematic for the VS bootstrapper.  I described that in item 1 at http://blogs.msdn.com/astebner/archive/2009/02/20/9436778.aspx.  If you want to support a self-extracting package with no web downloading of packages, you'll probably need to create a stub EXE that stays alive in the background (because the other option listed in that blog post of using the VS 2005 bootstrapper won't work for you since you want to include .NET 3.5 SP1 and the XNA Framework 3.0 redist as prerequisites and those VS bootstrapper packages are only installed for use with VS 2008's bootstrapper). Hopefully this helps.  Let me know if you have any questions as you get started with your packaging/setup work.

  • Anonymous
    April 13, 2009
    I’ve previously written a few posts about how to get started with Windows game deployment for games created

  • Anonymous
    April 22, 2009
    The comment has been removed

  • Anonymous
    April 22, 2009
    Hi Bill Packard - The setup.exe bootstrapper is generated automatically by Visual Studio, and VS doesn't offer the ability to view or modify that source code.  If you need UI or behavior that you don't get from the setup.exe bootstrapper that is generated for you by VS, you would need to write your own bootstrapper to replace the built-in one that VS generates for you.