How to target the .NET Framework 2.0 instead of 3.5 in a Windows game created with XNA Game Studio 3.0
By default, when you create a new Windows game project in XNA Game Studio 3.0, it will target the .NET Framework 3.5. This means that the project will be configured to include references to assemblies that are a part of the .NET Framework 3.5 but are not a part of the .NET Framework 2.0 or 3.0, and it will also be configured to include the .NET Framework 3.5 as a prerequisite if you choose to deploy your game using ClickOnce or a Visual Studio setup/deployment project.
The Visual Studio 2008 product family includes a multi-targeting feature that allows you to select what version of the .NET Framework is required for your application. You can use multi-targeting to create a Windows game using XNA Game Studio 3.0 that only requires the .NET Framework 2.0 instead of 3.0 or 3.5. This can be particularly useful in reducing your installer footprint and to enable your game to run on Windows Vista after installing only the XNA Framework Redistributable Package 3.0 and your game payload.
There are some specific steps you need to take to change the project defaults and choose to target the .NET Framework 2.0 instead of 3.5 in your Windows game. The exact steps you need to take depend on what edition of Visual Studio 2008 you have installed.
Changing the .NET Framework version to target in Visual Studio 2008 Standard Edition or higher
In Visual Studio 2008 Standard Edition and higher, there is a drop-down menu in the New Project dialog that allows you to select the .NET Framework version you want to target in your XNA Game Studio 3.0 game project. The New Project dialog looks like the following, and the drop-down menu is in the top right corner of this dialog:
Note - if you change the drop-down menu from the default .NET Framework 3.5 value to .NET Framework 2.0, you will notice that the Content Pipeline Extension Library and Platformer Starter Kit project templates are no longer available. This is because those 2 project templates use features that rely on the .NET Framework 3.5.
After changing the .NET Framework version in the New Project dialog, you can create your project and it will automatically configure the assembly references, using statements in the source code and prerequisite packages for ClickOnce and setup projects appropriately.
Changing the .NET Framework version to target in Visual C# 2008 Express Edition
In Visual C# 2008 Express Edition, the New Project dialog does not offer an option to change the .NET Framework version you will target for your project. Instead, it will always create projects that target the .NET Framework 3.5. You can change the .NET Framework version you want to target after the project is created, but it requires some additional steps.
To change the .NET Framework version that your Windows game will target from the default .NET Framework 3.5 value to the .NET Framework 2.0, you can right-click on the project in the Visual Studio solution explorer and choose Properties. Then, in the Application properties tab, you can change the Target Framework drop-down. The UI for the Application properties tab looks like the following, and the Target Framework drop-down is directly below the Assembly Name text box:
Note - You can only target the .NET Framework 3.5 for Xbox 360 and Zune projects because there is only one available version of the .NET Compact Framework for these platforms in XNA Game Studio 3.0. As a result, the Target Framework drop-down will be blank and grayed out in the Application properties page for an Xbox 360 or Zune project.
After making a change to the Target Framework drop-down, you will be prompted to save, close and re-open the project. After clicking Yes to make the change, you will have to make the following additional manual changes to complete the .NET Framework re-targeting process:
- Remove the reference to System.Xml.Linq from your project.
- Remove the using statement that refers to System.Linq from the Game1.cs source file.
- Update the deployment prerequisites to include .NET Framework 2.0 instead of .NET Framework 3.5 - you can access the prerequisites dialog by right-clicking on your project, selecting Properties, selecting the Publish tab, then clicking on the Prerequisites... button.
You can also use the above steps in Visual Studio 2008 Standard Edition and higher to change the .NET Framework version that your game project will target if you do not want to keep the default value selected when you first created the project.
Possible deployment error messages related to .NET Framework version targeting issues
Skipping steps 1 and 2 above will result in build errors, so they will be easy to catch. Skipping step 3 can lead to more subtle error messages when users attempt to install your game.
There are a couple of installation errors your users might encounter that are related to .NET Framework version mismatches. If you create a game that targets the .NET Framework 3.0 or 3.5 and a user tries to run the ClickOnce .application file for the game on a system that has the .NET Framework 2.0 installed (but not 3.0 or 3.5), they will see an error with the following text:
Unable to install or run the application. The application requires that assembly WindowsBase Version 3.0.0.0 be installed in the Global Assembly Cache (GAC) first. Please contact your system administrator.
It looks like the following:
If you create a game that targets the .NET Framework 3.5 and a user tries to run the ClickOnce deployment manifest (named <game>.application) for the game on a system that has the .NET Framework 2.0 and 3.0 (but not 3.5) installed, they will see an error with the following text:
Unable to install or run the application. The application requires that assembly System.Core Version 3.5.0.0 be installed in the Global Assembly Cache (GAC) first. Please contact your system administrator.
It looks like the following:
In both of the above cases, you will need to double-check that you have selected the appropriate .NET Framework version as a prerequisite for your game. I have most commonly run into this type of error when creating a game that targets the .NET Framework 2.0 and then deciding to change it to target the .NET Framework 3.5 afterwards, but forgetting to update the deployment prerequisites for the game after making the targeting change (step 3 described above).
This type of error can also occur when creating a ClickOnce-based game installer, but then running the ClickOnce deployment manifest (<game>.application) instead of setup.exe on the system to deploy the game. The prerequisite checking logic for ClickOnce-based games exists in setup.exe, not in the deployment manifest. This can lead to cases where a user has a version of the .NET Framework (which will enable the .application file extension to be invoked), but do not have the version of the .NET Framework that your game is targeting.
A key thing to keep in mind here is that even if your Windows game does not use any .NET Framework 3.0 or 3.5 features, if you configure your project to target the .NET Framework 3.0 or 3.5, your users can run into this kind of error when they try to deploy your game to their system.
<update date="11/13/2008"> Added text that lists the deployment error messages to make this post easier to find in search engines. </update>
<update date="6/17/2009"> Fixed broken image links. </update>