.NET Framework Multi-Targeting for ASP.NET Web Projects

Visual Studio multi-targeting enables you to take advantage of the latest enhancements to Visual Studio without having to upgrade Web sites or Web services to the latest version of the .NET Framework. This lets you use Visual Studio to maintain and develop Web applications that use earlier versions of the .NET Framework.

Web projects can target the following versions of the .NET Framework:

• .NET Framework 4

• .NET Framework 3.5 SP1

• .NET Framework 3.0

• .NET Framework 2.0 SP1

This topic contains the following sections:

• Scenarios

• Multi-Targeting Features

• Selecting the Target .NET Framework Version

• Adding Items to a Web Project

• Adding Custom Web Server Controls to a Web Page

• IntelliSense

• Adding References

• Configuration Files

• Compiling

• Deployment

• Additional Information

Scenarios

Visual Studio multi-targeting enables you to perform the following tasks:

• Open and work on existing Web projects in Visual Studio that were created by using Visual Studio 2008 or Visual Studio 2005, without upgrading them to the .NET Framework 4. 

• Create new projects that you want to deploy in run-time environments that are configured with earlier versions of the .NET Framework.

Multi-Targeting Features

Visual Studio multi-targeting includes the following features:

• When you open a project in Visual Studio that targets an earlier version of the .NET Framework, Visual Studio can automatically upgrade it or leave it targeted for the earlier version.

• When you create a new project, you can specify the version of the .NET Framework that you want to target.

• You can change the version of the .NET Framework that an existing project is targeted for.

• You can target different versions of the .NET Framework in different projects in the same solution.

• When you change the version of the .NET Framework that a project targets, Visual Studio can make any required changes to references and to Web.config files.

In addition, when you work on a project that targets an earlier version of the .NET Framework, Visual Studio dynamically makes changes in the development environment, such as the following:

• It filters items in the New Project dialog box, in the Add New Item dialog box, in the Add New Reference dialog box, and in the Add Service Reference dialog box to omit choices that are available only in later versions.

• It filters custom Web server controls in the Toolbox to remove those that are available only in later versions, and to show the latest version when multiple controls are available for the targeted version.

• It filters IntelliSense to omit language features that are available only in later versions.

• It filters items in the Properties window to omit properties that are available only in later versions.

• It filters menus to omit options that are available only in later versions.

• It creates new Web pages and class files that have the appropriate default namespaces.

• It creates new Web.config files that have the appropriate sections, elements, and attributes.

• It compiles and builds with the appropriate version of the compiler and with the appropriate compiler options. The appropriate compiler is also used when you precompile a Web site (such as through the Deployment menu) and for dynamic compilation at run time.

  Note

  ASP.NET multi-targeting is designed to work with Visual Studio. If you use other tools to change the contents of files in an ASP.NET Web application, such as text editors, results are unpredictable.

Selecting the Target .NET Framework Version

If you want to target a version of the .NET Framework earlier than version 4, you must have the .NET Framework 3.5 installed on the computer that you use for development. This is true whether you are creating a new project or changing an existing project. You might need to install the .NET Framework 3.5, because by default the .NET Framework 3.5 is not installed with the .NET Framework 4.

Creating a New Project

When you create a new Web project in Visual Studio, you select the target framework from a drop-down list in the New Web Site dialog box or in the New Project dialog box.

Converting a Project Created by an Earlier Version of Visual Studio

When you open a Web project that has not been opened in Visual Studio before, you are asked if you want to upgrade the site to the current version of the .NET Framework. If you click Yes, Visual Studio makes the required changes to the Web.config file.

If you click No, Visual Studio determines the targeted version of the .NET based on what it finds in the Visual Studio project file or in the Web.config file. For more information, see Additional Information at the end of this topic.

Changing the Target Framework of an Existing Web Project

The target framework for existing projects can be changed. However, the normal direction in which to make a change would be from an earlier version to a later version.

For information about how to change the target Framework version of an existing project, see Additional Information at the end of this topic.

Adding Items to a Web Project

Visual Studio filters item templates that are displayed in the Add New Item dialog box based on the currently targeted version of the .NET Framework.

When you add an existing item to a project, Visual Studio does not verify that references 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 might see warnings or errors when you build and run the project.

