Upgrading XNA Game Studio projects for use in the XNA Game Studio 3.0 beta

  • Article

One of the new features in the XNA Game Studio 3.0 beta is an automated process to upgrade your XNA Game Studio 2.0 projects to the format used by XNA Game Studio 3.0.

There are a few different upgrade scenarios that you can end up in, depending on what format your original project files are in.  In this post, I will summarize each of them and explain what is needed in order to get up and running in the XNA Game Studio 3.0 beta.

XNA Game Studio Express 1.0 and 1.0 Refresh projects

1.0 and 1.0 refresh projects are Visual Studio 2005 projects behind the scenes.  This means that attempting to open them in Visual Studio 2008 and XNA Game Studio 3.0 will trigger the built-in Visual Studio 2008 conversion wizard.  However, the XNA Game Studio 3.0 product does not include the necessary logic to automatically upgrade these projects to 3.0 format.  That means that if you use the built-in Visual Studio 2008 conversion wizard, your project will be converted from VS 2005 to VS 2008 format, but it will not work as expected with XNA Game Studio 3.0.

The options for upgrading 1.0 and 1.0 refresh projects are outlined in item 1.2.3 in the XNA Game Studio 3.0 beta readme.  To summarize that item, you can do one of the following:

  1. Create a new game project in XNA Game Studio 3.0, then import your code and content files
  2. Use the XNA Game Studio 2.0 upgrade wizard to convert your 1.0 or 1.0 refresh project to 2.0, then open the converted 2.0 project in Visual Studio 2008 and XNA Game Studio 3.0

My colleague Stephen posted a very helpful set of steps for option 1 in this post on the Creators Club forums.  Here is a summary of those steps:

  1. Create a new game project in the XNA Game Studio 3.0 beta
  2. Delete the code files created by default by the new project (Game1.cs, Program.cs)
  3. Right-click on the new project in the VS Solution Explorer and choose Add | Existing Item...
  4. Browse to the old project directory and select all the code files (*.cs). This will copy the old files into the new project. If you have your code in sub-folders, add new folders to the new project first, then right-click and add files to the folder node.
  5. Right-click on the Content node under the new project, and choose Add | Existing Item...
  6. Browse to the old project directory and select all the content files (*.x, *.jpg, etc). This will copy the old files into the new project. Note that doing this will place all the build content into a subdirectory called Content. You should modify your content loading code accordingly. The RootDirectory property on ContentManager will make this easy.
  7. If you had additional references for the Content Pipeline, you now add those to the References node in the Content project under your new project. The Content node is actually a nested project, which only builds content with the Content Pipeline. This was introduced in XNA Game Studio 2.0.
  8. Fix up your code to match the API changes that have occurred between 1.0 to 3.0. The biggest changes occurred between 1.0 and 2.0. There is an MSDN topic named XNA Framework Changes in XNA Game Studio 2.0 that will help here.
  9. You may need to fix up the Content Pipeline properties because a few things have changed since 1.0.

XNA Game Studio 2.0 projects

2.0 projects are Visual Studio 2005 projects behind the scenes.  When you open them in Visual Studio 2008 and XNA Game Studio 3.0, the built-in Visual Studio 2008 conversion wizard will run.  XNA Game Studio 3.0 extends this conversion wizard to make the necessary changes to 2.0 project files so they will open, build and run correctly with XNA Game Studio 3.0.  The conversion process does not change any of the code in any of your projects though, so if there are any behavior changes in XNA Framework APIs between XNA Game Studio 2.0 and 3.0 that affect your scenarios, you will need to update the code yourself as needed.

XNA Game Studio 3.0 CTP projects

3.0 CTP projects are Visual Studio 2008 projects behind the scenes.  When you open them in Visual Studio 2008, the conversion wizard does not run because Visual Studio does not detect that any upgrades are needed.  As a result, there is not an opportunity for XNA Game Studio 3.0 to automatically upgrade old CTP projects when they are opened in the beta.  In addition, there is not any metadata in a 3.0 CTP project to guarantee that it was created in the CTP.  Instead, there is logic in the build process to display an error like the following if you attempt to build a CTP project in the beta:

The project file '<projectname>' appears to have been created with XNA Game Studio 3.0 CTP. For instructions on how to upgrade this project to work with the current version, copy and paste this link into your browser: https://go.microsoft.com/fwlink/?LinkId=121512.

This link redirects to the XNA Game Studio 3.0 beta readme, and the steps required to update your 3.0 CTP projects to 3.0 beta format are listed in item 1.2.1 there.  Here is a summary of those steps (I have modified them slightly from the ones listed in the readme because the ones in the readme only work in Visual Studio 2008 but not in Visual C# 2008 Express Edition):

  1. Open <projectname>.csproj in a text editor such as Notepad.

  2. Scroll down to the bottom of the .csproj file and locate the following three <Import.../> elements.

    <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
    <Import Project="$(MSBuildExtensionsPath)\Microsoft\XNA Game Studio\v3.0\Microsoft.Xna.GameStudio.Common.targets" />
    <Import Project="$(MSBuildExtensionsPath)\Microsoft\XNA Game Studio\v3.0\Microsoft.Xna.GameStudio.NestedContent.targets" />

  3. Replace these with the following two <Import.../> elements. Note that the first element is the same.

    <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
    <Import Project="$(MSBuildExtensionsPath)\Microsoft\XNA Game Studio\Microsoft.Xna.GameStudio.targets" />

  4. Save <projectname>.csproj file.

  5. Open <projectname>.csproj in Visual C# 2008 Express Edition or Visual Studio 2008 in order to use it with the XNA Game Studio 3.0 beta.

<update date="10/1/2008"> Clarified the steps to update a CTP project - they were originally using steps that only work in Visual Studio 2008 but not in Visual C# 2008 Express Edition. </update>