File Handling During ASP.NET Precompilation

When you precompile a site for deployment, ASP.NET creates a layout—a structure that contains the compiler output. This topic 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, including program code and resources) and markup (.aspx files), or only source code. For details, see ASP.NET Web Site Precompilation Overview.

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 for deployment only 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 the 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 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 .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	Compiles into 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 with code-behind class files and 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 placed 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	Compiles into assembly.	Bin folder

.compiled Files

For executable files in an ASP.NET Web application, the compiler assemblies and files with the .compiled file name extension. 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 needs 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 provide a way to invoke ASP.NET for a specific page request and so that file permissions can be set to restrict access to the pages.

Updates to Deployed Web Sites

After deploying 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 Allowed (Deployment Only)	Changes Allowed (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 allowed 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 without event handlers. You can also add new .aspx files, which will be compiled normally on first request.
.skin files	Changes and new .skin files are ignored.	Changes and new .skin files are allowed.
Web.config files	Changes are allowed that affect the compilation of .aspx files. Compilation options for debugging or batching are ignored. No changes to profile properties or provider elements are allowed.	Changes are allowed if they do not affect site or page compilation, including compiler settings, trust levels, and globalization. Changes that affect compilation or that change behavior in compiled pages are ignored or might in some instances generate errors. Other changes are allowed.
Browser definitions	Changes and new files allowed.	Changes and new files allowed.
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.

See Also

Tasks

How to: Precompile ASP.NET Web Sites for Deployment

Concepts

ASP.NET Web Site Precompilation Overview