Step-By-Step Guide to Converting Web Projects from Visual Studio .NET 2002/2003 to Visual Studio 2005

  • Article

 

Web Platform and Tools Team
Microsoft Corporation

July 2006

Summary: Walks you through the process of converting an existing Visual Studio .NET 2003 Web project to a Web application project in Visual Studio 2005 (7 printed pages)

Migrating a Visual Studio .NET 2003 Web Project to a Web Application Project
   Step 1: Install the Visual Studio 2005 Web Application Project Preview
   Step 2: Back Up Your Visual Studio .NET 2003 Projects
   Step 3: Open and Verify your Visual Studio .NET 2003 Web Project
   Step 4: Migrate the Solution to Visual Studio 2005
   Step 5: Verify in Visual Studio 2005
   Step 6: Covert Code-Behind Classes to Partial Classes
   Step 7: Examine and Resolve XHTML Compliance Issues
The Future of Web Application Projects

Migrating a Visual Studio .NET 2003 Web Project to a Web Application Project

This article walks you through the process of converting an existing Visual Studio .NET 2003 Web project to a Web application project in Visual Studio 2005. The Web application project model uses the same conceptual approach as a Web project in Visual Studio .NET 2003, including a project file to include and exclude files, compilation to a single assembly, and so on. In general, Web application projects do not require any architectural changes after the conversion.

This article assumes that you are working in C#. The steps for working with Visual Basic are very similar, but file names and some of the code will differ.

Step 1: Install the Visual Studio 2005 Web Application Project Preview

Be sure you have installed Web Application Projects in Visual Studio 2005 by following the steps in Installing Web Application Projects.

Step 2: Back Up Your Visual Studio .NET 2003 Projects

Make absolutely sure to save a backup of your Visual Studio .NET 2003 Web projects and solutions before attempting any migration. The following steps have been tested using the preview version of Web Application Projects. However, there could still be issues, and you might need to restore the Visual Studio .NET 2003 solution.

Step 3: Open and Verify your Visual Studio .NET 2003 Web Project

Before migrating a project, open your existing Visual Studio .NET 2003 solution, compile it, and then run it. Spending a few minutes to verify that everything works before you migrate can save trouble later, especially if the cause of errors is a last-minute directory change or similar.

Step 4: Migrate the Solution to Visual Studio 2005

Close the solution in Visual Studio .NET 2003, and then start Visual Studio 2005. On the File menu, click Open File, and then browse to the .sln file for the solution you want to migrate. This launches the Visual Studio 2005 Conversion wizard:

Aa479567.wap_11(en-us,MSDN.10).gif

Figure 1. Visual Studio 2005 conversion wizard

Click Next to proceed through the wizard, accepting all defaults. Visual Studio 2005 will convert the solution and its contained project files to use the MSBuild format, which is the new project file format in Visual Studio 2005.

As part of the migration, Visual Studio 2005 generates an XML-based log file that provides a summary of the conversion process, flagging any issues encountered during migration. By default, the conversion log file is saved in the same directory as the .sln file. If you have issues later when compiling the project, you might need to refer back to the conversion log file.

Step 5: Verify in Visual Studio 2005

After the solution and project files are upgraded to Visual Studio 2005 format, validate that your application builds without errors and runs as expected. At this point, the most common errors or warnings will be of these types:

  • Conflicts with names in introduced in the .NET Framework version 2.0.
  • Warnings about using obsolete members.

To fix naming conflicts, you can either fully qualify existing names with a namespace to remove ambiguity, or rename the members so they do not conflict.

If you see a warning about using obsolete members, the warning message will usually suggest alternative APIs to use. In these cases, you can continue to use the obsolete members in the 2.0 version of the .NET Framework. However, the members will be removed in the next major release of the .NET Framework, so it is a good practice to remove the members and substitute the suggested alternatives.

When running your Web application, you might see an error that says "Directory Listing Denied" that suggests that a virtual directory does not allow its contents to be listed. If you see this error message, do the following:

  1. Close the browser.
  2. In Solution Explorer, right-click the application's start page and then click Set as Start Page to ensure that the correct page is invoked when the application runs.
  3. Run the application again.

Step 6: Covert Code-Behind Classes to Partial Classes

As noted earlier, in Visual Studio 2005, Web application projects use partial classes to store designer-generated code. These classes are stored in a separate file from the code-behind file. By default, the Visual Studio 2005 Web project conversion wizard does not create a *.designer.cs (or *.designer.vb) file for Web pages (.aspx files) or user controls (.ascx files). Instead, the code will look and work just like it did in Visual Studio .NET 2003.

