Web Site project vs Web Application project in Visual Studio
Visual Studio offers two templates for ASP.NET on .NET Framework: ASP.NET Web Site (File › New › Web Site) and ASP.NET Web Application (File › New › Project). The pages look identical, but how the code is compiled and deployed differs, and mixing up the two explains many deployment errors.
Main differences
| Web Site project | Web Application project | |
|---|---|---|
| Project file | None; the folder is the project | .csproj lists every file |
| Page directive | CodeFile="Default.aspx.cs" | CodeBehind="Default.aspx.cs" |
| Compilation | On the server at run time (or precompiled at publish), often one assembly per folder or page | At build time into one assembly in bin |
| Deploy | Can copy source files; ASP.NET compiles them | Deploy the DLL and markup, not the .cs files |
| Shared code | Must live in App_Code | Anywhere in the project |
| Designer file | Generated on the fly | .aspx.designer.cs holds control declarations |
| Namespaces | Pages often have none | Standard project namespaces |
| Build events, references, MSBuild customisation | Limited | Full |
Consequences
- A Web Site can be edited on the server and the change takes effect at the next request: convenient for tiny sites, risky for anything else, because a typo becomes a run-time compilation error for users.
- A Web Application catches compile errors in Visual Studio, works with unit tests and CI builds, and deploys as a precise set of files.
- Deploying a Web Application's
.aspxfiles without its DLL, or a Web Site's pages without their.csfiles, produces "Could not load type" errors; see Parser Error when deploying.
Which is best?
For anything maintained by a team or deployed through a pipeline, the Web Application project. Microsoft's own Web Forms templates and tutorials use it, and it is the model that tools such as NuGet, MSBuild and publish profiles assume. The Web Site model remains supported for existing sites.
Converting a Web Site
- Create an empty Web Application project and copy the site's files into it.
- Move
App_Codeclasses to a normal folder (code inApp_Codewould be compiled twice). - Right-click the project and choose Convert to Web Application. Visual Studio changes
CodeFiletoCodeBehindand generates the designer files. - Add namespaces, fix references, build and test every page.
Spotting the type of an existing project
Open the folder: a .csproj or .vbproj file and .designer.cs files mean a Web Application; their absence, an App_Code folder and CodeFile= in page directives mean a Web Site. In Visual Studio, a Web Site appears in Solution Explorer with a path as its name and has no "Properties" node with build settings. Knowing which one you have tells you what to deploy and why a page may compile on one machine and not on another.
Official documentation
- Microsoft Learn: Web Application projects versus Web Site projects in Visual Studio
- Microsoft Learn: Page class