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

If you use Visual Studio to open a Web project that was developed for the .NET Framework 2.0, the .NET Framework 3.0, or the .NET Framework 3.5, Visual Studio can automatically perform all the changes to Web.config files that are required to be able to run using .NET Framework 4.5. If the project is a local IIS project and you are using IIS 7.0, Visual Studio can also reassign the application to an application pool that is associated with the .NET Framework 4.

It is recommended that you use Visual Studio to perform the tasks that are required in order to upgrade. If you do not use Visual Studio to perform the upgrade automatically, you must manually edit the Web.config file and must manually associate the application in IIS with the .

Typically the procedures covered in this topic are sufficient for upgrading a Web application, because later versions of the .NET Framework are designed to be backward compatible with earlier versions. However, you should also look in the readme documentation for breaking changes. The behavior of a component that was developed for an earlier version of the .NET Framework might have changed in the newer version of the .NET Framework.

To upgrade an application by using Visual Studio

1. Open the Web site or project in Visual Studio.

2. If a Visual Studio Conversion Wizard welcome dialog box appears, click Next.

   This wizard appears when you open a Web Application Project or a solution. It does not appear when you open a Web Site project that is not in a solution.

   

3. If you are converting a project, in the Visual Studio Conversion Wizard, select backup options and click Next in the Choose Whether to Create a Backup dialog box.

   

   Visual Studio upgrades your project file to the Visual Studio 2010 format. If you are upgrading a solution instead of an individual project, Visual Studio upgrades the solution file to the Visual Studio 2010 format.

4. If you are converting a project, in the Visual Studio Conversion Wizard, click Next in the Ready to Convert dialog box.

   

5. If you are opening the Web project on a computer that does not have the .NET Framework 3.5 installed, in the Project Target Framework Not Installed dialog box, select Retarget the project to .NET Framework 4 and click OK.

   

6. If you are opening the Web project on a computer that does have the .NET Framework 3.5 installed, in the Web Site targeting older .NET Framework Found dialog box, clear the check box if you do not want to upgrade all Web sites or projects in a solution.

   

7. In the dialog box, click Yes.

   Visual Studio updates the Web.config file. The changes that are made to the Web.config file are listed in the procedure later in this topic that explains how to update the Web.config file manually. Visual Studio does not update comments. Therefore, after the conversion, the Web.config file might contain comments that reference earlier versions of the .NET Framework.

   Visual Studio automatically sets the controlRenderingCompatibilityVersion attribute of the pages element to 3.5. You can remove this setting in order to take advantage of XHTML and accessibility improvements in ASP.NET 4. For more information, see the procedure later in this topic that explains how to update the Web.config file manually.

8. If you are converting a project, in the Visual Studio Conversion Wizard, click Close in the Conversion Complete dialog box.

   

9. If the project is not a local IIS project, associate its IIS application with the Visual Studio when it is deployed to IIS. For more information, see the procedure later in this topic that corresponds to the version of IIS that you are using.

   If the IIS application is associated with the .NET Framework 2.0, the site will not work. ASP.NET will generate errors that indicate that the targetFramework attribute is unrecognized.

10. If the project is a local IIS project and the IIS version is 6.0, associate its IIS application with the Visual Studio by following the procedure later in this topic for IIS 6.0.

    If the project is a local IIS project, Visual Studio automatically performs this association. It assigns the application to the first available application pool for the.NET Framework 4. If no application pool exists, Visual Studio creates one.

    Note

    By default, the IIS 6.0 Metabase API that Visual Studio uses to assign and create application pools is not available in Windows Vista or Windows 7. To make it available, enable IIS 6 Metabase Compatibility Layer in the Windows Control Panel by selecting Programs and Features and Turn Windows Features On or Off. The following illustration shows the Windows Features dialog box.

    

11. If the project includes code that accesses the HttpBrowserCapabilities object (in the HttpRequest.Browser property), test the code to make sure that it works as expected.

    The browser definition files that provide information to the HttpBrowserCapabilities object were changed in ASP.NET 4, and the changes are not backward compatible with earlier versions of ASP.NET. If you discover a problem and prefer not to change your code to accommodate the ASP.NET 4 changes, you can copy the ASP.NET 3.5 browser definition files from the ASP.NET 3.5 Browsers folder of a computer that has ASP.NET 3.5 installed to the ASP.NET 4 Browsers folder. The Browsers folder for a version of ASP.NET can be found in the following location:

    %SystemRoot%\Microsoft.NET\Framework\versionNumber\Config\Browsers

    After you copy the browser definition files, you must run the aspnet_regbrowsers.exe tool. For more information, see ASP.NET Web Server Controls and Browser Capabilities.

To manually upgrade an application's Web.config file from the .NET Framework 3.5 to the .NET Framework 4

1. Make sure that the application currently targets ASP.NET 3.5.

   Note

   This topic explains how to convert a Web.config file from the .NET Framework 3.5 to the .NET Framework 4. To upgrade a Web application that is earlier than the .NET Framework 3.5, you must first convert the application to the .NET Framework 3.5. For more information, see Converting to ASP.NET 3.5.

