Thoughts about setup and deployment issues, WiX, XNA, the .NET Framework and Visual Studio
All postings are provided AS IS
with no warranties, and confer no rights. Additionally, views expressed
herein are my own and not those of my employer, Microsoft.
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:
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:
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:
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:
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:
ClickOnce publishing output
The above steps will produce a publishing output folder that contains the following:
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:
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:
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:
After a build, your setup project's output directory will contain the following by default:
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.
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.
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>
PingBack from http://blogs.msdn.com/astebner/archive/2008/09/18/8957968.aspx
Thanks for pointing me to the correct writeup! Clear as a bell,
If you are using ClickOnce to deploy a Windows game created with XNA Game Studio 3.0, you might run into
Any thoughts on using obfuscation with ClickOnce when distributing and XNA GS3.0 application for windows? Are we still condemned to Mage and MageUI? Would you recommend just not using ClickOnce given the added hurdles of having to manually build the deployment packages? And if so what is the best alternative solution?
Hi Dorchester_software - XNA Game Studio 3.0 does not provide any type of unique obfuscation solution, so if you are using ClickOnce to deploy your Windows game, your options for obfuscation are the same as they are for any other application that you build and deploy using ClickOnce. There isn't a blanket recommendation that I can make here because all scenarios have their own unique requirements and developers have their own unique set of deployment knowledge, tools and processes.
If you plan to use ClickOnce with obfuscation, I'd suggest referring to the following links for additional information:
Deploying Obfuscated Assemblies - http://msdn.microsoft.com/library/76e4d2xw.aspx
Building ClickOnce Applications from the Command Line - http://msdn.microsoft.com/library/ms165431.aspx
If you prefer to not use ClickOnce, then I'd suggest creating an MSI-based installer. There are a lot of tools available to do this, but I always use WiX v3.0 (http://wix.sourceforge.net) so I'd encourage you to take a look at that toolset for this purpose.
PingBack from http://www.igrophile.com/introduction-to-windows-game-deployment-features-in-xna-game/
Great article! Cleared up a lot of things for me.
When I installed a ClickOnce publish named spacewar on another machine the game did not work, until I moved the settings.xml from the spacewar...exe directory to the spacewar..tion directory.
The project is the spacewar 2.0 base project upgraded to 3.0. Anyone have an idea what might be going on?
Hi Holon777 - ClickOnce treats .xml files as data files by default and installs them to a special data file folder when deploying an application. There is a section in one of the XNA Game Studio 3.0 documentation topics that explains how to handle this.
You can find the topic at XNA Game Studio 3.0 | Using XNA Game Studio | Sharing and Distributing Your Game | Distributing Your Finished Windows Game in your XNA Game Studio 3.0 documentation table of contents. The section you'll want to look at in that topic is titled Special Consideration for Game Data Files.
Also, in the updated 3.0 version of the Spacewar starter kit that is available at http://creators.xna.com/en-US/starterkit/spacewar, we have fixed this deployment issue related to settings.xml.
I previously wrote an introductory post describing Windows game deployment features that are a part of
Thanks Aaron, I followed the instructions and my installs are working!
Aaron Stebner's WebLog : Introduction to Windows game deployment features in XNA Game Studio 3.0
A few days ago, I wrote a blog post describing how to create an MSI-based installer for a Windows game
Since we released XNA Game Studio 3.0 , I've heard of a few problems from customers via my blog and the
I’ve previously written a few posts about how to get started with Windows game deployment for games created
Why doesn't my content get included with ClickOnce? The installer can't find my only .png file.