ASP.NET’s compilation system

Compilation in ASP.NET applications

First, let’s take a moment to revisit compilation in the context of ASP.NET applications. There are generally two types of compilation that typically take place in an ASP.NET application: project compilation, and runtime compilation.

Project compilation

This type of compilation is used by ASP.NET applications built using the project system approach, i.e. they have a .csproj/.vbproj file. Project compilation typically takes place in Visual Studio via the project system and msbuild. It compiles any C# or VB files in your project and produces an assembly in the project’s bin folder. This assembly is then deployed to your web server along with your application and is loaded by the ASP.NET runtime when your application starts. Note this assembly could also be built from the command line using msbuild directly, e.g. when on a continuous integration or build server.

Assets such as page, user control, and handler code-behind classes, controllers and embedded resources are built using project compilation. Typically the source code for these assets is not deployed to the server. Other asset types, including .aspx, .ascx, .ashx, .cshtml, and .vbhtml, are deployed to the server and built by the ASP.NET runtime itself using runtime compilation.

Runtime compilation

ASP.NET includes a full runtime compilation pipeline that compiles many of your application’s assets on the web server when the application is running (hence “runtime compilation). Even if you’re using the project compilation model detailed above, part of your application will be compiled using ASP.NET’s runtime compilation feature. If you’re using the “Web Site” model for your application (you chose File –> New Web Site… in Visual Studio and your application doesn’t have a .csproj/.vbproj file) your application is built exclusively using ASP.NET’s compilation system. In this model, your application will contain shared code files in the App_Code folder.

Page assets in your application such as .aspx, .ascx and .cshtml/.vbhtml files, are compiled in the following fashion:

• The file is parsed and turned into CodeDOM using the configured build provider
• The CodeDOM graph that represents the file is used to generate a string of C# or VB code using the configured CodeDOM provider (the code generation step)
• The C# or VB code is then compiled into an assembly using the configured CodeDOM provider (the code compilation step)
• The assembly is loaded into the application and optionally cached to disk in the Temporary ASP.NET Files folder

You can read more about ASP.NET’s compilation system on MSDN.

Runtime pre-compilation

To confuse matters slightly, you can elect to pre-compile the portions of your application that use the ASP.NET runtime compilation system before deployment, so that the compilation doesn’t take place at runtime. This is achieved using the ASP.NET Compilation Tool, aspnet_compiler.exe. This will produce assemblies that can be deployed along with your application in the bin folder and will remove the cost associated with compiling those assets when the application starts up. The tool is simply a wrapper around the runtime compilation feature and doesn’t use msbuild in any way. It will only compile the portions of your application that would’ve been compiled at runtime by ASP.NET, so if you’re using the project compilation model from above, you’ll still need to compile your application’s project using Visual Studio or msbuild.

You can read more about ASP.NET pre-compilation on MSDN.