2. Open the Web.config file in the application root.

3. In the configSections section, remove the sectionGroup element that is named "system.web.extensions".

4. In the system.web section, in the compilation collection, remove every add element that refers to an assembly of the .NET Framework.

   Framework assemblies generally begin with "System.". Typically these have Version=3.5.0.0 in the assembly attribute. However, some assembly entries that have the 3.5.0.0 version number might refer to assemblies that were installed as part of add-on releases, or to custom assemblies. Do not delete these. If the Web.config file contains any of these references, you must investigate them individually to determine whether a later version is available and whether the version reference must be changed.

5. Add a targetFramework attribute to the compilation element in the system.web section, as shown in the following example:

   <compilation targetFramework="4.0">
   

   In the opening tag for the pages section, add a controlRenderingCompatibility attribute, as shown in the following example:

   <pages controlRenderingCompatibilityVersion="3.5"/>
   

   Many ASP.NET 4 controls render HTML that is compliant with XHTML and accessibility standards. However, the Web site that you are converting might have CSS rules or client script that will not work correctly if Web pages change the way they render HTML. If you want to take advantage of the control rendering enhancements in ASP.NET 4, you can omit this attribute. For more information, see ControlRenderingCompatibilityVersion.

6. In the system.codedom section, in the compilers collection, remove the compiler elements for c# and vb.

7. Delete everything between the system.webserver section start and end tags, but leave the tags themselves.

8. Delete everything between the runtime section start and end tags, but leave the tags themselves.

9. If you have customized the Web.config file, and if any customizations refer to custom assemblies or classes, make sure that the assemblies or classes are compatible with the .NET Framework 4.5.

   The following example shows an example Web.config file for a simple Web application that was converted from the .NET Framework version 3.5 to the .NET Framework version 4.

   <?xml version="1.0"?>
   <!-- 
       Note: As an alternative to hand editing this file you can use the 
       web admin tool to configure settings for your application. Use
       the Website->Asp.Net Configuration option in Visual Studio.
       A full list of settings and comments can be found in 
       machine.config.comments usually located in 
       \Windows\Microsoft.Net\Framework\v2.x\Config 
   -->
   <configuration>
     <appSettings/>
     <connectionStrings>
       <add name="NorthwindConnection" connectionString="Data Source=.\SQLEXPRESS;AttachDbFilename=|DataDirectory|\NORTHWND.MDF;Integrated Security=True;User Instance=True" providerName="System.Data.SqlClient"/>
     </connectionStrings>
     <system.web>
   <!-- 
       Set compilation debug="true" to insert debugging 
       symbols into the compiled page. Because this 
       affects performance, set this value to true only 
       during development.
   -->
     <compilation debug="true" targetFramework="4.0">
       <assemblies>
       </assemblies>
     </compilation>
   <!--
       The <authentication> section enables configuration 
       of the security authentication mode used by 
       ASP.NET to identify an incoming user. 
   -->
     <authentication mode="Windows"/>
   <!--
       The <customErrors> section enables configuration 
       of what to do if/when an unhandled error occurs 
       during the execution of a request. Specifically, 
       it enables developers to configure html error pages 
       to be displayed in place of a error stack trace.
           <customErrors mode="RemoteOnly" defaultRedirect="GenericErrorPage.htm">
               <error statusCode="403" redirect="NoAccess.htm" />
               <error statusCode="404" redirect="FileNotFound.htm" />
           </customErrors>
   -->
     <pages controlRenderingCompatibilityVersion="3.5"/></system.web>
     <system.codedom>
     </system.codedom>
   <!-- 
       The system.webServer section is required for running ASP.NET AJAX under Internet
       Information Services 7.0.  It is not necessary for previous version of IIS.
   -->
     <system.webServer>
     </system.webServer>
   </configuration>
   

To associate an IIS application with the .NET Framework 4 in IIS 7.0

1. In Windows, start Inetmgr.

2. In the Connections pane, expand the server node and then click Application Pools.

3. On the Application Pools page, select the application pool that contains the application that you want to change.

4. In the Actions pane, click View Applications.

5. Select the application whose application pool that you want to change and then click Change Application Pool in the Actions pane.

6. In the Select Application Pool dialog box, select an application pool that is associated with .NET Framework 4 from the Application pool list, and then click OK.

To associate an IIS application with the .NET Framework 4 in IIS 6.0

• Register a scriptmap for the application that associates it with the .NET Framework version that you want to run the application under.

  For information about how to update scriptmaps for an ASP.NET application, see ASP.NET IIS Registration Tool (Aspnet_regiis.exe). For more information about IIS configuration in IIS 6.0, see Setting Application Mappings in IIS 6.0 (IIS 6.0).

See Also

Tasks

How to: Troubleshoot Unsuccessful Visual Studio Project Upgrades

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

How to: Deploy Web Projects Targeted for Earlier Versions of the .NET Framework

Concepts

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

ASP.NET Side-by-Side Execution Overview

Other Resources

ASP.NET 4 Breaking Changes