How to Upgrade VS Web Site Projects to VS Web Application Projects

Description:
My XAF solutions contain a Web Site Project. However, XAF now supports Web Application Projects. I want to migrate my existing XAF solutions to use new Web Application Projects.

Answer:
Before following the steps below, refer to the Introduction to Web Application Projects topic in MSDN. Note that XAF supports both Web Site and Web Application projects. So, you don't have to change your solutions if you don't desire.
Please follow the steps below in precise order. If you have problems using the steps below, please post a message to the Support Center, and XAF team members will be able to help.
Note: the sample I am using with the migration steps below is an empty solution, created using XAF v7.3, and upgraded using XAF v8.1.
Step 0: Install the VS Web Application Project Preview
If VS Web Application Project support is not built into your MS Visual Studio, install it. For this purpose, install either the Visual Studio 2005 Service Pack 1, or the Microsoft Visual Studio 2005 - Update to Support Web Application Projects and Visual Studio 2005 Web Application Projects.
Step 1: Create a New VS Web Application Project
The best strategy to migrate an existing VS Web Site Project is to first create a new blank VS Web Application Project in a separate directory of your XAF solution. This avoids changing any of the existing Web Site files, and will allow you to copy already implemented functionality.
To add a VS Web Application Project to an existing solution, right-click the solution node and select Add | New Project… . Name the project as you like (for instance, MySolution.Web_App), and select the language type you want to use.

Once you've added this new VS Web Application Project, delete the default.aspx and web.config files that are added to it by default (since you'll instead just copy your existing ones). A blank project will look like this:

Step 2: Setup Project References
Before migrating any code into your new VS Web Application Project, you should first make sure to setup any project or assembly references for it. You can see the list of default references with new VS Web Application Projects under the References node above. You can right-click on the References node to add new references to the project, as well as setup project-to-project references.
First, add references to your Module and Module.Web projects. Then, add references to all the assemblies that are listed in you Web Site Project's configuration file.

Once you have all of your references setup for the Web Application Project, right click the Project and choose Build (or just hit Ctrl-Shift-B). This will build the project and verify that any project to project references are working.
Step 3: Copy the files from the Web Site Project into the new Web Application Project
The easiest way to add your existing files from a VS Web Site Project is to simply select all the files in the Web Site Project (except for .bak and .log files), and copy and paste them into the new Web Application Project.
At this point none of the files have been converted, and the directory structure looks the same as it did in the Web Site Project.

One difference between a VS Web Site Project and a VS Web Application Project is that the VS Web Site Project Model dynamically generates the tool-generated partial class half page, and does not persist it on disk. On the other-hand, the VS Web Application Project model does save this partial class on disk within files that have a .designer.cs extension, and compiles it using the in-memory VS compilers when a build occurs (one benefit of this is faster build times).
Notice how the code-behind files for each page/user-control are still associated with the .aspx and .ascx content. However, no .designer.cs files have been generated.
As part of our next step, we will be converting these pages to persist their partial class declarations on disk within a .designer.cs file.
Step 4: Converting the Project Files
To convert pages and classes within the project, right-click the root node of the Web Application Project and select Convert to Web Application. This will cause VS to recursively examine every page in the project and automatically generate a .designer.cs file for each, as well as change the .aspx/.ascx files to use the "codebehind" rather than the "codefile" attribute. This command will also rename App_Code to Old_App_Code.
Select the WebApplication.cs file within the Old_App_Code directory and change its Build Action (in the Properties dialog) to Compile from Content.
VERY, VERY IMPORTANT: you can rename the Old_App_Code folder as you like, except for the previous name App_Code. Because ASP.NET 2.0 tries to dynamically compile any classes it finds in the App_Code directory of an application at runtime, you explicitly *DO NOT* want to store classes that you compile as part of your VS Web Application Project under an App_Code folder. If you do this, then the class will get compiled twice - once as part of the VS Web Application Project assembly, and then again at runtime by ASP.NET. The result will most likely be a "could not load type" runtime exception - caused because you have duplicated type names in your application. Instead, you should store your class files in any other directory of your project, other than one named App_Code.
When it's completed, your project will look as follows:

After all this has been done, build the project again to see if there are any compiling errors. The most likely cause of errors at this stage is "You are missing an assembly reference". If so, you should go to the reference manager and add the required reference.
Step 5: Running the Site
Once you have completed the steps above, you should be able to cleanly compile and run your application. By default, it will use the built-in VS Web Server to run the site. You can alternatively configure the project to use IIS instead. To manage these settings, right-click the Web Application project and pull up its project properties. You can then select the Web tab to configure these runtime settings:

Step 6: Rename the Web Application Project
So that all the namespaces used in the files you copied to the new Web Application Project are valid, rename the project to MySolution.Web. The name of the folder with the Web Application Project will remain, but the project will be renamed.

Step7: Remove the Old Web Site Project
Now, when everything works and you can run the new Web Application Project, remove the old Web Site Project.