Common ASP.NET 2.0 Conversion Issues and Solutions

Article
06/30/2006

Michael Bundschuh
Program Manager, Microsoft

Robert McGovern
Infusion Development

July 2005

Applies to:
   ASP.NET 1.x
   ASP.NET 2.0
   Visual Studio 2005
   .NET Framework 2.0

Summary: Looks at some of the common conversion issues developers may face when upgrading from ASP.NET 1.x to 2.0 and shows how to avoid and/or fix those issues. (20 printed pages)

Introduction
Operational Changes
Converting an Application
Running the Wizard
The Conversion Report
Notification Types
What Changed?
Web Projects in Source Control
Common Conversion Issues
Updating the Server
Summary

Introduction

As you convert your ASP.NET 1.x applications to the new ASP.NET 2.0 framework, you may encounter issues related to the changes introduced by the 2.0 framework. In this article, we will look at both the conversion process and some of the common issues you may encounter during a conversion.

What Is ASP.NET 2.0?

ASP.NET 2.0 is a major update of the ASP.NET 1.x framework. Not only does ASP.NET 2.0 introduce many new features, it also fundamentally changes the way that an ASP.NET application is designed, compiled, and deployed. Although your ASP.NET 1.1 applications will run on ASP.NET 2.0 without recompiling, you will find that upgrading to use the new ASP.NET 2.0 features both simplifies your development and gives you more options for compiling and deploying your code. If you aren't familiar with ASP.NET 2.0, or the benefits of upgrading, please read Migrating from ASP.NET 1.x to ASP.NET 2.0.

With specific regard to upgrading an application, you will need to be aware of operational issues that affect how an application is compiled and deployed. You will also need to be aware of how new coding features affect your conversion and also give you opportunities to improve your application.

Operational Changes

Operational changes affect how you develop, configure, and deploy your ASP.NET applications. As either a developer or Web site administrator, you will need to be aware of these changes in order to properly build, deploy, and maintain ASP.NET 2.0 applications.

No project file. The most immediately noticeable difference between an ASP.NET 1.x application and a 2.0 application is the absence of the project file (e.g. *.vbproj or *.csproj). In a 1.x application, the project file contains build settings, references to external assemblies, and a list of files in the project. In a 2.0 application, the build settings and list of files are no longer necessary because all files in a Web project directory are considered part of the Web project.
Special directories. An ASP.NET 1.x application has one required directory (\bin) for containing assemblies. An ASP.NET 2.0 application has a larger defined directory structure. The new directories start with the prefix "App_" and are designed for storing resources, assemblies, source code, and other components. The new directory structure helps eliminate the need for a project file and also enables some new options for deployment.
Code-behind model. In ASP.NET 1.x, the code-behind model allowed separation of content (e.g. foo.aspx) from code (e.g. foo.aspx.vb). The content page inherited from the code-behind page and the code-behind page contained both user and designer generated code. ASP.NET 2.0 enhances the code-behind model by using partial classes, which allows a class to span multiple files. In the new code-behind model, the content page inherits from a compiled class consisting of its corresponding code-behind page plus an auto-generated stub file that defines the field declarations for the controls used in the content page. This change allows the auto-generated code to be separated from the user's code, and makes the code-behind page much smaller and cleaner. The partial class structure also reduces the risk of inadvertently breaking the page by editing designer generated code.
Compilation model (one assembly to many assemblies). In ASP.NET 1.x all the content pages, code-behind pages, and support code were precompiled into a single assembly with a fixed name. In ASP.NET 2.0, multiple assemblies are created on the fly (by default) with uniquely generated files names. For example, each ASPX page (consisting of a content page, code-behind page, and hidden designer page) is compiled into its own assembly. The App_Code directory automatically compiles common source code into its own separate assembly. This new compilation model causes some changes in the structure of an ASP.NET application, but greatly enhances the options for deployment and how the Web application is served on the Web server.
Deployment options (precompile, full compile, updateable sites, etc). In ASP.NET 1.x, Web applications were precompiled and deployed as one large assembly. Content pages (e.g. *.aspx) are not compiled and could be edited on the server. Thanks to the new page compilation model and directory structure, you can deploy an ASP.NET 2.0 application in many different configurations. At one extreme, you can precompile all the ASPX pages and deploy a Web application that consists of fully compiled assemblies. In this mode, your application cannot easily be changed on the server. At the other extreme, you can deploy an application with no precompiled code. In this configuration, you can change the .aspx pages, code-behind files, or any other code in the application on the server directly. The pages will be dynamically compiled when a user asks for the page from the server.

