ASP.NET Web Site Project Precompilation Overview

You can precompile a Web site project before it is made available to users. This provides many advantages, which include faster initial response time, error checking, source-code protection, and efficient deployment. This is particularly important in large sites where there are frequent changes in Web pages and code files.

Note

This topic applies only to Web site projects. For information about the difference between Web application projects and Web site projects, see Web Application Projects versus Web Site Projects in Visual Studio. For information about how to precompile Web application projects, see ASP.NET Web Application Project Precompilation Overview

This topic contains the following sections.

• Overview
• Default Compilation
• In-Place Precompilation
• Precompilation for Deployment
• Precompiling for Deployment with Updatable UI
• Precompiling for Deployment with Non-Updatable UI
• Performing Precompilation
• Precompiling to Fixed-Name Assemblies
• Precompiling to Signed Assemblies
• File Handling During ASP.NET Precompilation
• Deploying and Updating Precompiled Web Sites
• Related Topics

Overview

By default, the Web pages and code files of a Web site project are compiled on the Web server dynamically when users first request a resource such as a page from the Web site. After pages and code files have been compiled the first time, the compiled resources are cached. Therefore, subsequent requests to the same page are very efficient. As an alternative to this dynamic compilation, you can precompile a Web site project.

Precompiling an ASP.NET Web site project provides the following advantages:

• Faster initial response time for users, because pages and code files do not have to be compiled the first time that they are requested. This is especially useful on large sites that are frequently updated.

• A means to identify compile-time bugs before users see a site. (You can also accomplish this when you compile a project in Visual Studio.)

• The ability to create a compiled version of the site that can be deployed to a production server without source code. This makes sure that that people who have access to the production server will not be able to view the source code.

ASP.NET offers the following options for precompiling a site:

• Precompiling a site in place. This option is useful for existing sites where you want to enhance performance and perform error checking.

• Precompiling a site for deployment. This option creates a special output that you can deploy to a production server. The files that you deploy to the production server can be made read-only or updatable. The following sections provide more details about each option.

Default Compilation

By default, ASP.NET compiles the application the first time a page in the application is requested by a Web browser. If you make a change to a file in the application, the next time a page is requested the ASP.NET runtime determines the dependencies of the changed file. ASP.NET then recompiles only the files that are affected by the change.

Use default compilation in the following situations:

• When you are developing and testing a Web site.

• For Web sites that have primarily static information.

• For Web sites that are not frequently changed.

However, do not use default compilation Web site in the following situations:

• When you are concerned about storing source-code files on the production server. (Anyone who has access to the folders that contain the Web site files will be able to see the source code).

• When you are concerned about possible delays when the first request is made to the Web site in production. (You should test the site determine if the delay is noticeable. For most sites it is not noticeable.)

In-Place Precompilation

When you perform in-place precompilation, all ASP.NET file types are compiled. (HTML files, graphics, and other non-ASP.NET static files are left as is.) The precompilation process follows the same logic that ASP.NET uses for dynamic compilation, accounting for dependencies between files. During precompilation, the compiler creates assemblies for all executable output and puts them in a special folder under the %SystemRoot%\Microsoft.NET\Framework\version\Temporary ASP.NET Files folder. Thereafter, ASP.NET fulfills requests for pages from the assemblies in this folder.

If you precompile the site again, only new or changed files are compiled (or those with dependencies on new or changed files). Because of this compiler optimization, it is practical to compile the site after even minor updates.

Use in-place compilation in the following situation:

• You make frequent changes to pages on the Web site and you don't want to have to redeploy the site each time you make a change.

• When you are concerned about storing source-code files on the production server. (Anyone who has access to the folders that contain the Web site files will be able to see the source code).

• When you are concerned about possible delays when the first request is made to the Web site in production. (You should test the site determine if the delay is noticeable.)

Precompilation for Deployment

