ASP.NET Web Application Project Precompilation Overview

By default, code files in a web application project are precompiled into a single assembly by using the Microsoft Build Engine (MSBuild). ASP.NET web pages (.aspx), user controls (.ascx), and MVC Razor views (.cshtml and .vbhtml) are compiled dynamically on the server by the ASP.NET compiler. You can optionally precompile the web pages, user controls, and Razor views also.

Compilation Model

All code files (stand-alone, code-behind, and designer class files) in the project are precompiled into a single assembly. By default, this assembly is built and persisted in the Bin folder. Because this compilation model creates a single assembly, you can specify attributes, such as assembly name and version. You can also specify the location of the output assembly. To change the location of the output assembly, in Solution Explorer, right-click the project name, click Properties, and then click the Build tab. On the Build tab is a field named Output Path where you can specify the path to the output assembly.

A Web application project is defined by a project file instead of by a project folder, as is done for a Web site project. The project file references the files that are included in the project, and includes the assembly references and other project metadata settings. Files that are in the project folder but that are not defined in the project file are not compiled as part of the web application project. Project settings that are added and changed through Visual Studio or Visual Web Developer Express are referenced in the project file (.*proj) that is generated for each project.

To run and debug pages, you must compile the complete web application project. However, building the complete Web application project can be fast because Visual Studio and Visual Web Developer Express use an incremental build model that builds only the files that have changed.

For more information, see ASP.NET Web Application Projects.

Compiling Class Files

Web application projects use MSBuild to compile class files. These class files are compiled into a single assembly. By default, they are put in the Bin folder. You can extend and customize the compilation process by using standard MSBuild extensibility rules. For more information, see MSBuild.

The following table describes the types of web application project class files that are compiled into a single assembly.

Customizing Compilation Options

You can specify the output assembly name, version, and other details by using elements of the Application property page of the Project Designer window. Use the Build page in the Project Designer window to specify the project's build configuration. For example, you can specify how errors are handled and specify details about the assembly output. In addition, you can add pre-build and post-build steps during compilation by setting values of the Build Events property page. For more information about property pages, see Project Designer User Interface Reference.

Setting the Build Action Property

By default, only class files of Web application projects are compiled by MSBuild when the Build Action property is set to Compile. However, if a web application project includes class files in the App_Code folder, those class files will be compiled by ASP.NET. This is true even if their build action is not explicitly set to Compile.

Dynamic Compilation

Although code files in the project are precompiled into a single assembly by using MSBuild, ASP.NET web pages (.aspx), user controls (.ascx), and MVC Razor views (.cshtml and .vbhtml) of a web application project are compiled dynamically on the server by the ASP.NET compiler. This means that you can make limited changes to the ASP.NET web pages, user controls, and Razor Views in your site after they have been compiled and deployed. For example, you can change the arrangement of controls, colors, fonts, and other appearance aspects of pages. When the site receives its first request for a page after you have made such a change, ASP.NET recompiles the changed files.

You can define a control in the code-behind file as long as you make it protected or public. Because the .aspx page inherits from the code-behind file, the page will use that control. Moving the definition of a control to the code-behind file is useful in the following situations:

• When the type of the control must be derived from a built-in ASP.NET type.

• When you want a scope for the control other than the default scope. Scope refers to accessibility level, such as public, private, internal, protected, and protected internal.

• When you want to add metadata attributes to the declaration of the control.

• When you want to write XML code comments for the declaration of the control.

For more information about how to add controls, see How to: Add Controls to an ASP.NET Web Page Programmatically.

Deployment

By default, all class files are compiled into a single assembly, which means that only that assembly has to be deployed, together with .aspx, .ascx, .cshtml, and .vbhtml files and static content files. In this scenario, the markup in .aspx, .ascx, .cshtml, and .vbhtml files is not compiled into runnable code until the page is requested by the browser.

However, you can specify different compile and merge options. For example, you can precompile.aspx files or you can specify that multiple assemblies should be created instead of just one. For more information about web application project compile and merge options and how to specify them, see the following resources:

• Package/Publish Web Tab, Project Properties

• Advanced Precompile Settings Dialog Box

For information about how to deploy web application projects, see Web Deployment Content Map for Visual Studio and ASP.NET.

See Also

Concepts

Web Deployment Overview for Visual Studio and ASP.NET

Web Application Projects versus Web Site Projects in Visual Studio

Other Resources

Web Deployment Content Map for Visual Studio and ASP.NET

MSBuild