ClickOnce publishing integration and improved Windows game deployment in XNA Game Studio 3.0

  • Article

Important note: The information in this blog post is specific to the XNA Game Studio 3.0 beta. There have been some changes in the final release of XNA Game Studio 3.0. For more information about Windows game publishing using the final release of XNA Game Studio 3.0, please refer to the updated blog post at https://blogs.msdn.com/astebner/archive/2008/10/31/9027445.aspx .  

As previously noted, the XNA Game Studio 3.0 beta has been released.  One of the features that we added in the beta is ClickOnce publishing support for XNA Framework-based Windows games.  I wanted to go over the behind-the-scenes details for this feature and explain how to configure and use it in a Windows game.

What is ClickOnce and why hasn't it worked in the past for games?

ClickOnce is an application deployment technology that can be used to publish applications to Web servers or network file shares for simplified installation scenarios.  ClickOnce features have been available in Visual Studio for a couple of versions, but have not worked well with XNA Game Studio for a couple of reasons:

  1. In XNA Game Studio 2.0, the output of nested content projects was not included in the ClickOnce publishing output when publishing in Visual Studio.  There are some advanced steps that can be used to work around this, but they require in-depth ClickOnce knowledge and also require running publishing tools outside of Visual Studio (such as mage.exe and mageui.exe).
  2. Prerequisites needed to run XNA Framework-based games on computers that do not have XNA Game Studio installed have not been integrated into the Visual Studio publishing process in the past, and the requirements for manually creating installers have been poorly (or worse - inaccurately) documented.

Changes made in the XNA Game Studio 3.0 beta for ClickOnce scenarios

We have addressed the above issues in the XNA Game Studio 3.0 beta by doing the following:

  1. Updating our build steps to properly include nested content project output in the ClickOnce publishing output for a Windows game.
  2. Creating a Visual Studio bootstrapper package for the XNA Framework Redistributable 3.0 that can be included as a prerequisite for ClickOnce-based installers and/or Windows Installer-based installers.
  3. Configuring XNA Game Studio 3.0 Windows game projects to have a dependency on the XNA Framework Redistributable 3.0 bootstrapper package so that this prerequisite will be included by default when publishing Windows games using ClickOnce.
  4. Moving the DirectX runtime files required for XNA Framework-based games into the XNA Framework redistributable so they do not need to be installed as a separate step anymore.

How to publish an XNA Game Studio 3.0 Windows game

There are a couple of ways to access publishing functionality in Visual C# 2008 Express Edition or Visual Studio 2008.  The following steps will allow you to publish using the default settings for prerequisite packages:

  1. Open Visual C# 2008 Express or Visual Studio 2008.
  2. Create a new XNA Game Studio 3.0 Windows game project.
  3. Click on the Build menu and choose Publish <game> - this will launch the Visual Studio Publish Wizard.
  4. Specify the publishing output location.
  5. Choose the installation mechanism to offer to your users - install from the Web, install from a UNC path or file share, or install from a CD/DVD.
  6. Choose whether or not to enable automatic updates for your game.
  7. Click Finish to publish (which will trigger a build automatically if your build output is out of date).

ClickOnce publishing output

The above steps will produce a publishing output folder that contains the following:

  • setup.exe - this is the setup executable for your game, and it contains logic to install prerequisites and then trigger ClickOnce to deploy your game payload
  • <game>.application - this is the ClickOnce deployment manifest for your game
  • Application Files folder that contains your game payload
  • xnafxredist30 folder that contains the XNA Framework Redistributable 3.0 MSI

The above steps will automatically configure your game to include the .NET Framework 3.5 and the XNA Framework Redistributable 3.0 as prerequisites.  It will use the default deployment settings for each of these prerequisites.  For the .NET Framework 3.5, this means that setup.exe will detect whether or not the user's system needs the .NET Framework 3.5 and will download and install it if it is missing.  For the XNA Framework Redistributable 3.0, it will deliver the MSI as payload in a sub-folder next to setup.exe (in the beta only).

In the XNA Game Studio 3.0 beta, you will notice that publishing a Windows game will result in a warning in the error list that states the following:

No 'HomeSite' attribute has been provided for 'Microsoft XNA Framework Redistributable 3.0', so the package will be published to the same location as the bootstrapper.

We did not specify a HomeSite value in the beta because we did not post the XNA Framework Redistributable 3.0 MSI as a separate download.  In the final release of XNA Game Studio 3.0, we will post the XNA Framework Redistributable 3.0 MSI as a separate download, and we will update this bootstrapper package to specify a valid HomeSite value.  That will cause the default publishing behavior to be to cause setup.exe to detect whether or not the user's system needs the XNA Framework Redistributable 3.0 and to download and install it if it is missing (like the default behavior for the .NET Framework 3.5).

How to configure non-default ClickOnce publishing options

