Share via

Understanding ASP.NET Dynamic Compilation

In order for your Web application to service requests, ASP.NET must first parse and compile the code of your Web application into one or more assemblies. When the code is compiled, it is translated into a language-independent and CPU-independent representation called Microsoft Intermediate Language (MSIL). At run time, MSIL runs in the context of the .NET Framework, which translates MSIL into CPU-specific instructions for the processor on the computer running the application.

ASP.NET dynamic compilation enables you to modify your source code without having to explicitly compile your code before you deploy your Web application. If you modify a source file, ASP.NET automatically recompiles the file and updates all linked resources. The IIS server does not have to be restarted for the changes to take effect unless the <processModel> section has been changed.

You can extend the ASP.NET build system by creating custom build providers for new file types that are called during compilation.

Compiling on First Request

By default, ASP.NET Web pages and code files are compiled dynamically when users first request a resource, such as an ASP.NET page (.aspx file), from a Web site. After pages and code files have been compiled the first time, the compiled resources are cached, so that subsequent requests to the same page are extremely efficient.

ASP.NET supports the dynamic compilation of ASP.NET pages (.aspx files), ASP.NET Web services (.asmx files), ASP.NET HTTP handlers (.ashx files) and ASP.NET application files (Global.asax), as well as other files, such as source code and class files. For more information about ASP.NET file types, see Web Site File Types. For more information about the ASP.NET compilation process, see the "Compilation Life Cycle" section of ASP.NET Application Life Cycle Overview for IIS 5.0 and 6.0.

Recompiling on Change

Any changes to a dynamically compiled file will automatically invalidate the file's cached compiled assembly and trigger recompilation of all affected resources. The next time a request to the code is made, ASP.NET recognizes that the code has changed and recompiles the affected resources of the Web application. This system enables you to quickly develop applications with a minimum of compilation processing overhead. (Note that depending on the change to the resources, the result can range from recompiling a single page to recompiling the whole Web site.)

Compilation Dependencies

When the first request is made to an application, ASP.NET compiles files in a specific order. The first items to be compiled are referred to as the top-level items. After the first request, the top-level items are recompiled only if a dependency changes.

Top-level items include the App_GlobalResources folder, the App_WebResources folder, profile properties, the App_Code folder, and the Global.asax file. After the top-level items are compiled, ASP.NET compiles additional items. These items include the App_LocalResources folder, individual ASP.NET pages (.aspx files), ASP.NET user controls (.ascx files), ASP.NET HTTP Handlers (.ashx files), and ASP.NET HTTP modules (.asmx files), as well as themes, master pages, and other source files.

For more information, see ASP.NET Web Site Layout and the "Compilation Life Cycle" section of ASP.NET Application Life Cycle Overview for IIS 5.0 and 6.0.

Compilation Output

When your code is compiled, the resulting assemblies are cached in a folder on the server. This folder requires appropriate permissions so that your code compiles and runs correctly. You can configure both the compilation folder location and the permissions under which your code compiles and operates.

Compilation Folder Location

By default, when you compile a Web application the compiled code is placed in the Temporary ASP.NET Files folder. This folder is a subdirectory of the location where you installed the .NET framework. Typically, the location is the following:

%SystemRoot%\Microsoft.NET\Framework\versionNumber\Temporary ASP.NET Files

Compilation Folder Required Permissions

The .NET installation process creates the Temporary ASP.NET Files folder and assigns access permissions to the ASP.NET local user account, which has the high-trust permissions needed to access your compiled code. If you modify your configuration or account settings, you must make sure that the account you use has high-trust permissions to the Temporary ASP.NET Files folder. For additional details, see How to: Run the Worker Process Under a User Account.

Compilation Folder Configurability

ASP.NET creates a discrete subfolder under the Temporary ASP.NET File folder for each application. You can configure the root location using the tempDirectory attribute of the compilation section of the configuration file. This optional attribute enables you to specify the directory to use for temporary file storage during compilation. The default is an empty string (""). In the case of an empty string, and if the current process has the required access permissions, the files are stored in the following directory:

%FrameworkInstallLocation%\Temporary ASP.NET Files

For more information, see compilation Element (ASP.NET Settings Schema) and the TempDirectory property of the CompilationSection.

Multiple Language Support

ASP.NET 2.0 supports multiple programming languages in the same Web application. In the App_Code directory, you can specify a subfolder for each language, such as C# and Visual Basic. ASP.NET will create a separate assembly for each subfolder. For more information, see Shared Code Folders in ASP.NET Web Sites and Walkthrough: Develop Web Sites Using Multiple Programming Languages.

Optimizing Dynamic Compilation

By default, when any change is made to a top-level file in a Web site, the whole site is recompiled. Top-level files include the global.asax file and all files in the bin and App_Code folders. It is safest to recompile everything when one of these files changes because other files in the site, such as .aspx and .ascx files, may reference the objects created by code in top-level files.

While recompiling everything works fine for most applications, it could cause a very large application to be unavailable for long periods of time even when minor changes have been made to it. If the application is large enough, it could be unavailable for five to ten minutes or more after a change is made.

If you want to be able to change top-level files without causing the whole site to be recompiled, you can set the optimizeCompilations attribute of the compilation element in the Web.config file to true.


You must install a hotfix to make the optimizeCompilations attribute available in the .NET Framework version 3.5.

If optimizeCompilations is true, when you change a top-level file only the affected files are recompiled. This saves time but can cause run-time errors depending on the type of changes you make to a top-level file.

The following kinds of changes are generally safe:

  • Changing a method implementation. Because the signature is not changed, pages compiled against the old version can call the method without throwing an exception.

  • Adding new methods or properties. Because these did not previously exist, no already-compiled pages will reference them, and no exceptions will be thrown.

  • Adding a CLR attribute to an existing member. This is a typical Dynamic Data scenario where you add attributes like DisplayName to properties. Because CLR attributes are discovered at runtime through reflection, existing pages do not have to be recompiled.

The following kinds of changes may cause run-time exceptions:

  • Renaming or deleting methods or properties. If the affected member is referenced by an already-compiled page, an exception will be thrown.

  • Changing the signature of a method, or the type of a property. If the affected member is referenced by an already-compiled page, an exception will be thrown. Some signature changes would not cause compile or run-time errors if the whole site is recompiled. For example, the code Response.Write(ClassA.MethodA() in an .aspx page will compile and run fine whether MethodA returns an int or a short. But if the .aspx page is already compiled and you change the return type of MethodA from int to short without recompiling, a runtime exception will be thrown because the compiled code expects the int signature.

If you want to use the optimizeCompilations attribute to minimize dynamic compilation time, you should carefully review each change you make to top-level files in your site, and if a particular change is not safe, temporarily remove the optimizeCompilations attribute or set it to false.

Disadvantages of Dynamic Compilation

There are certain capabilities that dynamic compilation does not offer. Dynamic compilation can mean slower initial response time for users, because pages and code files must be compiled the first time they are requested. This may be an issue particularly on large sites that are updated frequently. Dynamic compilation does not offer a means to identify compile-time bugs before users access a site. Also, dynamic compilation does not provide the ability to create a compiled version of the site that can be deployed to a production server without source code. If any of these issues are concerns for your Web applications, you can precompile your Web site. For details information, see ASP.NET Precompilation Overview.

See Also


How To: Secure an ASP.NET Application on a Shared Server


ASP.NET Impersonation

ASP.NET Required Access Control Lists (ACLs)

Web Site File Types

ASP.NET Web Site Layout



Other Resources

ASP.NET Web Site Precompilation Overview