Adding Custom Web Server Controls to a Web Page

Visual Studio hides custom Web server controls in the Toolbox that do not apply to the currently targeted version of the .NET Framework. If multiple versions of a custom Web server control are installed, Visual Studio hides all but the most current version. To see all versions, you can right-click the Toolbox and select Show All.

The Toolbox multi-targeting behavior assumes that custom Web server controls for a specific version of the .NET Framework can be used in projects for that version or for later versions. For instance, it assumes that .NET Framework 2.0 controls can be used in projects that target the .NET Framework 2.0, the .NET Framework 3.0, or the .NET Framework 4.

IntelliSense

Visual Studio provides IntelliSense for C#, Visual Basic, and ASP.NET markup that is adapted to the features of the targeted version. JScript IntelliSense is independent of the .NET Framework version that the project is targeting.

Adding References

When you open the Add Reference dialog box, Visual Studio displays all available assemblies but disables those that are for a later version of the .NET Framework than the version that is targeted. If you hold the mouse pointer over a disabled assembly, a tooltip explains why it is disabled.

You 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, run-time errors might result.

If you add a reference manually (by modifying project files directly without using the Add Reference dialog box), Visual Studio does not check the reference. If you add a reference that is not appropriate for the targeted framework version, you might see warnings or errors at design time, build time, or run time.

For information about adding service references, see Additional Information at the end of this topic.

Configuration Files

In projects that target the .NET Framework 4 or later versions, the compilation element of the Web.config file contains a targetFramework attribute, as shown in the following example:

<configuration>
  <configSections>...</configSections>
  <appSettings/>
  <connectionStrings/>
  <system.web>
    <compilation debug="false" 
        targetFramework="4.0">
    ...
    </compilation>
  </system.web>
  ...
</configuration>

Visual Studio automatically inserts the targetFramework attribute when you upgrade a project to the .NET Framework 4. It removes the attribute when you change a project's target from the .NET Framework 4 to an earlier version. 

Compiling

The Visual Studio design-time environment makes sure that you use only language and framework features that are available in the targeted version of the .NET Framework. If you edit the files of a Web project outside of Visual Studio and introduce code that refers to language or .NET Framework features that are not available in the targeted version, the compilation system will report an error when the project is compiled. For information about specific exceptional situations which might result in compile errors before or after deployment, see Additional Information at the end of this topic.

Deployment

When a Web site runs under IIS, the scriptmap (in IIS 6) or application pool (in IIS 7) must specify the targeted version of the .NET Framework. For more information, see How to: Deploy Web Projects Targeted for Earlier Versions of the .NET Framework.

The Copy Web Site tool in Visual Studio does not check the version of the .NET Framework that is running on a remote server. This tool cannot notify you if you copy a Web site project to a target server that does not contain the targeted version of the .NET Framework. In that case, the Web site might not run or might report run-time errors.

ASP.NET 4 applications that are configured as children of applications that run earlier versions of ASP.NET also might not run. For information about how to fix this, see the section "ASP.NET 4 Child Applications Fail to Start When Under ASP.NET 2.0 or ASP.NET 3.5 Applications" in the document ASP.NET 4 Beta 2 Breaking Changes on the ASP.NET Web site.

For more information about Web project deployment, see Web Deployment Overview for Visual Studio and ASP.NET.

Additional Information

This section provides details about some of the issues discussed earlier in this topic.

Setting the Default Target Framework for Converted Web Projects

When a Web project that was created by an earlier version of Visual Studio is opened in Visual Studio 2010 for the first time, you can choose not to upgrade the project to ASP.NET 4. If you do that, the target version of the .NET Framework is determined by using the following criteria:

• If the project was created or updated by a version of Visual Studio that supports multi-targeting, and if you open the project by using the Visual Studio project file, Visual Studio uses the information that is stored in the project file.

• If the previous criterion does not apply and if one of the following is found, Visual Studio targets the .NET Framework 3.5:

  • A compilers section in the Web.config file that maps to a compiler version of "v3.5" for C# or for Visual Basic.

  • References to .NET Framework 3.5 assemblies.

• If the previous criteria do not apply and references to .NET Framework 3.0 assemblies are found, Visual Studio targets the .NET Framework 3.0.

