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.

NoteNote

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).

NoteNote
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.

NoteNote
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).

NoteNote
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.

NoteNote
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