So you have a .Net website and want to convert it to a web application? Firstly, why might you want to do it?

  1. More strict compilation
  2. Better reference handling - for example, it will pull in dependencies of dependencies automatically
  3. More deployment options than just "xcopy"
  4. More clever incremental build i.e. won't always build everything every time.
Fortunately, the process is not too difficult, but there are some gotchas along the way. Assuming you are a fairly good developer, here are the steps in short format:

  1.  Build and run the current website to ensure there is nothing fundamentally broken
  2. Create a new empty web forms application of the correct language for the source web site (if you get this wrong, you will get some very weird compiler errors!).
  3. Delete any files and folders that get created with it and prune any nuget or references that you don't want.
  4. You can pre-emptively add any nuget and project references that you know you need or add them later when your compilation fails. You only need to add packages that are needed directly, it will automatically pull in dependencies of dependencies so don't just add everything that is currently in the old bin folder!
  5. Copy the old App_Code folder into the new project, with its contents (which you can do in Solution Explorer)
  6. Select all the code files and ensure their build action is set to "Compile", you can do this in one go with multi-select.
  7. Click on the web application project and then select Project->Convert to web application in the Visual Studio menu. This will rename App_Code to Old_App_Code, which it is supposed to, so don't rename it back.
  8. Perform your first build and fix any build errors. Depending on how loose your web site was written, there could be missing Import statements and problems with anything that is not defined correctly. Note, you can add global imports like Microsoft.VisualBasic into the project settings references section to avoid adding these into each page. Go sparingly though or you will have conflicts.
  9. Copy the remaining content over and then select all of your ASPXs etc. and choose Project->Convert to web application again, which should add a designer file and correctly order the files with the code-behind and designer hidden away. I had to do a lot of this manually but it might be because I missed a step.
  10. You will notice if a page does not have a designer file if you attempt to reference a page control from the code behind and it fails. Simply select the offending page and run Project->Convert to web application again.

Common Errors

Common errors include:
  • Having the wrong build action on a file
  • Not having fully-qualified namespaces in the Inherits attribute of an aspx page
  • Having duplicate class names which would have been namespaced differently in the web site and might now conflict. 
  • "Convert to web application" makes some changes to class names and namespaces, which might cause unexpected errors.
  • If your new project does not globally include namespaces that were included before, files might fail the build
  • If your new namespace is different, you might get unusual conflicts with types that worked before. Types in code files use relative namespace paths whereas Imports/using always use global (absolute) namespace paths. For example type A.B.ClassName referenced inside a class that is inside A.C either needs an Imports/using for A.B or a fully-qualified namespace of B.ClassName (note the missing A). This might have worked fine in the old namespace. 
  • Any times you have used tools like Resharper while migrating might have made incorrect changes - for example pointed ASPX pages to the wrong code file.
Note that like all Web Forms projects, the ASPX page errors will not fail the build by default so make sure you open each one and check for errors to be fixed before running your application.