In order to change the default publishing behavior for XNA Game Studio 3.0 Windows game, you can use the following steps:

  1. Right-click on your Windows game project in the Visual Studio Solution Explorer and choose Properties.
  2. In the property pages, select the Publish tab.
  3. Use the Application Files... button to exclude payload from your publishing output.
  4. Use the Prerequisites... button to add/remove prerequisite packages or to change how they are packaged (download from the manufacturer's web site, download from the same location as the application, package in a directory along with the game).
  5. Use the Updates... button to enable automatic update checking and configure the update details.
  6. Use the Options... button to configure other advanced ClickOnce options.
  7. Use the Publish Wizard... button to invoke the publishing wizard (the same one that appears if you click on the Build menu and choose Publish <game> in the previous set of steps.
  8. Use the Publish Now button to publish using the default publishing settings without stepping through the wizard.

Notes about installing Windows games using ClickOnce

After publishing your game, you can install it on another system by running setup.exe or by running <game>.application (if the target system already has the .NET Framework 2.0 or higher, it will know how to handle the .application file extension).  Any missing prerequisites will be installed, and then your game will be deployed.  Here are a few key notes about this deployment process:

  • ClickOnce applications are deployed as per-user application to a randomly-generated folder under the currently logged in user's %LOCALAPPDATA% folder.  This folder is chosen automatically by ClickOnce, and you do not have any control over this location in the publishing process.
  • ClickOnce will create a Start menu shortcut for your game.
  • ClickOnce will create an Add/Remove Programs entry so that the user can uninstall the game later.
  • If you choose to include automatic updates for your game, ClickOnce will check for new versions of your game each time the user launches it, and will deploy new versions if they are available.

Using a setup/deployment project to create a game installer

Visual Studio Professional Edition and higher offers the ability to create MSI-based installers in addition to ClickOnce packages.  Both of these deployment solutions use the same bootstrapper packages for installing prerequisites.  This means you can also use a setup/deployment project in Visual Studio 2008 Professional Edition and higher to create an MSI to install your game, and then include the XNA Framework Redistributable 3.0 as a prerequisite.

It is important to note that XNA Game Studio 3.0 does not support automatically adding game or content project output to the setup project (which is normally done by right-clicking the setup project, choosing Add | Project output... and selecting the primary output of the desired project in the Add Project Output Group dialog).  As a result, you will have to manually add the binary files and content files that you want to install as a part of your game to your setup project one-by-one if you choose this option.

Here are steps that you can use to accomplish this:

  1. Open Visual Studio 2008 Professional or higher (setup/deployment projects are not available in the Standard or Express Editions).
  2. Create a new XNA Game Studio 3.0 Windows game project.
  3. Right-click on the solution in the Visual Studio Solution Explorer and choose Add | New Project...
  4. Go to Other Project Types | Setup and Deployment and add a Setup Project.
  5. Use the File System designer to populate the project with the payload of your game (content plus game binaries).  To do this, right-click on your setup project and choose View | File System.  Then create folders and add files in the desired locations.
  6. Right-click on your setup project in the Solution Explorer and choose Properties.
  7. Change the configuration drop down if you want the changes to affect both debug and release builds.
  8. Click on the Prerequisites... button to bring up the Prerequisites selection dialog.
  9. Scroll to the bottom and check the item named Microsoft XNA Framework Redistributable 3.0, then click OK.
  10. Build your solution.

After a build, your setup project's output directory will contain the following:

  • setup.exe - this is the setup executable for your game, and it contains logic to install prerequisites and then trigger the installation of your MSI
  • <game>.msi - this is the Windows Installer MSI file that contains your game payload
  • xnafxredist30 folder that contains the XNA Framework Redistributable 3.0 MSI

In the XNA Game Studio 3.0 beta, you will see the same warning about the HomeSite attribute as described above in the ClickOnce publishing steps.  This is because the same underlying bootstrapper package is used by ClickOnce and setup/deployment projects.  In the final release of XNA Game Studio 3.0, it will be possible to enable download-and-install-on-demand scenarios for the XNA Framework Redistributable 3.0.

Important note about the contents of the XNA Framework Redistributable 3.0

The above information describes how to create an installer for an XNA Framework-based Windows game.  There are a couple of key scenarios that are not currently possible when deploying a Windows game to a system in this way because the necessary functionality is only installed by XNA Game Studio, not by the XNA Framework Redistributable:

  • The Microsoft Games for Windows - LIVE Redistributable package is installed during XNA Game Studio setup, but it is not available for redistribution as a part of a game installer.  A Windows game that attempts to use networking functionality provided by this package on a system without XNA Game Studio installed will encounter a GamerServicesNotAvailableException.
  • The Content Pipeline Build Runtime is installed during XNA Game Studio setup, but it is not included in the XNA Framework Redistributable.  Building content at run time (which could be used for things like level editors and game modding engines) is only supported when XNA Game Studio has been installed on the Windows-based development computer.

Behind the scenes details if you are interested

If you are interested in more details, you can see the data files for the XNA Framework Redistributable 3.0 bootstrapper package by looking at the folder %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages\XnaFxRedist30 on a system with XNA Game Studio 3.0 installed.  We created this bootstrapper package by using the steps in this MSDN document about creating custom bootstrapper packages.

Summary

Windows game packaging and deployment have been consistent pain points since the first version of XNA Game Studio Express.  Hopefully the features that we've added in the XNA Game Studio 3.0 beta will end up being useful in making this process simpler and less error prone.  If you are creating Windows games using XNA Game Studio, I encourage you to try out these features in the 3.0 beta and let us know if you run into any troubles using these features and/or have any suggestions for further improvements by posting on the forums and/or reporting bugs on the Connect site.

<update date="9/30/2008"> Clarified that adding project output from a game project or a content project into a setup/deployment project will not work in XNA Game Studio 3.0. Instead, if you plan to use a setup/deployment project, you have to manually add the game binaries and content files to the setu project one-by-one. </update>

<update date="10/20/2008"> Added a note about networking and content building scenarios that are supported on systems that have XNA Game Studio installed, but not on systems that only have the XNA Framework Redistributable installed. </update>

<update date="11/3/2008"> Added a caveat that this information is only applicable in the XNA Game Studio 3.0 beta, and added a link to the updated blog post that I wrote about Windows game deployment in the final release of XNA Game Studio 3.0. </update>