Another use for precompiling a site is to produce an executable version of the site that can be deployed to a production server. Precompiling for deployment creates output in the form of a layout. The layout contains assemblies, configuration information, information about the site's folders, and static files (such as HTML files and graphics).

After compiling the site, you can deploy the layout to a production server by using tools such as the Windows XCopy command, FTP, Windows installation, and so on. After the layout is deployed, it functions as the site, and ASP.NET fulfills requests for pages from the assemblies in the layout.

For more information about how the compiler works with files during compilation for deployment, see File Handling During Site Compilation for Deployment later in this topic.

Precompile a project for deployment in the following situations:

• When you are concerned about storing source-code files on the production server. (Anyone who has access to the folders that contain the Web site files will be able to see the source code).

• When you are concerned about possible delays when the first request is made to the Web site in production. (You should test the site determine if the delay is noticeable.)

• The extra work of performing a separate compilation step before deployment to production servers does not outweigh the advantages of precompilation.

You can precompile for deployment in two ways: precompiling with updatable UI or precompiling with non-updatable UI.

Precompiling for Deployment with Updatable UI

When you precompile for deployment and update, the compiler produces assemblies from all source code (except page code in single-file pages) and from other files that ordinarily produce assemblies, such as resource files. The compiler converts .aspx files into single files that use the compiled code-behind model and copies them to the layout.

This option enables you to make limited changes to the ASP.NET Web pages in the site after you compile them. For example, you can change the arrangement of controls, colors, fonts, and other appearance aspects of pages.

When the site runs the first time, ASP.NET performs additional compilation in order to create output from the markup.

Use precompilation for deployment with updatable UI in the following situation:

• You want to be able to modify the markup in .aspx pages without requiring the whole Web site to be recompiled. Typically, this is an advantage only for very large sites for which compilation takes a significant amount of time.

• You are not concerned about storing some of your source code on the production server.

Precompiling for Deployment with Non-Updatable UI

When you precompile for deployment only, the compiler produces assemblies from almost all ASP.NET source files that are ordinarily compiled at run time. This includes program code in pages, .cs and .vb class files, other code files, and resource files. The compiler removes all source and markup from the output. In the resulting layout, compiled files are generated for each .aspx file (with the extension .compiled) that contains pointers to the appropriate assembly for that page.

To change the Web site, which includes the layout of pages, you must change the original files, recompile the site, and redeploy the layout. The only exception is the site configuration. You can make changes to the Web.config file on the production server without having to recompile the site.

This option provides the greatest degree of protection for source code and the best performance at startup.

Precompile the Web site to have non-updatable UI in the following situations:

• Your UI code contains intellectual property that you want to protect from people who have access to the production server.

• You do not have to change the UI often.

• You want to have only compiled DLLs on the production server.

Performing Precompilation

You can precompile a Web site using the Aspnet_compiler.exe tool on the command line. For more information, see ASP.NET Compilation Tool (Aspnet_compiler.exe). You can also precompile a Web site project in Visual Studio by selecting Publish Web Site from the Build menu.

Note

Precompiling a Web site compiles only that site, not any child sites. If a Web site contains a subfolder that is marked as an application in IIS, the child application is not compiled when you precompile the parent folder.

One coding restriction when you precompile a Web site applies to sites that you intend to compile with source protection enabled. It is possible for a base page class (a code-behind class) to reference the associated page class (.aspx file) and page class members by using a fully qualified class name. However, this kind of reference will not work when you precompile the site with source protection enabled. This is because the base page class from the code-behind file is not located in the same assembly as the page class derived from the .aspx page. For more information about precompilation with source protection enabled, see How to: Sign Assemblies for Precompiled Web Site Projects.

Precompiling to Fixed-Name Assemblies

The ASP.NET compilation tool uses random names for the assemblies that are generated during compilation. The name of the assembly changes every time that the application is recompiled.

