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>
As announced today in this news item on the Creators Club site and on this post on the XNA team blog, the final version of XNA Game Studio 3.0 is now available for download. In addition, a refreshed Creators Club web site has been unveiled, including the ability to submit and peer review games for publication via Xbox LIVE Community Games in the New Xbox Experience.
Important note - if you are planning to submit an Xbox LIVE Community Game and/or participate in the peer review process, you must use XNA Game Studio 3.0 and not any previous version of XNA Game Studio.
Here are some links with information about how to download and get started using XNA Game Studio 3.0:
What is new since the XNA Game Studio 3.0 beta?
The XNA Game Studio 3.0 beta represented a feature complete milestone for the XNA Game Studio 3.0 product. This means that the main differences between the beta and the final release are bug fixes and small fit-and-finish improvements. The notable exception to this are the following:
If you previously had a pre-release version of XNA Game Studio 3.0 installed
If you previously had a pre-release version of XNA Game Studio 3.0 (the CTP or beta) installed, there are a few things you will need to keep in mind:
If you encounter XNA Game Studio 3.0 setup failures
If you run into setup failures while installing XNA Game Studio 3.0, it can help to look at the log files created by XNA Game Studio 3.0 setup. They are located at %temp%\XNA Game Studio 3.0 Setup\Logs.
The best way to get help for setup issues is to gather your log files, upload them to a file server of your choice, and then post a question on the Creators Club general forum that includes a link to your log files. When doing this, please be sure to search for related issues before posting something because your question may have already been answered.
You can also report setup issues via the Connect site - please include your log files as attachments when doing this.
<update date="10/31/2008"> Added link to a forum post about issues with .ccgame files created in the XNA Game Studio 3.0 CTP or beta. </update>
As a part of PDC 2008, a community technology preview of Visual Studio 2010 and the .NET Framework 4.0 has been released for you to download and try out. It is available via a Virtual PC image that can be downloaded from this location.
As Rob Mensching noted a while back in this blog post, Visual Studio will be shipping a build of WiX 3.0. This CTP of VS 2010 includes the 3.0.4325 build of the WiX toolset and the Votive Visual Studio package. The WiX toolset is installed to the %ProgramFiles%\Visual Studio 2010 Windows Installer XML Toolkit CTP folder in the Virtual PC image. Bob Arnson posted some more specific details in this blog post about which WiX extensions are and are not included in the VS 2010 CTP.
Some folks on the Visual Studio team are working with the WiX developers to fix bugs in the WiX core toolset and get a version of WiX and Votive ready to ship with Visual Studio 2010. They have created a feedback forum titled Building and Deploying Applications where you can provide feedback specifically about the WiX development experience in the VS 2010 CTP. Candy Chiang, the program manager working on WiX integration, has posted an introductory item here.
To summarize the above information, here is a collection of some useful links for the VS 2010 and .NET Framework 4.0 CTP and the WiX development features it includes:
There has been some early information about Windows 7 presented at PDC 2008 this week. Of particular interest to me as a former member of the Media Center team is some detailed information about upcoming Windows 7 Media Center features. Here are a couple of links to some information that Charlie Owen posted on his blog about Media Center end-user features and developer/platform features:
If you're interested in Media Center and/or Media Center development and want to get an early preview of what is planned for Windows 7, I encourage you to check out the information in these posts.
A couple of weeks ago, a Best Practices for Community Games guide was published on the Creators Club web site that provides a list of suggestions to consider when creating Xbox LIVE Community Games using XNA Game Studio 3.0. You can find this guide at http://creators.xna.com/en-us/education/bestpractices. You are not required to follow these guidelines when creating your game, but following these guidelines will add polish to your game that will hopefully make it appeal to more users, increase your sales via Xbox LIVE Community Games, etc.
This best practices guide currently includes information about the topics listed below. It describes things to consider when designing and building your game, and also has links to relevant samples and documentation topics to provide more details and code snippets to help you get started:
In addition, Mitch Walker has posted an item on his blog that provides more details about one of the bullet points in the Seamless loading and saving section of the best practices guide. In his blog post at http://blogs.msdn.com/mitchw/archive/2008/10/15/the-one-about-storage.aspx, he demonstrates how to implement the Guide.BeginShowStorageDeviceSelector API in an asynchronous manner so that your game will not deadlock on systems that have multiple storage devices attached (such as a hard drive and a memory unit).
Last week, I posted some high-level details about a couple of new Visual Studio features that are available in XNA Game Studio 3.0 - cross-platform synchronization and multiple content projects. Over this past weekend, Stephen Styrchak posted an entry on his blog with much more detailed information about how cross-platform development works in XNA Game Studio 3.0, as well as some tips and tricks to more effectively use Visual Studio 2008 and XNA Game Studio 3.0 for cross-platform game development.
His blog post is at http://badcorporatelogo.spaces.live.com/Blog/cns!43EB71B104A2D711!343.entry, and it contains the following types of information:
I encourage you to check out Stephen's blog post for more details about all of the above - this post is a great reference if you are planning to use the cross-platform development features in XNA Game Studio 3.0.
I have an application that installs some .config files that users can customize. I want to implement a Windows Installer major upgrade to install new versions of my application on systems that have an older version installed. During the upgrade, I want to keep any customizations that users have made to the .config files instead of replacing them with new versions of the files.
How do I configure a major upgrade so that customized .config files will not be replaced during the upgrade process?
The first thing to keep in mind is that a Windows Installer major upgrade is simply an install operation and an uninstall operation combined into a single installation session. Whether or not .config files get replaced depends on how you author the information in your MSI.
There are a couple of key things you need to do to enable this behavior:
1. Place each .config file in its own component and mark the .config file as the key path of the component.
Doing this will ensure that Windows Installer will use unversioned file replacement logic when deciding whether or not to replace this file in the install of your new version. The high-level summary is that Windows Installer will compare the creation time of the component's key path file with the last modified time if both the old and new versions of the file are unversioned. If they differ, then Windows Installer assumes the user has modified it and it will not replace it.
2. Schedule the RemoveExistingProducts action in the new version of your MSI after the InstallFiles action.
Doing this will make sure that the new versions of all of your components are installed before removing the old version of your MSI. When the new versions are installed in this sequence, your components will have their reference counts incremented to 2, but the .config files will not be replaced unless they are unmodified (because of the unversioned file replacement logic described in item 1 above). Then, when the old version of your MSI is uninstalled afterwards during the RemoveExistingProducts action, the reference counts will be decremented back to 1, but the files will not be removed the system because the reference counts are not yet 0. If you schedule RemoveExistingProducts before InstallFiles, then the uninstall of your old version will cause the component reference counts to reach 0, and the files will be removed from disk. When the new versions of your components are installed afterwards, the files will be replaced with the new versions. This will cause your users to lose any customizations they have made to their .config files. The .NET Framework 2.0 SP1 and SP2 are implemented as major upgrades of the original version of the .NET Framework 2.0. It has the same requirement of keeping any customizations the user has made to .config files. The .NET Framework 2.0 SP1 and SP2 installer schedules RemoveExistingProducts in the following specific order because otherwise, it would encounter an ICE63 warning:
There was an announcement on the XNA team blog earlier this week about a couple of upcoming release dates, and I wanted to mention them here as well:
Xbox LIVE Community Games will require games that are created with XNA Game Studio 3.0, so make sure to download the final release when it is available on October 30th to get your game ready to submit for peer review and publishing. Keep in mind that you can start with an XNA Game Studio 2.0 project for Xbox 360 and upgrade it to 3.0 after it releases. Check out this blog post for more information about XNA Game Studio project upgrade scenarios.
A couple of new cumulative update package for Windows Media Center have been released this week.
The first is an update for Windows Vista Media Center that is called the October 2008 Cumulative Update for Media Center for Windows Vista and is also known as KB955519. It is available for download in x86 and x64 versions. It can be installed on systems running the original version of Windows Vista Home Premium or Ultimate Editions and the SP1 version of Windows Vista Home Premium or Ultimate Editions. This update includes all fixes previously included in the June 2008 Cumulative Update and some additional fixes described in the knowledge base article linked below. Notably, this update fixes a regression introduced in the June 2008 update that caused playback to resume if it was paused and then the screen saver started.
The second is an update that is called the Cumulative Update for Media Center TV Pack for Windows Vista and is also known as KB956147. It is available for download in x86 and x64 versions. It can only be installed on systems that include the Media Center TV Pack for Windows Vista.
Here are some links for the October 2008 Cumulative Update for Media Center for Windows Vista:
Here are some links for the Cumulative Update for Media Center TV Pack for Windows Vista:
Right after the .NET Framework 3.5 SP1 shipped, I updated the .NET Framework cleanup tool and the .NET Framework setup verification tool to support the .NET Framework 2.0 SP2, the .NET Framework 3.0 SP2 and the .NET Framework 3.5 SP1.
I updated both of these tools on my file servers back then, but didn't announce the updates via posts on my blog. However, I've gotten several questions about support for the components of the .NET Framework 3.5 SP1 in these tools since then, so I decided that I should post something to give folks a heads up.
Here are links to more information about each of these tools:
Visual Studio 2008 SP1 shipped with a bootstrapper package for the .NET Framework 3.5 SP1. This bootstrapper package can be used with ClickOnce and setup/deployment projects to install the .NET Framework 3.5 SP1 as a prerequisite before installing your application.
This past week, new VS 2008 bootstrapper packages were released for the .NET Framework 2.0 SP2 and the .NET Framework 3.0 SP2. The 2.0 SP2 and 3.0 SP2 versions of the .NET Framework are installed as prerequisites during .NET Framework 3.5 SP1 setup, but they were not previously available as standalone bootstrapper packages.
Here are some links for the .NET Framework 2.0 SP2 and 3.0 SP2 bootstrapper packages for VS 2008:
There are a few caveats to keep in mind when using the .NET Framework 2.0 SP2 and 3.0 SP2 bootstrapper packages:
There are a couple of new features that have been added in the XNA Game Studio 3.0 beta that are intended to improve the development experience in Visual Studio that I want to briefly introduce. If you have a chance, I encourage you to download the XNA Game Studio 3.0 beta and give it a try. Please let us know if you find any bugs or have any feedback about the features described below or any of the other features in the product by using the Connect site.
Multiple Content Projects
In XNA Game Studio 2.0, the concept of a content project was introduced. However, each game project was limited to a single content project, which meant that sharing content between games required some additional work (such as creating a game library and including that library in each game project that you wanted to use the shared content in).
In XNA Game Studio 3.0, it is now possible to add and remove content projects directly within a game project. This allows you to include multiple content projects into your game project. You can do all of the following:
There are several possible uses for this feature. Here are a couple of examples:
XNA Game Studio has a feature that allows you to create a game project for one platform (Windows, Xbox 360 or Zune) and then create a copy of that project for one of the other supported platforms. Behind the scenes, a new .csproj file is created to represent the game for the new platform, and the appropriate changes are made to the .csproj file so references, pre-processor definitions, etc will be configured correctly for the new platform.
When you create a copy of a project for another platform, it will automatically be populated with the same code and content that existed in the original project at the time the copy was made. However, in previous versions of XNA Game Studio, any future additions, removals or renames to items in one of the projects would cause it to get out of sync with the other project. Stephen Styrchak posted some information a while ago on his blog about an add-in he wrote to automatically synchronize cross-platform projects in XNA Game Studio 2.0.
Starting in the XNA Game Studio 3.0 beta, we have included built-in support for cross-platform synchronization that is similar to Stephen's add-in. After creating a game project and then creating one or more cross-platform copies, XNA Game Studio 3.0 will automatically synchronize item additions and renames that occur in any of the projects in the cross-platform group.
It is important to note here that XNA Game Studio 3.0 will only synchronize projects that are in the same solution and are part of a "cross-platform group." This means that the projects have to have been added to the solution by creating copies of an existing game project as opposed to by using the Add New Project or Add Existing Project options in Visual Studio. You can tell whether or not 2 .csproj files are a part of the same cross-platform group by looking at the metadata in the project files. Every XNA Game Studio project should have a property named <XnaCrossPlatformGroupID> that is set to a GUID value. Projects that are a part of the same cross-platform group will have identical <XnaCrossPlatformGroupID> values in their .csproj files.
My colleague Michael Klucher posted some screenshots and details on his blog about the new version of XNA Game Studio Connect that will be released along with the final release of XNA Game Studio 3.0. You can find Michael's blog post at http://klucher.com/blog/the-new-xna-game-studio-connect/.
There is some important information in his post for current XNA Creators Club members who are using XNA Game Studio 2.0 to deploy games to their Xbox 360s. The upcoming updated version of XNA Game Studio Connect will replace the 2.0 version of XNA Game Studio Connect, and you will use it to deploy games created with both XNA Game Studio 2.0 and XNA Game Studio 3.0.
Unfortunately, there are some manual steps you will have to take if you already have the 2.0 version of XNA Game Studio Connect in order to download and use the new 3.0 version. At a high level, you will need to do the following (note - there is a more detailed set of steps to accomplish these tasks in Michael's blog post):
Once the 3.0 version of XNA Game Studio Connect is released, the 2.0 version will be updated to display a single screen that contains a set of instructions similar to the ones on Michael's blog so that you will know that you need to update it in order to continue deploying games to your Xbox 360. In addition, the 2.0 version will no longer be available on the Xbox LIVE Marketplace once the 3.0 version is released, so there will hopefully not be any confusion about what you need to download.