Introduction to Windows game deployment features in XNA Game Studio 3.0 and 3.1

Article
10/31/2008

Note - I originally wrote this post when we released XNA Game Studio 3.0, but the content of this post applies to XNA Game Studio 3.1 as well.

When the XNA Game Studio 3.0 beta was released a couple of months ago, I wrote a blog post describing the new Windows game deployment features that were added for the beta. Since then, we have released the final version of XNA Game Studio 3.0. We made some subtle changes to the Windows deployment features that were introduced in the beta, so instead of updating that older beta blog post, I decided to post a new version of it with updated information that applies to the final release of XNA Game Studio 3.0.

There is also some information about Windows deployment in the XNA Game Studio 3.0 documentation. This blog post is intended to supplement, not replace, that documentation, so there are some topics I do not cover here because they are already in the documentation. The best place to get started in the documentation is the Distributing Your Finished Windows Game topic.

Prerequisites for XNA Framework 3.0-based Windows games

Windows games created with XNA Game Studio 3.0 require the following components to be installed in order to run correctly on a system that does not have XNA Game Studio 3.0 installed:

The .NET Framework 2.0 or the .NET Framework 3.5 (depending on what version of the .NET Framework you choose to target when creating your game). The service pack level for the .NET Framework does not matter, so you could also install the .NET Framework 2.0 SP1, 2.0 SP2 or 3.5 SP1 as a prerequisite for your game if you choose to.
The XNA Framework Redistributable 3.0
Your game binaries and content

Deploying XNA Framework 3.0-based Windows games to other computers

In order to deploy your game to other Windows computers, you need to do one of the following:

Ensure that the target computer has all of the necessary prerequisites listed above by asking the end user to install them, then deliver the game as a .zip file or some other file format. Typically, you will need to package the contents of your \bin\x86\release\ directory and deliver those files to your users.

Note: XNA Game Studio allows you to create a .ccgame file that is a compressed cab file with some specific metadata embedded in it. However, the user must have XNA Game Studio installed on their system (and therefore, must also have a Visual Studio product installed since that is a prerequisite for XNA Game Studio) in order to unpack a .ccgame file. That usually makes the .ccgame file format less than ideal for game redistribution scenarios - it is typically more useful for developer sharing.
Create an installer that will install the prerequisites if needed and then install the game payload. Typically, the installer will be a Windows Installer .msi file and a bootstrapper .exe that will check the user's system state and install any of the prerequisites that are not yet present on the system.

There are a lot of options available for creating a game installer. Visual Studio 2008 and Visual C# 2008 Express Edition have built-in support for creating ClickOnce installer packages, and Visual Studio 2008 Professional contains a setup/deployment project type that can be used to create MSI-based installers. There are also other tools that can be used to create installers - I use WiX when creating my installers for example.

Changes made in XNA Game Studio 3.0 for Windows deployment scenarios

In previous releases of XNA Game Studio, deploying Windows games has been a confusing and error-prone process. This was partly due to not integrating well with Visual Studio deployment features, and partly due to requiring a relatively long list of prerequisites in order for a game to run correctly on a system that didn't have XNA Game Studio installed.

We have improved the deployment process in XNA Game Studio 3.0 by doing the following:

Including the DirectX 9.0c 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.
Including the Visual C++ 2005 SP1 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.
Updating the build steps for Windows game projects so they will properly include nested content project output in the ClickOnce publishing output for a Windows game.
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.
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.

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:

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

As mentioned above, the issues that used to make ClickOnce deployment a complicated process for XNA Framework-based Windows games has been greatly improved in XNA Game Studio 3.0.

How to publish an XNA Game Studio 3.0 Windows game using ClickOnce

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:

Open Visual C# 2008 Express or Visual Studio 2008.
Create a new XNA Game Studio 3.0 Windows game project.
Click on the Build menu and choose Publish <game> (or right-click on your Windows game project in the Visual Studio Solution Explorer and choose Publish... ) - this will launch the Visual Studio Publish Wizard.
Specify the publishing output location.
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.
Choose whether or not you want to enable automatic updates for your game.
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

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. This means that setup.exe will detect whether or not the user's system needs the .NET Framework 3.5 and/or the XNA Framework Redistributable 3.0, and it will download and install one or both of them if they are missing.

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:

Right-click on your Windows game project in the Visual Studio Solution Explorer and choose Properties.
In the property pages, select the Publish tab.
Use the Application Files... button to exclude files in your game project from your publishing output.
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).

The Download prerequisites from the same location as my application option in the Prerequisites dialog will cause your build output to include not only your game binaries and content, but also the installer packages for your prerequisites. This is useful when creating offline installers that do not require Internet access in order to install correctly.
Use the Updates... button to enable automatic update checking and configure the update details.
Use the Options... button to configure other advanced ClickOnce options.
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.
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 they choose to.
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 it 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 .NET Framework and the XNA Framework Redistributable 3.0 as prerequisites.

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:

Open Visual Studio 2008 Professional or higher (setup/deployment projects are not available in the Standard or Express Editions).
Create a new XNA Game Studio 3.0 Windows game project.
Right-click on the solution in the Visual Studio Solution Explorer and choose Add | New Project...
Go to Other Project Types | Setup and Deployment and add a Setup Project.
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.
Right-click on your setup project in the Solution Explorer and choose Properties.
Change the Configuration drop down if you want the changes to affect both debug and release builds.
Click on the Prerequisites... button to bring up the Prerequisites selection dialog.
Scroll to the bottom and check the item named Microsoft XNA Framework Redistributable 3.0, then click OK.
Build your solution.

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

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

Limitations in Windows game redistribution scenarios in XNA Game Studio 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.

Note: If you use XNA Game Studio content pipeline extension projects in your games, make sure that you only reference them from your content projects and not from your game project. If you reference a content pipeline extension project from a game project, that will cause the content pipeline to be required at runtime for your game (and not just at build time), and your game will not work if you deploy it using ClickOnce or a setup/deployment project because the XNA Framework Redistributable 3.0 does not include content pipeline binaries.

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.

Advanced scenarios

I have written a few supplemental blog posts about the following more advanced Windows game deployment topics:

If you have any suggestions for additional topics, please let me know.

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 XNA Game Studio 3.0 will end up being useful in making this process simpler and less error prone. If you are creating Windows games using XNA Game Studio 3.0, I encourage you to try out the deployment features 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="11/16/2008"> Added information about the XNA Game Studio 3.0 documentation topic about Windows game deployment. </update>

<update date="11/18/2008"> Added a link to the online documentation for XNA Game Studio 3.0 now that it has been published. </update>

<update date="11/21/2008"> Added links to additional blog posts about advanced deployment scenarios that I have written since this post was initially published. </update>

<update date="4/14/2009"> Added a link to a new post I wrote about integrating with Windows Game Explorer . </update>

<update date="8/24/2009"> Added a note about XNA Game Studio 3.1. </update>

Introduction to Windows game deployment features in XNA Game Studio 3.0 and 3.1

Additional resources