• If the Web site does not meet any of the previous criteria, Visual Studio targets the .NET Framework 2.0.

  Note

  A Web application project includes Visual Studio project files. These files are converted to the Visual Studio format even if you choose not to target an earlier version of the .NET Framework. For more information, see How to: Upgrade an ASP.NET Web Application to ASP.NET 4.

How to Change the Target Framework Version of an Existing Web Project

The location of the list of target .NET Framework versions that you can choose from depends on the type of Web project. The list can be in one of the following locations:

• For C# Web application projects, the list is in the Application tab of the project properties dialog box.

  

• For Visual Basic Web application projects, the list is in the Advanced Compiler Settings dialog box, which you can reach by clicking the Advanced Compiler Options button on the Compile tab of the project properties dialog box.

  

• For all Web site projects, the list is in the Property Pages dialog box.

  

When you change the target framework, Visual Studio might require you to close and re-open the project.

The list from which you select the version of the .NET Framework might include options that refer to subsets of the .NET Framework. These subsets are called profiles. A profile must include the System.Web assembly in order to be suitable for Web development. If you select a profile that is inappropriate for a Web application project, an error might occur when the Web site is compiled or when it is run.

Adding Service References

The Add Service Reference dialog box is available only in Web sites that target the .NET Framework 3.5 or later versions, and in Web application projects that target the .NET Framework 3.0 or later versions.

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.

Manually Modifying the TargetFramework Attribute

If you manually add the targetFramework attribute to the Web.config file of a Web application that targets earlier versions of the .NET Framework, an error will result.

Adding the targetFramework attribute to the root Web.config file instead of to each application Web.config is not recommended, for the following reasons:

• There is no benefit to putting the targetFramework attribute in the root Web.config, because Visual Studio manages the targetFramework attribute.

• The multi-targeting feature of Visual Studio will not work correctly if you put the targetFramework attribute in the root Web.config file of a development server.

Compiling Web Site Projects

Visual Studio relies on information in the Web.config file to determine which version of the .NET Framework is targeted. Therefore, some errors can arise that do not apply to Web application projects. This is because for Web application projects, the target version that is stored in the Visual Studio project file is used for compiling.

The following scenarios for Web site projects might result in unexpected results:

• In a Web site project that targets the .NET Framework 4.5 or later versions, the targetFramework attribute is removed.

  Visual Studio compiles the project as if it were targeting the .NET Framework 3.0. If the Web site uses features that are not available in the .NET Framework 3.0, compile errors will result.

• In a Web site project that targets the .NET Framework 2.0, references to .NET Framework 3.0 features are added by using a tool other than Visual Studio, such as a text editor.

  Visual Studio compiles the project as if it were targeting the .NET Framework 3.0. Therefore, there is no compile error that warns about the use of .NET Framework 3.0 features. But if the Web site is deployed to a server that does not have the .NET Framework 3.0 installed, errors might result.

• A Web site project that targets the .NET Framework 2.0 or the .NET Framework 3.0 is deployed to a server that does not have the .NET Framework 3.5 installed, and markup in .aspx pages refers to control properties that are new in the .NET Framework 3.5.

  In order to target versions of the .NET Framework earlier than version 4, the computer that runs Visual Studio must have the .NET Framework 3.5 installed. Therefore, when the Web site is tested in Visual Studio, references to properties that are defined in the .NET Framework 3.5 will result in behavior that would be expected for the .NET Framework 3.5. However, if the Web site is deployed to a server that does not have the .NET Framework 3.5 installed, these properties will not be recognized, and they might be treated as expando attributes.

• An IIS Web site project that targets a .NET Framework version earlier than the .NET Framework 4 is nested in IIS within an IIS Web application that targets the .NET Framework 4.

  Web.config files inherit settings from files that are higher in the IIS application hierarchy. The .NET Framework 4 is backward compatible. Therefore, a nested application that targets the .NET Framework 4 can inherit settings from Web.config files that are for earlier versions. But versions of the .NET Framework are not forward compatible. Therefore, earlier versions cannot inherit settings from later versions.

Dynamic Compilation