Because the assembly names change, you must redeploy the whole application to service one assembly. However, by using the -fixednames switch with the ASP.NET compilation tool, you can create one assembly for each page in the application. The name of the assembly will not change on subsequent compilations. Therefore, you can create service releases of the application that replace only the changed assemblies.

Because the -fixednames switch creates an individual assembly for each page or user control (.aspx, .ascx, and .master files), the performance of a site with a large number of pages might be adversely affected. (Themes and skin files, along with other folders that do not contain pages or user controls, will continue to be compiled to a single assembly.)

For more information about this precompilation method, see How to: Generate Fixed Names with the ASP.NET Compilation Tool.

Precompile the Web site to fixed-name assemblies in the following situation:

• You want to be able to update individual .dll files in Web applications without replacing all of them.

• The number of Web pages in the application is not so great that creating a .dll file for each of them would degrade the site's performance.

Precompiling to Signed Assemblies

You can use the ASP.NET compilation tool to create strong-named assemblies that can be deployed to the server's Global Assembly Cache (GAC) or to the Bin directory of the application. A signed assembly makes it more difficult for malicious users to replace the application's assemblies with malicious code.

Assemblies must have the AllowPartiallyTrustedCallersAttribute attribute to be called by the ASP.NET runtime.

For more information about this compilation method, see How to: Sign Assemblies for Precompiled Web Site Projects.

Precompile the Web site to signed assemblies in the following situations:

• Users have access to the application directory or GAC, and they can replace the application's assemblies.

• You want to limit the ability of third parties to replace the assemblies generated by the application code.

• The difficulty that can be caused by the complexity of key management in shared development environments does can outweigh the advantages of signed assemblies.

File Handling During ASP.NET Precompilation

When you precompile a site for deployment, ASP.NET creates a layout, which is a structure that contains the compiler output. This section describes how files are handled during precompilation and describes the layout structure and contents.

You can precompile both source code (any file that produces an assembly, which includes program code and resources) and markup (.aspx files), or only source code.

Compiled Files

The precompilation process performs actions on various types of files in an ASP.NET Web application. Files are treated differently depending on whether the application is being precompiled for deployment only or if it is being precompiled for deployment and update.

Note

Precompiling a site only for deployment or for deployment and update does not preserve file access control lists (ACLs) on target files and subdirectories. For example, if you have previously precompiled a site and deployed it to a target location, changed a file's ACL, and then precompiled and deployed the site again, the ACL change will be lost.

The following table describes different file types and the actions taken on them if the application is being precompiled for deployment only.

File types	Precompilation action	Output location
.aspx, ascx, .master	Generates assemblies and a .compiled file that points to the assembly. The original file is left in place as a placeholder for fulfilling requests.	Assemblies and .compiled files are written to the Bin folder. Pages (.aspx files, with content stripped) are left in their original locations.
.asmx, .ashx	Generates assemblies. The original file is left in place as a placeholder for fulfilling requests.	Bin folder
Files in the App_Code folder	Generates one or more assemblies (depending on Web.config settings). Note Static content in the App_Code folder is not copied to the target folder.	Bin folder
.cs or .vb files not in the App_Code folder	Compiles with the page or resource that depends on it.	Bin folder
Existing .dll files in Bin folder.	Copies files as is.	Bin folder
Resources (.resx) files	For .resx files found in the App_LocalResources or App_GlobalResources folders, generates an assembly or assemblies and a culture structure.	Bin folder
Files in the App_Themes folder and subfolders	Generates assemblies in target and generates .compiled files that point to the assemblies.	Bin
Static files (.htm, .html, .js, graphics files, and so on)	Copies files as is.	Same structure as in source.
Browser definition files	Copies files as is. Note Browser information is inherited from machine-level configuration files, and may therefore behave differently on the target server.	App_Browsers
Dependent projects	Generates the output of the dependent project into an assembly.	Bin folder
Web.config files	Copies files as is.	Same structure as in source.
Global.asax files	Generates an assembly.	Bin folder

