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 version 4. 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 version 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 .NET Framework version 4
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.
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 version 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.