Visual Studio makes sure that only features that are relevant to the targeted .NET Framework version are used in a Web site project. When the Web site project is deployed to a production server and is dynamically compiled, ASP.NET uses the assemblies that are in the GAC for the CLR version that is associated with the Web application's IIS application pool. Therefore, unexpected results can occur during dynamic compilation if the Web application is associated with the wrong CLR version.

The assemblies that are used for dynamic compilation might be for a later .NET Framework version than the version that the Web application targets. The GAC contains only the most current assemblies for each version of the CLR that is installed on a computer. Therefore, the compiler uses the most current version of the .NET Framework that is installed on the computer for the selected version of the CLR. For example, the .NET Framework 2.0, the .NET Framework 3.0, and the .NET Framework 3.5 all use the .NET Framework 2.0 CLR. If a computer has the .NET Framework 3.5 installed, and if a Web application uses an application pool that is associated with the .NET Framework 2.0 CLR, ASP.NET uses the .NET Framework 3.5 assemblies.

The Command-Line Compiler

The aspnet_compiler.exe and aspnet_merge.exe tools can be used from the command-line directly or within a build environment. When you compile a Web site by using one of these tools, you must use one of the following versions:

• The version that is provided with the .NET Framework 2.0. This version is for Web sites that target the .NET Framework 2.0, the .NET Framework 3.0, or the .NET Framework 3.5. The sites must be deployed in an application pool that is associated with the targeted version of the .NET Framework.

• The version that is provided with the .NET Framework 4. This version is for Web sites that target the .NET Framework 4 and later versions of the .NET Framework. This version of the tool will create assemblies that work only with the .NET Framework 4 CLR even if the Web.config file lacks the targetFramework attribute.

  You can use this version to compile an application whose Web.config file indicates that it targets one of the earlier versions, which is useful if you intend to deploy the application to an application pool that is associated with the .NET Framework 4.

For more information about the command-line compiler and dynamic compilation, see the following topics:

• ASP.NET Compilation Tool (Aspnet_compiler.exe)

• Understanding ASP.NET Dynamic Compilation

• BuildManager.TargetFramework

Designing Custom Web Server Controls for Multiple Target Frameworks

The Visual Studio environment always runs the latest version of the .NET Framework, even when the project targets an earlier .NET Framework version. To provide multi-targeting functionality, Visual Studio filters metadata about types to make sure that projects that target earlier versions do not use classes or members that were introduced in .NET Framework versions later than the target. Because of this filtering, IntelliSense, property windows, and so on present information that is appropriate to the targeted version.

If a custom Web server control must determine at design time whether a class or members of a class exist, the code should use the TypeDescriptor class instead of using reflection. This makes sure that the code finds only classes or members that are available in the version of the .NET Framework that is targeted in the project where the control is used. The use of reflection will circumvent the type-filtering mechanisms that Visual Studio uses for a given .NET Framework target.

Only the latest version of a custom control is typically shown in the Toolbox. If you want earlier versions to remain accessible in the Toolbox, and if the control's assembly is deployed to the Bin folder rather than to the GAC, make sure that the assembly names for each version of the control are different.

When a control is dragged from the Toolbox to a Web page, the assembly is copied to the Bin folder. Therefore, if the site already has instances of an earlier version of the custom Web server control, and if the latest version is then dragged onto a page, the new version will overwrite the earlier versions of the control in the Web site's Bin folder. Because Visual Studio already has the older version in memory, copying over the assembly in the Bin folder might cause errors.

For more information about how to make sure that custom Web server controls work correctly with ASP.NET multi-targeting, see Web Custom Control Behavior and Authoring on the Visual Web Developer team blog.

Designing Custom Build Providers and Expression Builders for Multiple Target Frameworks

You should make sure that any code that is generated through build providers and expression builders works with different versions of the .NET Framework. Build providers and expression builders should check the BuildManager.TargetFramework property to determine which .NET Framework version a project targets, and generate only code that is valid for the targeted version.

See Also

Tasks

How to: Host Web Applications That Use Different Versions of the .NET Framework on the Same Server

How to: Upgrade an ASP.NET Web Application to ASP.NET 4

Concepts

ASP.NET Side-by-Side Execution Overview

Other Resources

Targeting a Specific .NET Framework Version or Profile