Compiling Web Application Projects 

The Web application project type provides an alternative to the Web site project type that was introduced in Visual Studio 2005. This new project model, which is based on the Visual Studio .NET 2003 Web project model, was created to simplify the conversion of Visual Studio .NET 2003 Web projects to Visual Studio 2005 and to reduce the need for code changes. Code files in the project are precompiled into a single assembly by using the Microsoft Build Engine (MSBuild). ASP.NET Web pages (.aspx) and user controls (.ascx) are compiled dynamically on the server by the ASP.NET compiler.

Compilation Model

The compilation model for Web application projects resembles the Visual Studio .NET 2003 compilation model. All code files (stand-alone, code-behind, and designer class files) in the project are precompiled into a single assembly that is built and persisted by default in the Bin folder. Because this compilation model creates a single assembly, you can specify attributes, such as assembly name and version, and the location of the output assembly.

A Web application project is defined by a project file instead of a project folder, which is used to define a Web site project. The project file contains the files that are included in the project as well as the assembly references and other project metadata settings. Files contained in the project folder that are not defined in the project file will not be compiled as part of the Web application project. Project settings that are added and changed through Visual Studio are reflected in the project file (.*proj) that is generated for each project.

To run and debug pages, you must compile the complete Web application project. Building the complete Web application project can be fast because Visual Studio uses an incremental build model that builds only the files that have changed.

For more information about Web application projects, see Web Application Projects Overview.

Precompilation of Class Files

Web application projects use MSBuild to precompile class files. These class files are compiled into a single assembly and put in the Bin folder by default. The compilation process can be extended and customized using standard MSBuild extensibility rules. For more information about MSBuild, see MSBuild Overview.

Web application projects enable you to precompile the classes of an application into a single assembly. The following table describes the types of Web application project class files that are compiled into a single assembly.

Class File Type Description


Class files that you can create and add to the Bin folder.

Code behind

User-defined code that directly relates to content files.


Code that is auto-generated. You should not modify the designer file.

You can also control the build through the property pages. For example, you can name the output assembly or add pre-build and post-build actions during the build process. Additionally, you can control which class files will be included for compilation based on the Build Action file property.

Customizing Compilation Options

The property pages of Web application projects can be used to modify the compilation characteristics of your Web application. You can specify the output assembly name, version, and other details by using elements of the Application property page of the Project Designer. Use the Build page of the Project Designer to specify the project's build configuration. For instance, you can set the way errors are handled and details about the assembly output. Also, you can add pre-build and post-build steps during compilation by setting values of the Build Events property page of the Project Designer. For more information about property pages, see Projects, User Interface Elements.

Setting the Build Action Property

By default, MSBuild only compiles class files of Web application projects that have the Build Action property set to Compile. However, if a class file is located in the App_Code folder of the Web application project, it will also be compiled by the ASP.NET compiler. This is because the ASP.NET compiler does not support the Build Action property of files that are contained in the App_Code folder. Also, the App_Code folder is not typically included in Web application projects.

Note   The App_Code folder exists for Web site projects in Visual Studio 2005. This folder is not typically included in Web Application Projects. For more information about the App_Code folder, see Shared Code Folders in ASP.NET Web Sites.

Dynamic Compilation

Although code files in the project are precompiled into a single assembly by using MSBuild, ASP.NET Web pages (.aspx) and user controls (.ascx) of a Web application project are compiled dynamically on the server by the ASP.NET compiler. In a Web application project, Web pages and user controls use the CodeBehind attribute and the Inherits attribute. The CodeBehind attribute points to the code-behind file to use. The Inherits attribute points to a namespace and class in the code-behind file.


If you change the root namespace of a Web application project, be sure to update the Inherits attribute in the .aspx page to appropriately match the namespace.

In Web application projects, you can make limited changes to the ASP.NET Web pages in your site after compiling and deploying them. For example, you can change the arrangement of controls, colors, fonts, and other appearance aspects of pages. You can also add controls, as long as they do not require event handlers or other code. When the site first runs, ASP.NET performs additional compilation in order to create output from the markup.

If you need to customize the declaration of a control within a Web application project, you should move the control declaration out of the designer file and into the code-behind file. Moving the declaration of a control to the code-behind file is useful in the following situations:

  • When the control needs to be typed differently.

  • When you want a scope for the control other than the default scope.

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

  • When you need to write specific XML comments for the declaration of the control.

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


Because all class files are compiled into a single assembly, only that assembly must be deployed, together with the .aspx and .ascx files and other static content files. In this model, .aspx files are not compiled until they requested by the browser. However, when it is used with Web Deployment Projects, which is a downloadable add-in to Visual Studio 2005, the .aspx files can also be compiled and included in a single assembly for deployment. To download this add-in, see Visual Studio 2005 Web Deployment Projects on the ASP.NET Developer Center. For more information about how to deploy Web application projects, see How to: Publish Web Application Projects.

See Also

Community Additions