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.
There are a several prerequisite dependencies that must be satisfied on a Windows system that does not have the XNA Game Studio 2.0 development tools installed in order to be able to play games built on the XNA Framework 2.0. Most of them are documented in the Distributing Your Finished Game topic in the XNA Game Studio 2.0 documentation, but there is an additional dependency not listed there that is documented in item 1.5.2 in the readme at http://creators.xna.com/gamestudio2/gamestudio2readme.htm. I wanted to summarize the dependencies that must be installed on a Windows system before you will be able to play games created with XNA Game Studio 2.0 so they can all be found in one place, and also provide some more specific information about how to detect the presence of these prerequisites on a user's system.
In order to play a game created with XNA Game Studio 2.0, a system needs to have the following components installed:
1. The .NET Framework 2.0
The .NET Framework 2.0 is available as a part of the OS on Windows Vista, and is also available as a redistributable package for pre-Vista operating systems. Either the original .NET Framework 2.0 release (http://go.microsoft.com/fwlink/?LinkID=76064) or the .NET Framework 2.0 SP1 (http://www.microsoft.com/downloads/details.aspx?FamilyId=79BC3B77-E02C-4AD3-AACF-A7633F706BA5) will work to fulfill this requirement.
The officially documented way to detect the presence of the .NET Framework 2.0 on a system is the following registry value:
[HKEY_LOCAL_MACHINE\Software\Microsoft\NET Framework Setup\NDP\v2.0\50727]Install=1
I have posted some sample code that can be used to implement this type of detection logic in an application setup.
2. The XNA Framework Redistributable 2.0
The XNA Framework redistributable 2.0 MSI can be downloaded from http://go.microsoft.com/fwlink/?LinkID=78244.
The Distributing Your Finished Game topic describes how to use the MsiQueryProductState API and pass in the value {245F6C7A-0C22-4DE0-8202-2AAA620A1D3A} (which is the XNA Framework redistributable 2.0 MSI product code) to detect the installation state of the XNA Framework redistributable 2.0. This algorithm requires writing code, and it cannot be implemented using standard Windows Installer actions. As an alternative, you can add rows to the Windows Installer AppSearch and RegLocator tables to check for the existence of the following registry value to determine whether or not the XNA Framework redistributable 2.0 is installed:
[HKEY_LOCAL_MACHINE\Software\Microsoft\XNA\Framework\v2.0]NativeLibraryPath
You can use the following WiX v3.0 syntax to set a property named XNAFX20_INSTALLED that can then be checked within an MSI-based setup to determine the XNA Framework redistributable 2.0 install state:
<Property Id="XNAFX20_INSTALLED" Secure="yes"> <RegistrySearch Id="XnaFx20InstallRegKey" Root="HKLM" Key="SOFTWARE\Microsoft\XNA\Framework\v2.0" Name="NativeLibraryPath" Type="raw" /> </Property>
3. The Visual C++ 2005 SP1 redistributable package
The Visual C++ 2005 SP1 redistributable package can be downloaded from http://go.microsoft.com/fwlink/?LinkId=106163. XNA Framework-based games technically only require the Microsoft_VC80_CRT runtime files (msvcr80.dll), but this redistributable package also includes VC runtime files for ATL, MFC and other VC components. The .NET Framework 2.0 SP1 includes the necessary Microsoft_VC80_CRT runtime files. The .NET Framework 2.0 SP1 can be installed as a redistributable package on Windows XP and Windows Server 2003, and it is included in Windows Vista SP1. However, the only way to install the .NET Framework 2.0 SP1 on the original release of Windows Vista is to install the .NET Framework 3.5.
Visual Studio 2005 SP1 standard and higher editions include merge modules that can be used to include the Visual C++ 2005 SP1 runtime files in an MSI-based setup in order to minimize the setup footprint. The merge modules are located at %ProgramFiles%\Common Files\Merge Modules on a system that has Visual Studio 2005 installed. Sample instructions for merging these modules into an MSI-based setup using the WiX toolset can be found in this blog post.
XNA Framework-based games need to include the Microsoft_VC80_CRT merge modules for the appropriate processor architectures (x86, x64 or ia64), and when doing so, you will need to ensure that you are consuming merge modules from a system that has Visual Studio 2005 standard edition or higher and VS 2005 SP1 installed. If you do not use the SP1 version of these merge modules or redistributable page, you will encounter errors related to side-by-side activation when trying to run your XNA Framework 2.0-based game.
If you use the redistributable package, you can use the information in this blog post to detect whether or not the package is already installed on the system and skip installing it if so. If you include the merge modules in your MSI, Windows Installer will handle detection and installation of the files for you behind the scenes.
4. DirectX 9.0c
Technically, only a subset of the DirectX 9.0c runtime redistributable package is needed for XNA Framework-based games (see the list at http://msdn2.microsoft.com/library/bb464156.aspx for specific components that are required). The DirectX 9.0c redistributable can be installed by using the web installer at http://go.microsoft.com/fwlink/?LinkID=56513. For scenarios that cannot rely on an active Internet connection during setup, you can download the DirectX SDK and select the necessary redistributable components from the Redist folder that is installed as a part of the SDK. For more information about redistributing DirectX 9.0c, you can refer to the DirectX Installation for Game Developers article on MSDN.
The general guidance in the DirextX Installation for Game Developers article is to always run DirectX 9.0c runtime setup as opposed to trying to determine whether or not to run it based on a setup-time inventory of the the user's system state.
Additional information
There are several topics on the XNA forums that discuss XNA-based game distribution on Windows. I encourage you to check them out as well:
A while back, I posted a list of instructions that can be used to enable Windows Installer verbose logging in order to troubleshoot MSI-based setup issues. Since then, some people have tried to follow those instructions in order to gather Visual Studio and .NET Framework setup log files and found that they did not produce any logs named %temp%\msi*.log like I described in that post.
Unfortunately, I neglected to explain a subtle but important point in that previous blog post. Some MSI-based setups are packaged with a setup bootstrapper package (also known as an external UI handler) that uses the Windows Installer MsiEnableLog API to enable verbose logging by default. When this API is used, Windows Installer will create the log file with the specified name and the specified logging attributes, regardless of the logging policy set in the registry on the system. For reference, Windows Installer system policy settings are described in more detail in this MSDN topic.
The net result of this logic is that the steps listed in my previous blog post do not need to be used to enable verbose logging for some product setups, and in fact will not cause logs named %temp%\msi*.log to be generated.
The following is a list of some products that I know of that use an external UI handler and the MsiEnableLog function, and that therefore create their own log files regardless of the Windows Installer logging policy on the system. Each link contains information about the names and locations of the logs that the products create:
Many other MSI-based products, including the .NET Framework 1.0 and 1.1, will create a log named %temp%\msi*.log if you use the steps listed in my previous blog post.
An article has been published at http://www.gamasutra.com/view/feature/3545/sponsored_feature_democratizing_.php that provides much more detail about how the Xbox LIVE community game submission process that was introduced last week at GDC will work.
This article was written by Dax Hawkins, a group manager on the XNA Community Games team here at Microsoft. It describes details of the 4 steps of the community game submission and publishing process:
As announced in the article, there will be a beta for community game submission in the spring of 2008. Here is some key information about what will be supported in the beta:
If you are interested in learning more behind-the-scenes details about the upcoming Xbox LIVE community game submission, peer review and publishing process, I encourage you to check out the article.
Since the announcement of Xbox LIVE community games at GDC on Wednesday, there has been a great response from folks interested in downloading the XNA Creators Club Game Launcher and trying out free preview versions of some of these games on Xbox LIVE Marketplace. In particular, we heard from some people attending GDC who were not going to be arriving back home until after the download period for these games was scheduled to end on Sunday, February 24, 2008.
As a result of this interest and feedback, the time window that the Game Launcher and preview versions of Xbox LIVE community games will be available for free download has been extended. They will now be available for download until midnight Pacific Standard Time (PST) on Tuesday, February 26, 2008. This extension does not affect the time limit for playing the games after they have been downloaded however. They can be played until midnight PST on Sunday, March 9, 2008.
Xbox LIVE Community Games (with XNA Game Studio) were announced this morning in a Game Developers Conference (GDC) keynote presentation. As a part of that announcement, 7 games created with XNA Game Studio have been made available as free downloads via the Xbox LIVE Marketplace for a limited time.
The XNA Creators Club Game Launcher and Xbox LIVE Community Games will be available as free downloads from now until midnight Pacific Standard Time on Sunday, February 24, 2008, so download them now if you want to be able to try them out. The games will be playable until midnight PST on Sunday, March 9, 2008.
My colleague Michael Klucher recorded a brief video with Major Nelson (which can be found here) where he walks through how to download the XNA Creators Club Game Launcher and XNA Community Arcade games (it is currently not an entirely intuitive process). To summarize that video and the FAQ items on Xbox.com and the XNA Creators Club, here are the steps you'll need to follow in order to try out the Xbox LIVE Community Games.
To download the XNA Creators Club Game Launcher:
After following the above steps to download the XNA Creators Club Game Launcher, you can use the following steps to download Xbox LIVE Community Games:
The following Xbox LIVE Community Games are available to download:
There are already reviews that have been posted for a couple of the community games:
It has been an exciting day for the XNA team here at the Game Developers Conference in San Francisco. This morning's keynote presentation included a couple of announcements related to XNA Game Studio development - Xbox LIVE Community Games, and Zune game development with XNA Game Studio 3.0. I've gathered a few links that contain more information about each of these topics.
Xbox LIVE Community Games links:
Zune development with XNA Game Studio 3.0 links:
Also, if you're attending GDC, there are follow-up sessions tomorrow (Thursday, February 21) to discuss each of these announcements. A talk at 2:30pm PST will provide more details about Xbox LIVE Community Games, and a talk at 4pm PST will provide more details about Zune game development with XNA Game Studio 3.0.
Since the .NET Framework 2.0 SP1 and 3.0 SP1 shipped (as prerequisites for the .NET Framework 3.5 and as standalone packages), I have gotten questions from customers asking how to perform automated repairs and uninstalls for these packages. Because of the architecture changes that were made to .NET Framework 2.0 SP1 and 3.0 SP1 setup, the command lines that must be used for repair and uninstall scenarios are different than the ones for the original releases of the .NET Framework 2.0 and 3.0.
The following list provides example command lines that can be used to repair and uninstall the .NET Framework 2.0 SP1 and 3.0 SP1 after they have been installed on the system:
.NET Framework 2.0 SP1 - silent repair
msiexec /i {B508B3F1-A24A-32C0-B310-85786919EF28} /l*v %temp%\netfx20sp1_repair_log.txt /qn
.NET Framework 2.0 SP1 - silent uninstall
msiexec /x {B508B3F1-A24A-32C0-B310-85786919EF28} /l*v %temp%\netfx20sp1_uninstall_log.txt /qn
.NET Framework 3.0 SP1 - silent repair
msiexec /i {2BA00471-0328-3743-93BD-FA813353A783} /l*v %temp%\netfx30sp1_repair_log.txt /qn
.NET Framework 3.0 SP1 - silent uninstall
msiexec /x {2BA00471-0328-3743-93BD-FA813353A783} /l*v %temp%\netfx30sp1_uninstall_log.txt /qn
Important notes:
<update date="5/22/2008"> Added information about return codes from the command lines listed in this blog post. </update>
As mentioned in this post on the XNA team blog, the 2008 Game Developers Conference will be happening from February 18-22 in San Francisco, California, USA. I'll be heading to the conference along with several members of the XNA community gaming platform team. Here are a few key GDC events:
I'll be spending some of my time at GDC at the Lobby Bar, and I'm looking forward to talking with folks who are using XNA Game Studio or are thinking about trying it out.
I just noticed an interesting post on Ian Dixon's blog that I wanted to link to here. Anthony Park has posted this announcement on his blog about the release of new version of the MyNetflix application for Windows Vista Media Center. The first version of MyNetflix was written as a hosted HTML application for Windows XP Media Center Edition by Ryan Hurst, but the new version was rewritten from scratch and uses Media Center Markup Language (MCML).
Here is a summary of key features offered by the 2.0 version of the MyNetflix application:
Here are some links with more information about MyNetflix 2.0:
If you're a NetFlix subscriber and use Windows Vista Media Center, I encourage you to try out the beta of MyNetflix 2.0.
A new cumulative update package for Windows Vista Media Center has been released this week. This update is called the February 2008 Cumulative Update for Media Center for Windows Vista and is also known as KB947172. It is available for download in x86 and x64 versions.
The February 2008 Cumulative Update includes the following fixes:
Here are some links for the February 2008 Cumulative Update:
Recently, a customer contacted me with a question about a .NET Framework 3.5 installation error they were running into on a Windows XP Embedded runtime image. I worked with the XP Embedded team to post more details about the cause of this issue and how to work around it in this item on the Embedded team blog, but I also wanted to mention it here as well in order to hopefully make it easier to find in the future.
Description of the issue
The customer who contacted me has a Windows XP Embedded image that contains the .NET Framework 2.0 Windows XP Embedded component. When they attempt to run .NET Framework 3.5 setup on this image, it displays the following error and then fails:
Microsoft .NET Framework 2.0 Service Pack 1 -- Setup has determined that this version of .NET Framework is part of your operating system and cannot be installed or uninstalled with this setup. Use Windows Update for all future updates to .NET Framework. Setup will now exit.
Behind the scenes, the .NET Framework 3.5 installer is trying to install the .NET Framework 2.0 SP1 MSI package. The .NET Framework 2.0 SP1 MSI contains logic to block it from installing when it detects that the .NET Framework 2.0 was installed as an OS component, and that causes this error dialog to appear. When using the .NET Framework 2.0 component for Windows XP Embedded, the .NET Framework 2.0 is treated as an OS component and cannot be updated using MSI-based installers.
How to work around the issue
If you have a Windows XP Embedded runtime with the .NET Framework 2.0 component included, and you need to install the .NET Framework 3.5 on the image after it has been deployed, you can work around this blocking dialog by removing the following registry value from your runtime:
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v2.0.50727]OCM=1
When doing this, it is important to note that the .NET Framework 3.5 has additional dependencies that were not needed for the .NET Framework 2.0. Even after removing this registry value, you may run into errors during .NET Framework 3.5 installation if your Windows XP Embedded runtime image does not include these dependencies. If you have included the dependencies required for the .NET Framework 3.0 into your runtime image (described in this blog post), then you should be able to install the .NET Framework 3.5 as well.
Mike Hall and I have decided to move the source code and releases for the DUAScriptGen power toy for Windows XP Embedded over to the Codeplex site. So, starting today, you can go to http://www.codeplex.com/duascriptgen/ and do any of the following:
I have updated the information in the DUAScriptGen User's Guide on my blog to point to Codeplex, and I've also transferred the bug reports and feature requests I have gotten from customers in the past to the issues list in the project on Codeplex.
Hopefully this will prove useful to people who use DUAScriptGen as a part of their Windows XP Embedded device servicing strategy.
Since XNA Game Studio 2.0 shipped back in December, we've heard of a few installation issues from customers via the team blog and the forums. Many of the issues have been tracked back to a Games for Windows LIVE redistributable issue and can be resolved by using the steps in this forum post or this blog post. However, we've also seen a few cases with other root causes.
If you run into an install issue with XNA Game Studio 2.0 and have already tried the workaround described above and it did not help, then there is some additional information that can be useful to diagnose the failure:
If you run into an XNA Game Studio 2.0 install failure, please gather the above information and contact me and/or post a comment on the XNA forums so we can take a look.
<update date="7/23/2008"> Added information about DirectX error logs that can be useful in some cases where XNA Game Studio 2.0 setup fails. </update>
Bob Arnson recently posted some information about a new feature he contributed to the WiX toolset that I wanted to link to here. This feature allows you to pass a new switch named -dcl to the WiX linker (light.exe) to specify a default compression level for all of the cabinets in a package. This type of global setting can be useful when using WiX in an automated build system where you'd like to allow developers to create buddy builds with no compression (to speed up buddy build times), but would also like to ensure that daily builds and release builds are compressed.
You can check out more detailed information about this new feature in Bob's blog post at http://www.joyofsetup.com/2008/01/28/new-wix-feature-defaultcompressionlevel/.
If you want to try out this new feature, it is available in WiX v3.0 builds starting with the 3.0.3801.0 build located at http://wix.sourceforge.net/releases/3.0.3801.0/.
Beta 4 of TV Toolbox for Windows Vista Media Center has been released recently on the MCEDev.com site. This beta includes bug fixes and functional changes that address issues reported by customers who used the first 3 beta versions. Here are some links to additional information about TV Toolbox:
If you are interested in editing and converting your recorded TV shows to other formats in Windows Vista Media Center, I encourage you to check out TV Toolbox.