Conversion Considerations

Before considering best practices for converting a Visual Studio .NET  2003 Web project to Visual Studio 2005 format, understand the benefits of conversion and decide whether it makes sense or not. The decision to convert is ultimately based on your particular application and situation.

 

If you have an application that is in production and is very infrequently updated, it may not make sense to convert it, as the benefits of doing so may be limited. If you choose not to convert your application to Visual Studio 2005 syntax, there are still two options to consider:

 

1.       Keep the application mapped to ASP.NET 1.1 (or 1.0) in IIS settings for that application's virtual directory. Continue to use Visual Studio .NET 2003 to edit the application code.

 

2.       Map the application to run under ASP.NET 2.0 in IIS settings, but do not upgrade the project format from Visual Studio .NET 2003. In this scenario, the application will benefit from several security and performance enhancements in ASP.NET 2.0, but you will need to continue to use Visual Studio .NET 2003 to edit the application code.

 

Note: you can run ASP.NET 1.1 and ASP.NET 2.0 applications side by side on the same IIS server.

 

The primary benefit of converting a Web application project to Visual Studio 2005 is the ability to use many new features in ASP.NET 2.0 (e.g., master pages, etc.) in your existing application. If you are looking to enhance an existing Web application built using Visual Studio .NET 2003, then upgrading to Visual Studio 2005 is most likely the right decision.

Expectations for Converting Web Projects

For relatively simple Web projects where a Web project is the only project in your Visual Studio .NET 2003 solution, conversion should be a relatively automatic process requiring little time or problem resolution.

 

If the application you are converting is of reasonable size and has several Web projects and additional projects, such as class libraries, in a single Visual Studio solution, it is possible to encounter issues during migration. Be prepared to spend the better part of a day completing the entire process. The steps and guidance provided in this article can help an informed user to migrate most applications of medium complexity.

 

Part 1: Prepare Your Visual Studio .NET 2002/2003 Web Projects for Conversion

Configuring Your Application in Visual Studio .NET 2003 When upgrading a project, it is recommended that you have Visual Studio .NET 2002/2003 and Visual Studio 2005 installed on the same machine.

 

When getting ready to migrate a Visual Studio .NET 2003 Web project, the first step is to make sure that it is configured and running properly in the Visual Studio .NET 2003 environment.

 

If you are upgrading an application with several projects in a solution, then ensure the entire solution builds and runs inside of Visual Studio .NET 2003 prior to migration. Even if you are upgrading an application represented by a single Web project, open the solution file to test and run the application in Visual Studio .NET 2003. To do so, in Visual Studio .NET 2003, click Open Solution.

 

Once the solution is open in Visual Studio .NET 2003, on the Build menu, click Build Solution to ensure that the application compiles without any errors.

 

To run the application, press F5 in Visual Studio .NET 2003 and make sure the application runs properly without any errors. Be sure to exercise pages in all Web projects in the solution to make sure that IIS is configured properly to serve the application pages.

 

Moving Excluded Files Outside of Web Projects One other step that can reduce potential issues down the road is to remove any excluded files from your Web project. If there are any files that are in your Web project folder structure that are not referenced by any of the Web projects in your solution, move those files into a separate location prior to migrating your solution.

 

To help discover such excluded files, you can use the Show All Files button in Solution Explorer.

 

Checking for Duplicate Project Files One other issue with project structure that may cause migration problem is that if you have multiple project files within the root folder of an IIS Web application. Generally, there is only one project file (*.vbproj or *.csproj) in the root folder of a given IIS Web application, but sometimes there are several project files.

 

A common reason to have multiple project files in the root of your IIS Web application is if you have a solution with multiple Web projects, each of which builds a separate set of pages in that Web application. This type of solution structure enables users to build a different set of pages into different assemblies within a single Web application. An example of such a structure is illustrated below:

 

If you have multiple Web projects in the same root folder of an IIS Web application, as long as each project doesn't include the same set of files, then you likely will not experience any issues during migration.

 

If you do reference the same set or subset of files within those multiple Web projects, then those common files will be migrated twice and will result in errors. This situation usually occurs if one has created a backup copy of an existing project file, thus resulting in two Web project files with the exact same set of files in them. If you have multiple Web projects files in the root of your Web application and they reference the same set of files, make sure to delete any project files that are not used by the solution to ensure the files in your Web project are not migrated twice.

 

Checking for Multiple Solutions Including the Same Web Project The recommended process is to migrate an entire Visual Studio solution together, although you may have several solutions that represent the application that you are migrating. In that situation, you would likely migrate each solution one at a time to convert your entire application to Visual Studio 2005. As an example, if the same Web project is included in two Visual Studio solutions and you attempt to upgrade both solutions, you will encounter an error when migrating the second solution.

 