Each of these changes may require you to modify your application architecture and deployment process either before or after converting your Web application.

New Features

Converting your Web application to ASP.NET 2.0 will make your application more powerful, flexible, and maintainable. Although this article focuses on the mechanics of converting your application, you can learn more about the new ASP.NET 2.0 features through the following links:

Feature Overview
This white paper will give you a good overview of the new features available with ASP.NET 2.0. If you are looking at leveraging ASP.NET 2.0 content on a site built with ASP.NET 1.x, you should read through this paper to see what is available for you.
Personalization
ASP.NET 2.0's personalization features, called Web Parts, let you design your Web site to be reactive to individual users. You can, for instance, let each user pick a site layout or color scheme and have that information preserved between visits. Web Parts allows you to provide personalization features with a minimal amount of new code.
Data Access
Not only has ADO.NET been updated for the .NET Framework 2.0, but ASP.NET 2.0 also now includes a new set of data source controls and features for data access.
Master Pages
In traditional ASP.NET, most developers struggle with designing a Web application framework that combines code reuse with flexibility. Master pages give the best of both worlds by introducing true inheritance. You can set up a master page that contains your header, footer, and navigation bar, and then create child pages that fill in the content while automatically inheriting the look, behaviors, and features of the master page.
ASP.NET Development Server
A stand-alone, development-only Web server is now bundled with Visual Studio 2005. This server, code-named "Cassini," allows users to develop and test their Web applications without having to have IIS installed on their development system. This server can be used only for development. When you deploy your application to production, you will need to use an IIS server configured with ASP.NET 2.0. You can find out more about Cassini by reading Web Servers in Visual Web Developer.

As a general rule, you will want to convert your ASP.NET 1.x application to ASP.NET 2.0 before trying to implement any new features. Every conversion is a two-step process. The first step is to achieve functional equivalence, and the second step is to leverage new features. Converting an ASP.NET application from 1.x to 2.0 is no different. First you want to get your application working in a 2.0 environment. Then you will want to evaluate your application to see where you want to leverage the new features and controls of ASP.NET 2.0.

Converting an Application

Converting an application from ASP.NET 1.x to ASP.NET 2.0 involves more than just changing a reference to the Framework version. In fact, there are three main areas of changes that impact how your application has to be structured:

An ASP.NET 2.0 Web application does not use a project file (.vbproj or .csproj). The project file contents have been eliminated or shifted to the web.config file.
The compilation model has changed in several ways. Not only has the relationship between the code-behind file and the ASPX page changed, but also the application is no longer compiled into a single assembly.
A new directory structure has been created to facilitate the new compilation model and deployment options. Resource files, references, code-behind files, and other code artifacts all have to be moved into their new directories.

Fortunately, many of the application changes imposed by the changes to the ASP.NET framework have been automated in the conversion wizard.

Planning Ahead

Before you convert your application, you should read through the common conversion issues section of this paper and then examine your application. You may find areas where you want to change your 1.1 code to help improve the conversion process. You may also want to look at the time and training required to convert your application and plan how you are going to update your servers to support ASP.NET 2.0.

Prerequisites

Before you can convert your application, you will need to make sure that:

Your developers all have access to Visual Studio 2005.
Your target servers have the .NET Framework 2.0 installed (note that the bundled ASP.NET Development Server is already configured with ASP.NET 2.0 so you can develop and run Web applications right away).
You have verified that all your existing ASP.NET 1.x applications are working correctly.

You can read about configuring a production server in the Updating the Server section at the end of this paper.

The Conversion Wizard

Visual Studio 2005 has a built-in conversion wizard that will help you convert your ASP.NET 1.x applications. This wizard automates many of the basic steps necessary to make your application meet the new structural and coding requirements built into ASP.NET 2.0.

Running the Wizard

The conversion wizard is automatically invoked whenever you open an ASP.NET 1.x Web application in Visual Studio 2005. The wizard detects the presence of a project file (e.g. *.vbproj or *.csproj) in the application directory and automatically starts the conversion process.

Figure 1. The Conversion Wizard

The first choice you have to make is whether to perform an in-place conversion or to create a backup of your application before conversion.

Figure 2. Backup your application

If you choose to create a backup, Visual Studio 2005 will automatically create a copy of your ASP.NET 1.x application in the directory of your choice.

Next, you will see a summary screen of the conversion process and have one last opportunity to back out of the conversion.

Figure 3. Summary screen

