Share via


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.

Note

Do not upgrade an IIS application if it has nested applications within it that target earlier versions of the .NET Framework. If an IIS application that targets the .NET Framework 3.5 or earlier is nested within an IIS application that targets the .NET Framework 4, the compiler might report errors when it compiles the nested application. This is because Web.config files inherit settings from files that are higher in the configuration file hierarchy. The .NET Framework 4 is backward compatible; therefore, a nested Web application that targets the .NET Framework 4 can inherit settings from Web.config files that are for earlier versions. But earlier versions of the .NET Framework are not forward compatible; therefore, they cannot inherit settings from a .NET Framework 4 Web.config file.

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.

    Visual Studio Conversion Wizard dialog box

  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 Conversion Wizard 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.

    Visual Studio Conversion Wizard Ready 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.

    Project Target Framework Not Installed dialog box

  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.

    .NET Framework version selection Dialog Box

  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.

    Visual Studio Conversion Wizard Close 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.

    Turn Windows Features On or Off 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

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