The following table describes the different file types and the actions taken on them if the application is being precompiled for deployment and update.

File types	Precompilation action	Output location
.aspx, ascx, .master	Generates assemblies for files that have code-behind class files. Generates a .compiled file that points to the assembly. Single-file versions of these files are copied as is to the target.	Assemblies and .compiled files are written to the Bin folder.
.asmx, .ashx	Copies files as is without compilation.	Same structure as in source.
Files in the App_Code folder	Generates one or more assemblies (depending on Web.config settings). Note Static content in the App_Code folder is not copied to the target folder.	Bin folder
.cs or .vb files not in App_Code folder	Compiles with the page or resource that depends on it.	Bin folder
Existing .dll files in Bin folder.	Copies files as is.	Bin folder
Resources (.resx) files	For .resx files in the App_GlobalResources folders, generates an assembly or assemblies and a culture structure. For .resx files in the App_LocalResources folders, copies files as is to the App_LocalResources folder of the output location.	Assemblies are put in the Bin folder
Files in the App_Themes folder and subfolders	Copies files as is.	Same structure as in source.
Static files (.htm, .html, .js, graphics files, and so on)	Copies files as is.	Same structure as in source.
Browser definition files	Copies files as is. Note Browser information is inherited from machine-level configuration files, and may therefore behave differently on the target server.	App_Browsers
Dependent projects	Generates the output of the dependent project into an assembly.	Bin folder
Web.config files	Copies files as is.	Same structure as in source.
Global.asax files	Generates an assembly.	Bin folder

.compiled Files

For executable files in an ASP.NET Web application, the compiler adds the .compiled file name extension to the name of assemblies and files. The assembly name is generated by the compiler. The .compiled file does not contain executable code. Instead, it contains only the information that ASP.NET must have to find the appropriate assembly.

After the precompiled application is deployed, ASP.NET uses the assemblies in the Bin folder to process requests. The precompilation output includes .aspx or .asmx files as placeholders for pages. The placeholder files contain no code. They exist only to invoke ASP.NET for a specific page request. The placeholder files also provide a way that file permissions can be set to restrict access to the pages.

Deploying and Updating Precompiled Web Sites

For information about how to deploy a precompiled Web site project, see ASP.NET Web Site Project Deployment Overview.

After you deploy a precompiled Web site, you can make limited changes to the files in the site. The following table describes the effect of different types of changes.

File type	Changes permitted (deployment only)	Changes permitted (deployment and update)
Static files (.htm, .html, .js, graphics files, and so on)	Static files can be changed, removed, or added. If an ASP.NET Web page refers to pages or page elements that are changed or removed, errors might occur.	Static files can be changed, removed, or added. If an ASP.NET Web page refers to pages or page elements that are changed or removed, errors might occur.
.aspx file	No changes are permitted to existing pages. No new .aspx files can be added.	You can change the layout of .aspx files and add elements that do not require code, such as HTML elements and ASP.NET server controls that have no event handlers. You can also add new .aspx files, which are compiled on first request.
.skin files	Changes and new .skin files are ignored.	Changes and new .skin files are permitted.
Web.config files	Changes are permitted that affect the compilation of .aspx files. Compilation options for debugging or batching are ignored. No changes to profile properties or provider elements are permitted.	Changes are permitted if they do not affect site or page compilation. This includes compiler settings, trust levels, and globalization. Changes that affect compilation or that change behavior in compiled pages are ignored or might generate errors. Other changes are permitted.
Browser definitions	Changes and new files are permitted.	Changes and new files are permitted.
Assemblies compiled from resource (.resx) files	New resource assembly files can be added for both global and local resources.	New resource assembly files can be added for both global and local resources.

Back to top

See Also

Tasks

How to: Create Versioned Assemblies for Precompiled Web Site Projects

Reference

ASP.NET Compilation Tool (Aspnet_compiler.exe)

Concepts

Configuring Deployed Web Site Projects