The conversion may take a few minutes, depending on the size of your application. However, when it completes you will see a message indicating that your code converted. You may also see a message about some warnings or errors. Warnings and errors occur when the conversion wizard made changes that may modify the behavior of your application, or when it can't completely update your application to ASP.NET 2.0.

Figure 4. Conversion completed

After the conversion is complete, you are ready to look at the conversion report to see if you have to perform any additional steps to complete your conversion from ASP.NET 1.x to 2.0.

The Conversion Report

When the conversion wizard finishes upgrading your project, it automatically generates both an XML and a text version of the conversion report before displaying the XML version. This report will show you any issues encountered by the wizard and code areas where you may need to take additional steps to complete the conversion.

Figure 5. Conversion report (click image to enlarge)

The report is divided into sections for each solution and project that was converted. The solution report will almost always be error free. However, the project sections may have multiple issues listed for each file in your project.

If you close the conversion report, you can always find a text version at the top level of your converted project.

Notification Types

Each item in the report falls into one of three categories:

Notification—A notification item simply informs you of an action taken by the wizard. You will see many notifications about files that were deleted or moved, and code that was deleted or commented out. As you'll see in the following sections, the wizard performs certain standard operations on every file. These operations are necessary for the conversion but do not require any additional effort from you.
Warning—A warning item is generated whenever the wizard has to take an action that may cause a behavioral change in your application. Warnings are items you want to review, but may not need to act on. For example, if the wizard has to change access level on a piece of code, you will see a warning. You should review the change to make sure it doesn't have any unintended consequences. Generally, however, you can simply review warnings and then ignore them.
Error—An error item is generated if the wizard encounters something that cannot be automatically converted. These items require your effort to complete the conversion. Generally, an error is something that will generate a compilation error if you try to run the application.

Keep in mind the conversion report is a log file describing the changes made to your Web project. Most of the notifications can be ignored unless you are really curious about what changes were made to your Web application. You should review errors and warning first since these items indicate places where you may need to change your code to complete the conversion.

What Changed?

The conversion wizard performs a series of checks and conversions on your ASP.NET 1.x application. These checks are all designed to automate the most common conversion tasks. However, the conversion wizard may not be able to completely convert your application. After reading about what the wizard can do, you should read through the common issues section of this paper to find out what may be left to do.

Changes in the Code-Behind Files

In ASP.NET 1.x, the graphical components were typically separated from the coding components using an .aspx page and a code-behind file. The .aspx page is derived from the code-behind file. This means that you have to declare all your controls in both classes in order to properly wire up the callback events. The inheritance relationship also caused some problems with synchronizing the classes, especially when a developer made a change to the .aspx (such as adding a control), without making the necessary changes to the code-behind or recompiling the application.

In ASP.NET 2.0, the code separation model has changed, thanks to the advent of a concept known as the partial class. The partial keyword lets you split the code for a single class into two separate files. The code-behind file defines a partial class that contains user code. The designer will also generate a stub file containing a partial class that defines the field declarations for the controls used in the aspx page. When compiled, the .aspx page will derive from the combined partial classes, and be compiled into its own page assembly. This design reduces the risk of inadvertently breaking the page by editing designer-generated code.

Application Changes

The conversion wizard updates your application by:

Changing all CodeBehind attributes in your .aspx pages to CodeFile attributes.
Changing all code-behind class definitions to implement the Partial keyword.
Deleting all control declarations from the code-behind file if the controls are declared on the aspx page.
(C# only) Moving event hook up code from the InitialzeComponent function of the code-behind and into the aspx page. Note that this does not apply to automatically called events including Page_Init, Page_Load, Page_DataBind, Page_PreRender, Page_Unload, Page_Error, Page_AbortTransaction, and Page_CommitTransaction.

Standalone Code Files

In ASP.NET 1.x all your source code was compiled into a single assembly. This assembly was stored in the /bin directory of your application directory. In order to support the new compilation options and provide some enhancements with regards to deployment, ASP.NET 2.0 actually creates a single assembly for each ASP.NET Web page and user control. In addition, a separate assembly is created to hold all standalone code files (i.e. non-code-behind code files).

Application Changes

The conversion wizard updates your application by:

Moving all standalone code to the App_Code directory.
Changing all default, Friend, and Internal scope declarations to Public. This change is required because your code-behind files are no longer in the same assembly as the shared code. Therefore the access levels have to be changed to match the new multiple assembly structure.
Changing any Type.GetType() calls to System.Web.Compilation.BuildManager.GetType(). This new method automatically recognizes which assembly to look in to find the type of a class. If you tried to use Type.GetType() from a code-behind file, you would most likely encounter a TypeLoadException, since the code-behind file is in a different assembly than your stand-alone code.

Resources

Because of the new directory structure in ASP.NET 2.0, the location and storage of resource files has changed. Specifically, ASP.NET 2.0 applications now have an App_GlobalResources directory that is specifically designed to hold resource files. The conversion wizard will automatically relocate your required resource files into the appropriate places. Resource files associated with Web forms are no longer needed in ASP.NET 2.0 and are not modified.

Application Changes

The conversion wizard updates your application by moving all standalone resource files into the App_GlobalResources directory. All files in this directory are built into a single assembly.

Note that some additional code changes are required in order to access the resource files. These code changes are outlined in the Common Conversion Issues section on Resource Files.

References

In ASP.NET 1.x, there are three types of external assembly references:

Global Assembly Cache (GAC)—Your Web application depends on an assembly that is loaded in the system's GAC. The assembly reference is stored in the project file and the compiler will link your Web application to the assembly in the GAC at runtime.
Project-to-Project (P2P)— During a conversion, P2P references are maintained provided all the projects in the solution are converted at the same time.
Local—Your Web application depends on a file-based assembly created outside the Web project's solution. The assembly reference is stored in the project file and Visual Studio will copy a version of the assembly to the bin directory. If CopyLocal is set to true, the bin directory will be updated with the latest build of the assembly. The compiler will link your Web application to the assembly in the bin directory.

ASP.NET 2.0 uses the bin directory to store P2P and Local referenced assemblies. Not only does this directory contain the automatically generated assemblies for your application, it can also store any other executable code that your application needs to reference.

Application Changes

Because an ASP.NET 2.0 application doesn't have a project file, the references to external assemblies have to be moved.

GAC references are moved to the web.config file. For example:

<system.web>
  <compilation>
    <assemblies>
      <add assembly="EnvDTE, Version=8.0.0.0, Culture=neutral, 
           PublicKeyToken=B03F5F7F11D50A3A"/>
      </assemblies>
    </assemblies>
    ... Other tags
  </compilation>
  ... Other tags
</system.web>

A web.config reference to an assembly in the GAC

P2P references are stored in the solution file. During a conversion, P2P references stay as P2P provided that all of the projects in the solution are converted at the same time.
In the Beta 2 release of Visual Studio 2005, local referenced assemblies are not updatable. This behavior is fixed in the final release of Visual Studio 2005 with the addition of a Refresh file. This file is stored in the bin directory, and the file name is generated by taking the assembly name and appending ".refresh" to it. The Refresh file contains the path to the external referenced assembly, and its presence indicates to the compiler that this assembly and its dependent assemblies need to be refreshed (updated) if the original assembly has a later timestamp. This is analogous to the Copy Local behavior available in Visual Studio .NET 2003.

Both P2P and Local referenced assemblies are copied to the Bin directory.

Web References

Unlike regular references, Web references point to Web services. When you created a Web reference in an ASP.NET 1.x application in Visual Studio .NET 2003:

You created a directory under the Web References directory for your application
You created a reference class that contained proxy classes for every object defined in the WSDL for the Web service.
You created a discovery file called reference.map that contained information about how to build and update the Web reference.

ASP.NET 2.0 changes this process to account for the new directory structure and a few changes in the way that Web Services are handled in the .NET Framework 2.0.

Application changes

The conversion wizard updates your application by:

Moving all Web reference directories from the Web References directory to the App_WebReferences directory.
Putting a copy of the WSDL file in the App_Code directory. A build provider for the WSDL file will automatically generate Web service proxy classes that are compiled and accessible to any Web page because they are stored in the App_Code directory.
Deleting the proxy class generated by Visual Studio .NET 2003. The old 1.x proxy classes are no longer necessary because the proxies are now automatically generated in the App_Code directory.
Changing the .map extension from the discovery file to .discomap.

Web Services

In ASP.NET 1.x, Web services (.asmx) were automatically split into an empty front page (the .asmx) and a code-behind file that contained the actual methods.

Application changes

The conversion wizard updates your application by:

Moving the code-behind class to the App_Code directory so that it is automatically accessible to any ASP.NET page in your application.
Changing the CodeBehind attributes in the asmx file to point to the new location. (Note that the code-behind file does not use partial classes, hence the continued use of the CodeBehind attribute).
Changing all default, Friend, and Internal scope declarations to Public.

Global.Asax

In any ASP.NET application, you can use the Global.asax file to trap specific application-level events, including startup, shutdown, session lifecycle, request lifecycle, and error messages. This file, much like a Web service file, has a simple shell front page (.asax) and a code-behind file.

Application changes

The conversion wizard updates your application by:

Moving the code-behind file to the App_Code directory so that it is automatically available to any ASP.NET page in the application.
The "Code-behind" attribute is removed from the directive in the ASAX file.
(For Visual Basic) Adding a namespace statement to the class file. The namespace is defined by the root namespace in the Web project.

Data Sets

In ASP.NET 1.x, you generated typed DataSet objects using either the built-in wizard or the xsd.exe command line tool. The resulting proxy object was stored in the top-level directory. In ASP.NET 2.0, these DataSet objects are generated and stored differently.

Application changes

The conversion wizard changes your application by:

Moving the .xsd file (DataSet descriptor) to the App_Code directory. The runtime will automatically generate the typed data set from this file.
Deleting the old proxy files.

Web Projects in Source Control

The conversion wizard assumes that converting from ASP.NET 1.x to ASP.NET 2.0 is a big enough change that you will want to fork your development. Based on this assumption, the conversion wizard will check out your entire application before beginning the conversion, and then remove the resulting code from your source control tree. You will have to add your project back into your source control system after the conversion has completed.

Application changes

If your project is under a source control system integrated with Visual Studio 2005, the conversion wizard will:

Check out every file associated with the current project.
Perform the conversion.
Remove the resulting code from source control. Note that Microsoft FrontPage Web applications will remain in source code control (an artifact of how FrontPage works).
After conversion, you will need to add your site back into source control.

Common Conversion Issues

Although ASP.NET 2.0 is designed to work with code developed in ASP.NET 1.x, you may encounter one or more common conversion issues. In this section, we will look at several of the most common issues.

Code-Behind (CB-CB) Broken References

Note CB is an acronym for the code-behind file for either a Web form (*.aspx) or a user control (*.ascx).

The new ASP.NET 2.0 compilation model uses multiple assemblies that are normally dynamically compiled on the server. This model improves both Web site performance and updatability.

However, if your ASP.NET 1.x code-behind files reference another code-behind file, then you will have a broken reference because the referenced code-behind file will no longer be in the same assembly.

Here are some common ways it may be triggered:

Using LoadControl() and casting the result to another user control, for example
UserControl1 c1 = (UserControl1)LoadControl("~/UserControl1.ascx");
Creating an instance of the Web form class, for example
WebForm1 w1 = new WebForm1();
where WebForm1 is a class defined in a code-behind file for a Web form.

How to fix

To resolve the problem, you will need to change your application so the reference can be found. Since this is a CB-CB broken reference, the easiest way to resolve is to add a reference directive to the Web form or user control that is making the reference. This will tell the compiler what assembly to link to.

Let's assume you have the following situation:

Original ASP.NET 1.x Code

File (in WebAppRootFolder)	Code
Page1.ascx
- Page1.ascx.cs	Control1 c = (Control1)LoadControl("~/Control1.ascx");
Control1.ascx
- Control1.ascx.cs

Change your code to use a reference directive:

ASP.NET 2.0 version

File (in WebAppRootFolder)	Code
Page1.ascx	<%@ Reference Control="~/Control1.ascx" %>
- Page1.ascx.cs	Control1 c = (Control1)LoadControl("~/Control1.ascx");
Control1.ascx
- Control1.ascx.cs

By using the reference directive, you are explicitly telling the compiler where to look for the Web form or control you want to use. Note that in the final release of Visual Studio 2005 the conversion wizard will do this automatically for you.

Stand-alone class file (SA–CB) Broken Reference

Note SA is an acronym for a stand-alone class file.

You may encounter another type of broken reference if you have a stand-alone class file that references code in a code-behind file. This is similar to a CB-CB broken reference, except you have a stand-alone class file in the App_Code directory trying to reference a separate page assembly. Again, some common ways it can be triggered is with a LoadControl() call or creating an instance of the CB class.

How to fix

Fixing an SA-CB broken reference is much more involved. Since the problem occurs in an SA file, you cannot use a reference directive to find the reference. Also, after conversion, the SA file is moved to the App_Code directory so you only have access to the App_Code assembly when it is compiled.

The solution is to create an abstract base class in the App_Code directory to reference at compile time, which will load the actual class from the page assembly at run time.

Let's assume you have the following situation:

Original ASP.NET 1.x Code

File (in WebAppRootFolder)	Code
Control1.ascx	inherits="Control1"
- Control1.ascx.cs	class Control1 : System.Web.UI.Page { public void foo() { some code }}
Code1.cs	Control1 c = (Control1)LoadControl("~/Control1.ascx");

Change your code to use a reference directive:

ASP.NET 2.0 Version

File (in WebAppRootFolder)	Code
Control1.ascx	inherits="d_Control1"
- Control1.ascx.cs	class d_Control1 : Control1 { override public void foo() { some code }}
App_Code\Code1.cs	Control1 c = (Control1)LoadControl("~/Control1.ascx");
App_Code\Stub_Control1.cs	abstract class Control1 : System.Web.UI.Page { abstract public void foo(); }

The abstract base class will allow both standalone class files and CB files to find a class during compilation (named Control1 in this example) since it now exists in the App_Code directory. However, the standalone class file will use late-binding to load the original class (renamed to d_Control1 in this example) during runtime. Note, in the final release of Visual Studio 2005, the conversion wizard will create this code for you automatically.

Extra Types in a Code-behind File

In ASP.NET 1.x, it was possible to share types (e.g. structs, enums, interfaces, modules, etc.) across different pages by storing the types in a code-behind file for one of the Web forms or user controls.

This model breaks in ASP.NET 2.0 since a Web form and user controls are compiled into their own assemblies—the extra types will no longer be discoverable.

How to fix

After the conversion wizard has converted your application, just move any non-private extra type to its own standalone code file in the App_Code directory. You will also need to change the access modifier for the type to public since it has to work across assemblies. The shared type will automatically be compiled and discoverable throughout your Web application.

Note that in the final release of Visual Studio 2005 the conversion wizard will do this automatically for you. The generated standalone files will be in the Migrated sub-directory and will have a file name based on the file where the extra type was found and the name of the type that was found. Feel free to rename this file as you like, just keep it in the App_Code directory.

Multiple Web Projects in the Same Location

If you have multiple Web projects in the same solution that share the same directory location, Visual Studio 2005 will consider all files found in that location as part of a single Web application. Although the wizard will automatically move all assembly references to the web.config file, you may still encounter:

Naming clashes caused by the project merge.
Reference issues if one Web project referenced another and both were merged together.

How to fix

Separate your projects before converting them, that is, put them in their own separate directory location.

Ambiguous References and Naming Conflicts

The .NET Framework 2.0 adds a host of new namespaces and classes. Several of these are likely to cause clashes with ASP.NET 1.x applications. For example, the new personalization features introduce classes with the names of Profile, Membership, and MembershipUser. The Profile name in particular is fairly commonly used by developers who want to keep track of user information. Therefore if you have a Profile class in your application, and you try to use any of the new personalization features, you may encounter compiler warnings about ambiguous class references.

How to fix

Planning ahead for naming conflicts can be rather difficult. You will want to take a quick look through the new ASP.NET classes. If you see any names that might conflict with what you have in your application, you might consider using explicit naming. For example, use System.Web.Security.Membership instead of importing/using System.Web.Security and then using the Membership class.

Design View Issues

The new Visual Web Designer built into Visual Studio 2005 is more strict about proper HTML than Visual Studio .NET 2003. If your aspx page contains mismatched tags or poorly formed HTML, then the designer will not let you switch to design view inside Visual Studio 2005. Instead, you will be restricted to code view until you fix the problems. This issue occurs because of the new source code preservation and validation functions built into Visual Studio 2005.

How to fix

All you can do to avoid this issue is make sure that the tags in your aspx pages are well formed. If you encounter a problem switching from code view to design view post-conversion, then the problem is almost certainly a bad tag.

Event Handlers Called Multiple Times

Because of the way that the conversion wizard merges code-behind files and aspx pages, you may encounter scenarios where an automatically called event gets called twice (page load, for example). This scenario occurs if you had event wireup code in your code-behind file that wasn't in the InitializeComponent method. The conversion wizard is only smart enough to remove duplicate wireups if they are in the InitalizeComponent method.

You may have a difficult time noticing this error because in most cases a second event firing will be harmless. However, if you do discover that an automatically called event is occurring multiple times, you should examine your converted code-behind file to see if the handler has been wired to the event twice. If so, you will have to manually remove the second wireup.

How to fix

You can avoid this issue entirely by scanning your existing code and making sure that all event wireups are contained in the InitialzeComponent function for the code-behind file or by setting AutoEventWireUp=False in your page.

Error list error 'Error: Unable to parse file filename'

One of the more ambiguous errors you may see in a conversion report informs you that a file could not be parsed. There are actually many reasons for this error, including:

The page is not formatted correctly. If you have a malformed aspx page in your project, the wizard may not be able to read it or recognize it as an aspx page.
'Codebehind' attribute or 'src' attribute not found. If your aspx page doesn't contain either of these attributes, then the wizard can't find the matching code-behind file and can't convert the page. If this happens to a normal HTML page this error can be ignored. You will often encounter this error if your application has pure HTML pages that use the aspx extension.
Code-behind file not found. If your aspx page is supposed to have a code-behind file, but it isn't in the project directory, you may see this error. In this specific case, you will also see another error: 'Code-behind file filename not found'. Both errors relate to the same page. The first one indicates that the aspx part could not be processed and the second indicates that the code-behind file wasn't found.
File is listed in the project file (.csproj, .vbproj) but does not exist in the directory. ASP.NET project files can often become outdated if you add, delete, rename, or move content. If you are sure the listed file shouldn't be part of the project, you can ignore the error.

How to fix

To avoid these issues, make sure your project is complete and that all files listed in the project are present in the directory before starting conversion.

Code-behind Files Moved to the App_Code Directory

After the conversion wizard runs, you might find some of your code-behind files (e.g. *.aspx.cs or *.ascx.vb) moved to the App_Code directory. This indicates your content page has a malformed Codebehind directive and is not set correctly to the code-behind file. In other words, the conversion wizard wasn't able to determine that the code-behind file was actually tied to a specific aspx page.

The conversion wizard will automatically move all standalone class files (for example *.cs or *.vb) to the App_Code directory. If you have a malformed Codebehind directive, then the code-behind file will be considered a standalone class file and moved to the App_Code directory.

Note that Web service files, for example *.asmx and *.asmx.cs, are different from normal content pages and their code-behind page. The code-behind for a Web service file is meant to go in the App_Code directory, so if you find one there it is not an error.

How to fix

Prior to conversion, you can avoid this issue by making sure your Codebehind directive is correctly set in all your content pages.

After conversion, move the code-behind file to the same directory as the associated content page and correct the content page's Codefile (renamed in ASP.NET 2.0) directive to point to that code-behind file.

Excluded Files Are No Longer Excluded

In Visual Studio .NET 2003, you had to explicitly decide whether or not to include files in your Web project. If a file was not explicitly listed as included, then the file was excluded from the project. You could also stop a code file from being built by setting its build action to "none". This information is stored in the project file.

In Visual Studio 2005, all files found in the Web application directory are implicitly included as part of the Web project. Since there is no project file, there is no way to explicitly list files to be excluded or prevent them from being built into the project. As a result, your Web project may contain extra files that are now part of your project. Depending on the file's extension, the compiler may try to compile the file, which may cause conflicts in your application.

If you set a file's build action to "none", the conversion wizard will not convert the files. Since these files are considered excluded, the conversion wizard cannot determine whether the files are necessary or not. Therefore, the wizard logs a warning in the conversion report about files in the project structure that were not converted.

How to fix

If you want an excluded file to be converted, then prior to conversion, explicitly include it in your Web project and make sure its build action is not set to "none".

After conversion, you can delete any formerly excluded files you do not want from your project. You can also rename them with a safe extension such as ".exclude" to effectively remove them from your Web application. If you rename, they are still part of the Web project but they will not be compiled.

The final release of Visual Studio 2005 will contain a context menu item that will allow you to exclude and include files, using the rename mechanism. The final release will also contain changes that will stop excluded files from being published by Publish Web and command-line builds (MSBuild). ASP.NET will also be configured to not serve files with the exclude extension.

Partially Converted Solutions

In both ASP.NET 1.x and 2.0, it is possible to have a solution that contains both Web projects and client projects, for example a C# or Visual Basic class library or Windows application.

If you are using an express product, such as Visual Web Developer (VWD) or Visual Basic Express Edition, you will be able only to convert projects in the solution that relate to the express product. For example, if you are using VWD and open a solution with a Web project and a Visual Basic class library project, only the Web project will be converted, leaving you with a partially converted solution.

How to fix

You should use either the Standard, Professional, or Team System editions of Visual Studio 2005 to convert solutions containing multiple, mixed project types.

If that is not possible (you have only an express edition), then you should create a new solution containing only that project type.

Updating the Server

Before you can deploy your converted ASP.NET 2.0 Web application to a production server, you need to deploy the .NET Framework 2.0 to your target server. In this section of this article we will take a look at the steps to install the .NET Framework 2.0 and how to configure your applications to work with the framework once it has been deployed.

Deploying .NET Framework 2.0

The first step in using ASP.NET 2.0 is to deploy the updated .NET Framework. Because of the way that the .NET Framework is designed, you can deploy the 2.0 framework without disrupting a current installation of the 1.0 or 1.1 frameworks.

Acquiring the Framework

Currently, you can get the .NET Framework 2.0 installer directly from Microsoft. You can also find versions on the most recent MSDN DVDs if you are an MSDN subscriber. The installer is 22.4 MB.

Note that the framework installer is just the framework and does not include Visual Studio 2005. You will use this package to install the new framework on your servers. If you need to install the new framework on a developer machine, you should look into installing Visual Studio 2005, which also includes the .NET Framework 2.0.

The Go-Live License

If you are planning on using ASP.NET 2.0 on a production site, you will need to acquire the Microsoft Visual Studio 2005 Beta 2 Go-Live license. This license is an addendum to the terms of use that lets you deploy applications built with Visual Studio 2005 into production. Please go to the Visual Studio 2005 Beta 2 Go-Live License page to read the terms of the license, see a list of covered products, read about the limitations of the license, and sign the Go-Live license using a Microsoft passport account.

Installing the Framework

Once you've downloaded the framework, you need to install it on your target servers. Remember that the .NET Framework 2.0 is designed to be fully compatible with the 1.1 framework. In addition, installing the new framework will not disrupt any of your existing applications, as they will continue to run on the ASP.NET 1.1 framework until you specifically configure them to run on ASP.NET 2.0.

Configuring ASP.NET 2.0 with the IIS MMC Snap In

Once the framework is installed on your server and you have set up the basic extensions with IIS, your next set of choices involves assigning each of your ASP.NET applications to a specific .NET Framework version. By default, your 1.x applications will continue to use the 1.x framework. However, you will have to configure your converted applications to use the 2.0 framework.

ASP.NET 2.0 deploys a special Microsoft Management Console (MMC) snap-in for IIS that lets you decide which applications should use which versions of the .NET Framework.

Figure 6. MMC display of ASP.NET applications (click image to enlarge)

The MMC ASP.NET tab lets you to choose which version of ASP.NET your application uses and displays the Web.config location.

In addition to managing the framework version, the console has an Edit configuration button that lets you visually edit most of the Web.config or machine.config settings without having to directly manipulate the Web.config XML file. As an administrator, you will find that this MMC snap-in provides an incredibly useful tool for configuring and managing multiple ASP.NET applications on a single server.

Summary

Converting an application from ASP.NET 1.x to ASP.NET 2.0 is generally a smooth process. However, you have to make sure that your development and deployment environments are properly configured. You also have to evaluate your conversion report to make sure that your converted application will function properly. You may also wish to review your application ahead of time and plan ahead to avoid known issues with the conversion.

Coming in the .NET Framework 2.0 Final Release

The RTM version of the conversion wizard will follow the same basic process outlined here. However, specific details may change. For example, the RTM wizard may be able to better avoid some of the current known issues by automatically implementing the necessary changes.

Common ASP.NET 2.0 Conversion Issues and Solutions

Contents

Introduction

What Is ASP.NET 2.0?

Operational Changes

New Features

Converting an Application

Planning Ahead

Prerequisites

The Conversion Wizard

Running the Wizard

The Conversion Report

Notification Types

What Changed?

Changes in the Code-Behind Files

Application Changes

Standalone Code Files

Application Changes

Resources

Application Changes

References

Application Changes

Web References

Application changes

Web Services

Application changes

Global.Asax

Application changes

Data Sets

Application changes

Web Projects in Source Control

Application changes

Common Conversion Issues

Code-Behind (CB-CB) Broken References

How to fix

Stand-alone class file (SA–CB) Broken Reference

How to fix

Extra Types in a Code-behind File

How to fix

Multiple Web Projects in the Same Location

How to fix

Ambiguous References and Naming Conflicts

How to fix

Design View Issues

How to fix

Event Handlers Called Multiple Times

How to fix

Error list error 'Error: Unable to parse file filename'

How to fix

Code-behind Files Moved to the App_Code Directory

How to fix

Excluded Files Are No Longer Excluded

How to fix

Partially Converted Solutions

How to fix

Updating the Server

Deploying .NET Framework 2.0

Acquiring the Framework

The Go-Live License

Installing the Framework

Configuring ASP.NET 2.0 with the IIS MMC Snap In

Summary

Coming in the .NET Framework 2.0 Final Release

Additional resources