.NET Framework Targeting for Web Sites
The multi-targeting feature of Visual Studio 2008 enables you to specify the .NET Framework version that you want the Web site or Web service to target. This lets you use Visual Studio 2008 to modify existing and new Visual Studio 2008 Web projects without unintentionally creating new assembly dependencies in your projects. Visual Studio 2008 enables you to build a Web site that can be deployed to the .NET Framework 2.0, .NET Framework version 3.0, or .NET Framework version 3.5 Service Pack 1. It does this by making sure that your project uses only the functionality that is available in the version of the .NET Framework that you specify for the project.
This topic contains information about the following:
Project Differences when Targeting a .NET Framework
Scenarios
Multi-targeting in Visual Studio 2008 enables you to target a Web site to a specific version of the .NET Framework. For example, you might want to create an ASP.NET Web application that uses the security capabilities supported by Windows Communication Foundation (WCF). If the application does not need support for Language-Integrated Query (LINQ), you can target the .NET Framework version 3.0.
Back to top
Multi-Targeting Features
The multi-targeting features of Visual Studio 2008 include the following:
You can select the .NET Framework version when you are creating a new Web site.
Visual Studio can detect the .NET Framework version when you open a Web site.
When Visual Studio detects that a Web site uses the .NET Framework version 2.0, Visual Studio gives you the option to target the .NET Framework version 3.5 Service Pack 1.
Visual Studio filters out features that do not apply to the currently targeted version of the .NET Framework. This includes menu options, Toolbox objects, compilation processes, and assembly references.
You can use project properties to select a target .NET Framework version.
.NET Framework Libraries
Visual Studio lets you target of the following versions the .NET Framework:
.NET Framework version 2.0 The version of the .NET Framework that is included with Microsoft Visual Studio 2005.
.NET Framework version 3.0 The version of the .NET Framework that is included with the operating system. This .NET Framework version includes support for Windows Presentation Foundation (WPF), Windows Communication Foundation (WCF), Windows CardSpace, and Windows Workflow Foundation.
.NET Framework version 3.5 The .NET Framework version that is included as the default for Visual Studio. This .NET Framework version includes support for ASP.NET AJAX and Language-Integrated Query (LINQ).
Back to top
Background
Visual Studio 2008 lets you target multiple versions of the .NET Framework from a single development environment. Visual Studio 2005 and earlier versions targeted a single version of the .NET Framework. Developers who wanted to write applications for different versions of the .NET Framework did so by running side-by-side versions of Visual Studio. Runtime dependencies and backward compatibility were key considerations related to multi-targeting.
In Visual Studio 2008, you can open a Visual Studio 2005 Web site without any changes being made to your code. However, the project file for the Web site will be upgraded. By default, Visual Studio 2005 projects will continue to target the .NET Framework 2.0. However, you can switch the target framework version for an existing project to take advantage of new features in a later version of the .NET Framework.
The latest .NET Framework functionality is included in new assemblies. Assemblies for earlier versions of the .NET Framework are not changed.
Creating a New Web Site
When you create a new Web site, you can specify the version of the .NET Framework to target for your project. New Visual Studio projects automatically target the newest version of the .NET Framework.
The following procedure describes how to create a new Web site that targets a specified .NET Framework version.
To create a new Web site and specify the .NET Framework target
In Visual Studio, in the File menu, click New Web Site.
The New Web Site dialog box is displayed.
From the framework version list, select the .NET Framework version that you want the project to target.
The list of templates displayed in the dialog box is filtered based on the framework that you select.
Under Visual Studio installed templates, select a Web site type, such as ASP.NET Web Site.
Click OK.
Opening an Existing Visual Studio 2005 Web Site
Visual Studio 2008 enables you to open projects or Web sites that were created in earlier versions of Visual Studio without upgrading the projects to a newer version of the .NET Framework. You can edit, compile, build, debug, and save Visual Studio 2005 projects.
You can open an existing Visual Studio 2005 project without targeting a later .NET Framework version. The first time that the Web application is opened in Visual Studio 2008, you will be prompted to target the Web site to .NET Framework version 3.5 Service Pack 1. If you do not want to change the target framework, click No.
Note
When you open a remote Web site, Visual Studio 2008 does not try to filter the available versions according to the .NET Framework versions that are installed on the remote server.
Upgrading or Downgrading the Target .NET Framework Version for an Existing Web Site
The following procedure describes how to change the version of the .NET Framework for an existing project to target a newer or older version.
Upgrading to a newer version of the .NET Framework lets you take advantage of new features. Downgrading a Web application to a different .NET Framework version lets you target the .NET Framework version installed on a different Web server.
If you are downgrading a project, you must make sure that the project works with the older version of the .NET Framework. This often requires you to manually make changes in the project.
Note
Beyond the different features that are available for each .NET Framework version, the primary differences when you change the .NET Framework version of a Web application are in the Web.config file.
To upgrade or downgrade the .NET Framework version for a Web Site
In Visual Studio 2008, open the Web site that you want to upgrade or downgrade.
In Solution Explorer, right-click the project name and then click Properties Pages.
Note
For Web Application Projects, right-click the project in Solution Explorer and then click Properties.
On the Project Properties page, click the Build tab.
Note
For Web Application Projects that use C#, click the Application tab of the Project Properties page. For Web Application Projects that use Visual Basic, click the Compiler tab of the Project Properties page and click Advanced Compiler Settings.
In the .NET Framework drop-down list, select a version number to target.
Note
For Web Application Projects, the project is unloaded and then reloaded in Visual Studio.
If you have downgraded a project, do the following:
Manually remove references to components that are not part of the targeted .NET Framework version.
Note
You might see reference errors in your code because of assembly references that no longer work with the older .NET Framework version. In that case, you must manually replace any missing assembly references.
If the project contains service references, remove them by right-clicking the service reference and then clicking Remove.
Assembly References
Visual Studio helps you add references to Web projects without automatically upgrading to a different .NET Framework version.
When you add a reference to an assembly, the Add Reference dialog box displays only system assemblies that belong to the target .NET Framework version. This prevents you from unintentionally adding references to assemblies that are not in the target framework.
Note
You can manually edit your project file to include references that belong to a .NET Framework target that is later than that of the current project. However, this will generate warnings at compile time.
Your might add a user assembly reference to your project that in turn references system assemblies that are not part of the target framework. In that case, Visual Studio displays a warning. If you ignore this warning, it displays again at build time.
Back to top
Project Differences when Targeting a .NET Framework Version
This section focuses on the differences between Web projects that target different versions of the .NET Framework. Differences include compilation, assembly support, and feature support. Some features in Visual Studio do not include support for multi-targeting, such as IntelliSense and deployment.
For new Web sites, the .NET Framework version that you select determines the following:
The assemblies that are referenced by default.
The namespaces that are included by default in ASP.NET Web pages and class files.
The version of the compiler that is used by ASP.NET at run time and at design-time for dynamic compilation.
The options that can be selected in Visual Studio, such as the objects, new items, assembly references, Web references, and service references.
When you open an existing Web site, Visual Studio tries to detect the .NET Framework version and set the projects target .NET Framework version. Visual Studio determines the .NET Framework version by using the following criteria:
If references to .NET Framework 3.0 assemblies exist, the Web project targets at least the .NET Framework 3.0. (Depending on other conditions, it might target a later version.)
If a compilers section in the Web.config file is mapped to a compiler version of "v3.5" for C# or for Visual Basic, the Web site targets the .NET Framework 3.5.
If there are references to .NET Framework 3.5 assemblies, the Web site targets the .NET Framework 3.5.
If the Web site does not meet the previous conditions, the Web site targets the .NET Framework version 2.0.
Note
If the project was previously opened or was created by Visual Studio, the target version number will already be stored in the project. In that case, Visual Studio uses the stored version number. It does not try to detect a mismatch between the stored version number and the version detected from references and compilers.
Selecting a Project Template
Visual Studio displays only the project templates that apply to the currently targeted .NET Framework version. When you create a new Web site, Visual Studio automatically targets the highest version number of the .NET Framework to provide access to the latest features. Alternatively, you can select a target version when you create the project.
The default content of the Web.config file for a new Web site is based on the selected version of the .NET Framework. The default referenced assemblies are specified in the assemblies section, and the compiler version is specified in the compilers section.
Adding Objects from the Toolbox
Visual Studio disables items in the Toolbox that do not apply to the currently targeted version of the .NET Framework. The Toolbox multi-targeting behavior assumes that components for a specific version of the .NET Framework can be used in projects for that version or later versions. For instance, .NET Framework 2.0 controls can be used in .NET Framework 2.0, .NET Framework version 3.0, or .NET Framework version 3.5 Service Pack 1.
Adding New Items
Visual Studio filters items that are displayed in the Add New Item dialog box based on the currently targeted version of the .NET Framework.
Note
If you add an existing item to a project, Visual Studio does not verify that references and imports for that item match the currently targeted version of the .NET Framework. No warnings are generated. However, if those references cannot be resolved in the project, you will see an error when you build and run the project.
Adding Assembly References
When you open the Add Reference dialog box, Visual Studio checks the currently targeted version of the .NET Framework version and enumerates only the assemblies that are available for that version. Assemblies that are for a later target framework are displayed but are disabled.
The title of the Add Reference dialog box includes the current .NET Framework target version. Because the dialog box shows the framework version of each assembly, you can determine which version of the .NET Framework is required in order to add the reference. The Add Reference dialog box also displays information about the assembly as a tooltip when you hold the mouse pointer over an unavailable assembly.
Note
If you add a system reference manually (without using the Add Reference dialog box), Visual Studio does not check the reference. You might see warnings at design or at build time that the assembly reference is not part of the currently targeted version of the .NET Framework target.
Adding Service References
The Add Service Reference dialog box is available only in Web sites that target the .NET Framework 3.5 and in Web Application projects that target the .NET Framework 3.0 or the .NET Framework 3.5. If you want to add a service reference to a Web site that targets the .NET Framework 3.0, you can add the service reference to a class library project. You can then reference the class library project from the Web site project.
Note
Class libraries cannot be added to a project in Visual Web Developer.
Using IntelliSense
The language services in Visual Studio 2008 do not target specific versions of the .NET Framework. Therefore, the editor always provides IntelliSense for the latest versions of C# and Visual Basic.
Web projects display IntelliSense for all .NET Framework versions, independent of the framework version that the project is targeting. When you target the .NET Framework version 2.0 or .NET Framework 3.0, any code that references features of the .NET Framework version 3.5 results in compiler errors.
JScript IntelliSense is independent of the .NET Framework version that the project is targeting.
Deploying a Project
The Publish and Copy Web tools in Visual Studio 2008 do not target specific versions of the .NET Framework. Visual Studio does not check the version of the .NET Framework that is running on a remote server. These tools cannot notify you if you publish a project to a target server that contains an earlier version of the .NET Framework than what your project is targeted to. In that case, a project that targets a later version of the .NET Framework will not run.
Back to top
See Also
Concepts
What's New in ASP.NET and Web Development
Reference
Back to top