To avoid this situation, migrate the first solution. When migrating the second solution, remove any Web projects from the second solution that were already migrated as part of the first solution's migration. Once the already migrated Web projects are removed, you can then migrate the second solution without any issues. Once the second solution is migrated, you can re-add the already migrated Web projects.

 Removing References to Web Projects

If you have a solution with multiple projects, it is also important to ensure that no references exist to any of the Web project(s) in your solution. An example of such a pattern would be if you have two Web

projects (WebProjectA and WebProjectB), where WebProjectB references WebProjectA to use some of the classes within WebProjectA.

 

This pattern, enabled in Visual Studio .NET 2003, will not work once the solution is migrated to Visual Studio 2005. Fortunately, you can modify your solution code to help avoid this situation. To do so, you

can use a model similar to the previous section by moving shared code into a class library and referencing it from there instead.

 

We'll use the simple example of WebProjectA and WebProjectB (which has a project reference to WebProjectA) to illustrate how to do this:

 

Add a new ClassLibrary project of the same language (Visual Basic or C#) to the solution using File > Add Project > New Project. For any classes in WebProjectA that are required by WebProjectB, copy those classes into the new Class Library project.

In WebProjectB, delete the reference to WebProjectA In WebProjectA and WebProjectB add a new "project reference" to the Class Library project created in step 3. Once you have restructured the solution using the guidance provided above, check to make sure the solution builds cleanly in Visual Studio .NET 2003. After the solution builds completely, run the entire application to make sure it is still fully functional.

 

Part 2: Migrate Your Web Projects

Running the Visual Studio 2005 Migration Wizard once you have restructured your Visual Studio .NET 2003 solution using the guidelines in Part 1 and have verified the entire solution builds and runs properly, it is now ready to be migrated to Visual Studio 2005.

 

When upgrading your application, the best practice is to migrate on the same machine as the one where it has been tested and run using Visual Studio .NET 2003. Visual Studio 2005 is fully installable side-by-side with Visual Studio .NET 2003 on the same machine, so you ought be able to install it on the same computer without any issues.

 

With Visual Studio 2005 installed on the same machine, upgrade the application by opening the solution file representing the application. Although it is possible to open individual projects and migrate them, the path of least resistance is to migrate the entire solution. To do so, click Open Project in Visual Studio 2005 and open the solution file (*.sln) representing the application you wish to upgrade. Doing so presents you with the following screen that indicates you are about to begin the migration process:

 

For best results, follow the defaults provided in this wizard to begin the migration.

 Making a Backup of Your Application

During the steps shown in the conversion wizard, pay closer attention to creating a backup copy of your solution. Double-check to make sure the Yes option is selected to create the backup, and make sure to note the backup location in case you want to restore the backup of the Visual Studio .Net 2002/2003 Web application in the future.

Part 3: Post-Migration Steps to Complete the Migration

Examining the Conversion Report Once the Conversion Wizard is finished, an XML report summarizing the results of the migration process is generated. Be sure to note the location of the XML file shown in the URL field at the top of the document window. Write down this location so that the XML conversion report can be referred to again after the file has been closed. In addition to the XML report that reports errors and warnings for all projects in the solution, each Web project contains a ConversionReport.txt file that has the same information for a particular Web project in the solution.

 

The XML report summarizes the results for each project in the solution. When collapsed, you can quickly determine how many warnings and errors were generated by each project in your solution. Expanding each section then details the warnings and errors for a particular project.

 

For the simplest of applications, the conversion report is likely to show successful migration for all of the projects in the solution. In most real-world situations with solutions of medium-to-large complexity, the more likely result is that some migration errors and warnings will be reported and will need to be investigated.

 

The following section describes the most efficient method to use when resolving issues that are reported.

 

Ensuring Compilation of Class Library Projects First As a general rule, the best method to use to work through any issues reported is to fix up each project in the solution, one at a time, beginning with the shared components first.

 

As an example, if you have Web projects in your solution that reference other projects (such as the class library project), then resolve any issues reported in the referenced projects first. To do so, with each project that is referenced by a Web project, right-click on that individual project and select Build Project to ensure that it compiles.

 

If the entire solution compiled cleanly in Visual Studio .NET 2003 prior to doing the conversion, the compile errors you will likely encounter in class library projects are conflicts with reserved keywords, or new types in the framework, and should be straightforward to fix. Fixing Conversion Errors and Warnings in Each Web Project Once you have fixed any errors reported in class library projects in your solution, the next step is to fix the errors and warnings reported in each Web project. For each Web project, use the following guideline as the approach for resolving issues found:

 

Review the warnings and errors reported by opening the conversionreport.txt file in the root folder of the Web project. This text file has sections titled Errors, Warnings and Comments found during migration. Review the Errors and Warnings sections and attempt to resolve the issues using the following methodology (the Comments section is mostly information and does not require any action):

If you see any warnings in the conversion file about previously "excluded" files being converted, it is recommended to remove those files first as they can result in many compilation errors that interfere with recognizing and fixing the other errors in the application.

To work through the remainder of the other errors and warnings reported in the conversionreport.txt file, see Common ASP.NET 2.0 Conversion Issues and Solutions for specific guidance on how to address each warning and error that can be reported.

 

After addressing any errors in the conversionreport.txt file, build the Web project to resolve any further compilation errors that may exist. To do so, select the root node of the Web site project you are working with, and on the Build menu, select Build Web Site. Once again, refer to Common ASP.NET 2.0 Conversion Issues and Solutions to identify any specific compilation errors that may be reported and to get guidance on how to fix them.

 

After you have resolved the reported issues and the Web project compiles successfully, there are two more recommended steps:

 

1.       It is likely that there are many *.resx files that are shown in the Web project that are no longer required. These files are easily identified by the same prefix name as an aspx or ascx file (e.g., default.aspx.resx). Visual Studio .NET 2003 created these resources files for every single page regardless of whether it was required. For most cases, these files are empty (or contain resources that are not used by the application) and can be deleted.

2.       Rename conversionreport.txt to conversionreport.webinfo. This is recommended because conversionreport.txt is viewable through a Web browser and might reveal sensitive information about your site. By renaming this file to conversionreport.webinfo, it is not accessible through a Web browser by default.

3.       Open the web.config file and turn batch compilation off and re-compile that application to see if any further compilation errors might exist. This can be done by setting the batch=false attribute in the

4.       compilation tag as such: <compilation debug="true" batch="false"/>. Turning off batch compilation may expose masked compilation errors that may exist in the application but are not reported.

 

Important: The batch=false attribute should only be added to find such errors and then reverted once any additional compilation errors are fixed. Leaving batch=false in the compilation section has significant performance impact on build times for the application in Visual Studio 2005, so make sure you remove this attribute after doing this check.

 

Fixing Runtime Issues in Each Web Project Once all class libraries and each Web project compile cleanly in Visual Studio 2005, the next step is to run the entire application and validate the functionality. As you test the application functionality, you may encounter some runtime exceptions that may be the result of breaking changes introduced between ASP.NET 1.1 and ASP.NET 2.0. Common ASP.NET 2.0 Conversion Issues and Solutions helps to identify such errors and fix them.

 

Part 4: Additional Information

The previous sections in this document describe the overall step-by-step process to convert Web project(s) from Visual Studio .NET 2003 to Visual Studio 2005. The following sections include additional

useful information:

 HTML / XHTML Validation Errors

You may come across validation errors being reported when ASPX and ASCX pages are open in the IDE. These additional errors may be reported by default because Visual Studio 2005 has stricter HTML validation based on the XHTML 1.1 standard.

 

These are not compilation errors, and should not affect the functionality of your application. If an ASPX or ASCX page is open, they appear in the same error list as compilation errors, and thus can add complexity by increasing the overall numbers of errors to review.

 

There are several things you can do to defer dealing with these validation errors.

 

Change the default validation in Visual Studio 2005 to "Internet Explorer 6.0". This can be done in the toolbar if an ASPX page is opened.  You can choose to keep the validation set to "Internet Explorer 6.0" if

it is unimportant to have XHTML compliance in your application. If you would like to ensure XHTML compliance, the recommendation is to set the validation to "Internet Explorer 6.0" during conversion, and once the conversion is completed, switch the validation to XHTML. Another trick is to close all open ASPX and ASCX pages once you have selected Build Website so the HTML validation errors are not intermixed with any compilation errors reported. This helps in identify which errors are related to site compilation versus which errors are simply validation issues in HTML. Opening Web Site Projects Using Local IIS Tab or Solution File In this article, we recommend that you open the solution file (*.sln) to open your Web projects. Doing so ensures that your Visual Studio .NET 2003 Web projects are opened as "Local IIS" projects within Visual Studio 2005 after conversion.

 

It is also possible to open a Web site project in Visual Studio 2005 by opening the project folder instead of opening the solution file. If you or others on your team decide to open projects in this manner, be sure any converted projects are opened using the Local IIS tab in Visual Studio 2005.

 

Hope this helps!

 

ASP.NET migration to asp.net 2.0