Note   The wizard makes the minimum number of changes to the code files during migration to help ensure a smooth conversion to Web application projects in Visual Studio 2005.

You can keep your code in this format. If you do, you must manually update the control field declarations in the code-behind files, but everything else will work fine in Visual Studio 2005.

To take advantage of the editor's ability to maintain field declarations in generated code, you should update your pages and controls to use the partial-class model introduced in ASP.NET 2.0. Partial classes make it easier to organize the generated code and custom code for your code-behind files. For more information on .designer.cs files, see Scenario 1: Creating a New Web Application Project.

To migrate your code to use partial-class model, first make sure that your code compiles without errors. Then in Solution Explorer, right-click the project name and click Convert to Web Application. This command iterates through each page and user control in the project, moves all control declarations to a .designer.cs file, and adds event handler declarations to the server-control markup in the .aspx and .ascx files.

Note   Another option is to use the Convert to Web Application command on individual pages. You might do this first on a few pages if you want to watch closely the changes made for each page before applying the change to the entire application.

Aa479567.wap_12(en-us,MSDN.10).gif

Figure 2. Converting a single page to Web application project format

When the process has finished, check the Task List window to see if any conversion errors are reported. If the task list displays errors, right-click the relevant page in Solution Explorer and choose View Code and View Code Gen File to examine the code and fix problems. Note that errors and warnings that appear in the Task List window persist between Visual Studio sessions. After you have fixed errors listed in the window, you can clear items from the task list.

Note   The Convert to Web Application command cannot be undone in Visual Studio. The best method for reverting the changes is to restore from a backup of the Visual Studio .NET 2003 project, and then to re-run the Visual Studio 2005 migration as described in Step 4 above.

Now recompile your project to ensure it compiles without errors. A possible source of errors is if you have modified the control declarations in a code-behind class and the conversion wizard mishandles your changes.

From this point, when you add new pages into your Web project, they will by default use the partial-class template.

Step 7: Examine and Resolve XHTML Compliance Issues

By default, Visual Studio 2005 generates and validates XHTML-compliant markup. This helps you build Web applications that are standards compliant and helps minimize issues with browser-specific rendering. Visual Studio .NET 2003 did not generate XHTML-compliant markup, so you might see validation and rendering issues with pages created in Visual Studio .NET 2003.

Note   Validation errors are informational only and are flagged as warnings. Validation errors do not prevent a page from running.

If you do not want to see validation errors, switch the HTML validation setting from XHTML Transitional to Internet Explorer 6.0 (which was the Visual Studio .NET 2003 default setting). In the Tools menu, click Options. In the Options dialog box, open the Text Editor node, then the HTML node, and then the Validation node. In the Target list, select Internet Explorer 6.0, and then unselect the Show Errors check box. Note that this does not fix XHTML validation errors; it simply switches the validation schema to one that is more compatible with the way markup was generated by Visual Studio .NET 2003, and it suppresses validation warnings.

Aa479567.wap_13(en-us,MSDN.10).gif

Figure 3. Configuring HTML validation

You can also add the following section to your project's Web.config file, which causes ASP.NET to render legacy (non-XHTML compliant) markup from server controls:

  <system.Web>
  <xhtmlConformance mode="Legacy" />
</system.Web>

This will avoid the slight rendering differences you might see between pages displayed using ASP.NET 1.1 and using ASP.NET 2.0. For more information, see ASP.NET and XHTML in the MSDN Library.

The Future of Web Application Projects

Web application projects provide a compilation and build model very similar to the one used in Visual Studio .NET 2003. Depending on their requirements, some users will find the new Web site project option in Visual Studio 2005 more appropriate for their applications, while other users will prefer the Web application project option. Web application projects provide the best path for upgrading existing Visual Studio .NET 2003 applications to Visual Studio 2005, and are highly recommended for that scenario.

We want to emphasize these important points about the future of Visual Studio 2005 Web application projects:

  • Going forward, we will fully support both the Visual Studio 2005 Web site project model and Visual Studio 2005 Web application project model. You can choose whichever model works best for you.
  • In future versions of Visual Studio, the Web application project model will be built in, and both the Web application project model and Web site project model will be supported.

© Microsoft Corporation. All rights reserved.