ASP.NET 2.0 Migration Overview
Many of the programming concepts used in earlier versions of ASP.NET remain the same in ASP.NET version 2.0, so developing applications in ASP.NET 2.0 will be familiar for users of ASP.NET 1.x. ASP.NET 2.0 will run on the same operating systems and hardware that you use to run your ASP.NET 1.x applications, including Microsoft Windows 2000 and Microsoft Internet Information Services (IIS) 5.0, Microsoft Windows XP and IIS 5.1, and Microsoft Windows Server 2003 and IIS 6.0.
If you have an existing Web application that you have decided to migrate to ASP.NET, you should review the new features of ASP.NET 2.0 before migrating. The most important changes involve the page code-behind model, the Web application folder structure, and the page compilation model.
Before migrating you should ensure that your ASP.NET 1.x application can be compiled and run on the .NET Framework version it was developed on. Additionally, before starting migration, ensure that the Microsoft .NET Framework version 2.0 is installed and working.
This topic covers general considerations that should be taken into account before migrating. The following sections are discussed in this topic:
Benefits to Migrating
Page Models
Sharing Data Across ASP.NET Versions
Forms Authentication Across ASP.NET Versions
Name Conflicts
Markup Compliance
HttpOnly and Cross-Site Scripting
Benefits to Migrating
There are many benefits to migrating your Web application to ASP.NET 2.0, including improved markup and code separation, reserved application folders, and automatic code compilation.
The new code-behind model based on partial classes allows greater separation of markup and code, and removes the need for control declarations and event wire-up code in your code-behind files. In the ASP.NET page compilation model, code-behind files are compiled at run time into multiple assemblies on first request to the corresponding .aspx files.
ASP.NET now uses an improved Web application structure based on reserved folders. These folders contain specific content to help you organize your application more efficiently. Some reserved folders, such as App_Data, do not serve their content in response to Web requests but can be accessed from application code. For more information, see ASP.NET Web Site Structure.
The ASP.NET 2.0 compiler automatically compiles application code and dependent resources when a request is made to a resource on your Web site. For example, changes to an existing Web page or dependent resources in ASP.NET 2.0 can simply be saved and the page requested again for the page and its resources to be recompiled. This applies to resources like code files in the App_Code folder, resource files in the App_GlobalResources and App_LocalResources folders, and themes in the App_Themes folder. For more information about the page compilation model, see ASP.NET Compilation Overview.
If you are migrating a large application, it is recommended you use Visual Web Developer 2005, Visual Web Developer 2005 Express Edition, Visual Studio 2005, or Visual Studio 2005 Team System, each of which has a migration wizard that automates many of the tasks involved in a typical migration. The wizard makes the necessary changes to convert ASP.NET 1.x Web applications to ASP.NET 2.0.
It is not necessary to migrate Web applications because ASP.NET 2.0 provides a high degree of backward compatibility with earlier versions. If you do not migrate, you can still use many of the features of ASP.NET 2.0 in your Web application, as long as your application uses the .NET Framework 2.0. To configure your existing Web application to use the .NET Framework 2.0, see How to: Run ASP.NET 1.x Applications in the .NET Framework 2.0.
Page Models
The ASP.NET code-behind Web page model enables you to store the markup of a Web page in one file – the .aspx file – and the programming code in another file – the code-behind file. The code-behind model for ASP.NET 2.0 is different than earlier versions in that it uses a new language feature known as partial classes. The new code-behind model in ASP.NET 2.0 allows even greater separation of markup and code than earlier versions of ASP.NET.
Web pages that use the old code-behind model based on the CodeBehind attribute of the @ Page directive will continue to work in ASP.NET 2.0. However, it is recommended that you migrate these pages to the new code-behind model using the CodeFile attribute of the @ Page directive and a partial class definition in the code-behind file to take advantage of improved markup and code separation as well as automatic page compilation. Web pages that use the old code-behind model must be manually compiled.
You can make the changes manually, as described in How to: Migrate an ASP.NET 1.1 Web Page Using the CodeBehind Attribute to ASP.NET 2.0, or you can use one of the Microsoft Visual Studio 2005 editions that includes a migration wizard, such as Visual Web Developer 2005 Express Edition.
ASP.NET version 1.1 also supports a variant of the code-behind model in which the CodeBehind attribute of the @ Page directive was replaced with the Src attribute. A Web page using the Src attribute will continue to work in ASP.NET 2.0 and does not require modification to run.
As an alternative to the code-behind model, the single-file page model places the page's markup and programming code in the same physical .aspx file. Single-file pages from earlier versions of ASP.NET will continue to work in ASP.NET 2.0 and do not require modification to run.
Sharing Data Across ASP.NET Versions
You can choose to migrate some parts of your Web site to ASP.NET 2.0 while leaving others unmodified. If your Web site is divided into independent Web applications working together to provide your Web site functionality, you might decide to migrate some applications and not others. In this scenario, you will not be able to share application state between migrated applications and non-migrated applications. Session state will likewise not be shared across applications unless you provide a custom session state solution that can be accessed from both ASP.NET 1.x and ASP.NET 2.0 pages. For more information, see Implementing a Session-State Store Provider.
Forms Authentication Across ASP.NET Versions
Forms authentication provides you with a way to authenticate users using your own code and then maintain an authentication token in a cookie or in the page URL. ASP.NET forms authentication can be made to work across applications running different ASP.NET versions so that authentication tickets issued by one version can be consumed by the other.
Configuring authentication to work across ASP.NET versions is similar to the process of configuring authentication across a network of Web servers (a Web farm). In both cases, you explicitly set the validationKey and decryptionKey attributes of the machineKey element for the applications sharing authentication tickets with the same key. To support authentication across ASP.NET versions, you must make the additional configuration change of setting the decryption attribute of the machineKey element to 3DES in your ASP.NET 2.0 application's Web.config file. The default encryption for ASP.NET 2.0 is AES, whereas earlier versions of ASP.NET use 3DES. For more information, see ASP.NET Forms Authentication Overview.
Name Conflicts
Before migrating, it is recommended that you scan your Web application and look for names that conflict with feature classes and namespaces in the .NET Framework 2.0. Conflicts might occur when common names such as cache, membership, profile, and role are used in your Web application but are already in use in the .NET Framework. To avoid a naming conflict, locate references in your code to any names in question and use a fully qualified reference.
ASP.NET 2.0 uses a different Web site layout than earlier versions. To make it easier to work with Web applications, ASP.NET reserves certain folder and file names that you can use for specific types of content. Content in reserved folders is not served to Web requests made to it; this can lead to issues in your existing application. Therefore, before migrating individual application files it is recommended you change the names of any of your application folders or files that conflict with ASP.NET 2.0 reserved folder and file names. For more information about the reserved folders in ASP.NET Web site layouts, see ASP.NET Web Site Layout.
Markup Compliance
By default, all markup that is produced by ASP.NET and the Web server controls included with ASP.NET now conforms to the XHTML 1.0 Transitional standard. This can lead to unintended HTML rendering issues after migration. To help in migration of a Web application, you can set the mode attribute of the xhtmlConformance element to Legacy in your Web.config file. This should be a temporary step in the migration process. In the long term, it is recommended you run your application with the mode attribute of the xhtmlConformance element set to Transitional. Additionally, it is recommended that you add the DOCTYPE element to your migrated pages. For more information about the benefits of making Web pages XHTML-conformant, see ASP.NET and XHTML.
HttpOnly and Cross-Site Scripting
The HttpOnly property of the HttpCookie class is new in the .NET Framework 2.0. Setting this property to true can help mitigate cross-site scripting threats. The HttpOnly property is set to true automatically for forms authentication cookies and session ID cookies so that these cookies are not available to client-side scripting. If a migrated Web page throws a NullReferenceException exception, it might indicate that the session from the client was lost because the HttpOnly property was set to true. If this is the case, you can use one of the following resolutions:
Set the HttpOnly property of each cookie to false in the EndRequest event handler of the HttpApplication class in the Global.asax file.
Write a custom module that copies the cookie into another cookie, and clears the HttpOnly property so it can be manipulated by client script.
Write a custom session ID manager that does not set the HttpOnly property to true.
For more information about cross-site scripting mitigation, see Mitigating Cross-site Scripting with HTTP-only Cookies.
See Also
Concepts
Web Application Projects Overview
ASP.NET Forms Authentication Overview