compilation Element (ASP.NET Settings Schema)

Configures all compilation settings that ASP.NET uses to compile applications.

<configuration> Element
  system.web Element (ASP.NET Settings Schema)
    compilation Element (ASP.NET Settings Schema)

<compilation 
   debug="[true|false]"
   batch="[true|false]"
   batchTimeout="number of seconds"
   defaultLanguage="language" 
   explicit="[true|false]" 
   maxBatchSize="maximim number of pages"
   maxBatchGeneratedFileSize="maximum combined size"
   numRecompilesBeforeAppRestart="number"
   strict="[true|false]" 
   tempDirectory="temporary files directory"
   urlLinePragmas="[true|false]"
   optimizeCompilations="[true|false]"
   targetFramework="2.0|3.0|3.5|4.0"
   assemblyPostProcessorType="assembly post processor, assembly"
>
   <assemblies>...</assemblies> 
   <buildProviders>...</buildProviders>
   <folderLevelBuildProviders>...</folderLevelBuildProviders>
   <codeSubDirectories>...</codeSubDirectories>
   <compilers>...</compilers>
   <expressionBuilders>...</expressionBuilders>
</compilation>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute

Description

assemblyPostProcessorType

Optional String attribute.

Specifies a post-process compilation step for an assembly by referring to an assembly post-processor. Use the format "assembly post processor, assembly". The assembly post processor must implement the IAssemblyPostProcessor interface. Using this method of post-processing forces debug on the compilation, which you can override when specifying deployment mode.

This attribute is new in the .NET Framework version 2.0.

The default is an empty string.

batch

Optional Boolean attribute.

Indicates whether batching is supported.

If True, eliminates the delay caused by the compilation required when you access a file for the first time. When this attribute is set to True, ASP.NET precompiles all the uncompiled files in a batch mode, which causes an even longer delay the first time the files are compiled. However, after this initial delay, the compilation delay is eliminated on subsequent access of the file.

The default is True.

batchTimeout

Optional TimeSpan attribute.

Specifies the time-out period, in seconds, for batch compilation. If compilation cannot be completed within the time-out period, the compiler reverts to single compilation mode for the current page.

The default is "900" (15 minutes).

debug

Optional Boolean attribute.

Specifies whether to compile debug binaries rather than retail binaries.

The default is False.

defaultLanguage

Optional String attribute.

Specifies the default programming language, such as "C#" or "PERL", to use in dynamic compilation files. Language names are defined using either the compilers element of the system.codeDom section or the compilers child element of this element (deprecated).

The default is "vb".

explicit

Optional Boolean attribute.

Specifies whether to set the Microsoft Visual Basic explicit compile option. If True, all variables must be declared using a Dim, Private, Public, or ReDim statement.

The default is True.

maxBatchGeneratedFileSize

Optional Int32 attribute.

Specifies the maximum combined size (in KB) of the generated source files per batched compilation. In general, it's not ideal to load a huge assembly in memory when fewer bits are actually needed. This limit helps to make sure the size of assemblies fall into a reasonable range so that the application takes advantage of the batch mechanism without overloading the system. This is similar to the maxBatchSize.

The default is 1000.

maxBatchSize

Optional Int32 attribute.

Specifies the maximum number of pages per batched compilation.

The default is 1000.

numRecompilesBeforeAppRestart

Optional Int32 attribute.

Specifies the number of dynamic recompiles of resources that can occur before the application restarts. This attribute is supported at the global and application level but not at the directory level.

Note

ASP.NET increases the NumRecompilesBeforeAppRestart property every time an assembly is invalidated and fails to be deleted.

The default is 15.

optimizeCompilations

Optional Boolean attribute.

Specifies whether dynamic compilation will recompile an entire site if a top-level file is changed. Top-level files include the Global.asax file and all files in the Bin and App_Code folders. If True, only changed files are recompiled.

The default is False.

For more information, see Understanding ASP.NET Dynamic Compilation.

strict

Optional Boolean attribute.

Specifies whether to enable the Visual Basic strict compile option.

The default is False.

targetFramework

Optional String attribute.

Specifies the version of the .NET Framework that the Web site targets.

The default is Null.

If this attribute is omitted, the target version is determined by other settings in the Web.config file and by the IIS application pool that the Web site is associated with. For more information, see CompilationSection.TargetFramework and .NET Framework Multi-Targeting for ASP.NET Web Projects.

tempDirectory

Optional String attribute.

Specifies 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 %FrameworkInstallLocation%\ Temporary ASP.NET Files directory.

Note that only processes with high trust permissions can access the %FrameworkInstallLocation%\ Temporary ASP.NET Files.

urlLinePragmas

Optional Boolean attribute.

Specifies whether the compiler should use URLs rather than physical paths.

The default is False.

Child Elements

Element

Description

assemblies

Defines a collection of names of assemblies that are used during compilation of an ASP.NET resource.

buildProviders

Defines a collection of build providers that are used to compile custom resource files. For more information, see the BuildProvider class.

codeSubDirectories

Defines an ordered collection of subdirectories containing the files that are compiled at run time.

compilers

Defines a collection of compiler options.

Note

In the .NET Framework version 2.0 and later versions, this element is deprecated in favor of the compilers element of the system.codeDom section. However, using the compilers child element of the compilation element is still valid and overrides the compilers element that is located in the system.codedom section.

expressionBuilders

Defines a collection of resource strings to be used during compilation. The resource strings associate prefixes with expression builders.

folderLevelBuildProviders

Defines a collection of build providers that are used to compile custom resource files in specific folders. Build providers are mapped to file extensions and are used to generate code from files of the specified type. For more information, see the FolderLevelBuildProvider class.

Parent Elements

Element

Description

configuration

Specifies the required root element in every configuration file that is used by the common language runtime and .NET Framework applications.

system.web

Specifies the root element for the ASP.NET configuration settings in a configuration file and contains configuration elements that configure ASP.NET Web applications behavior.

Remarks

The compilation element configures all the compilation settings that ASP.NET uses to compile applications.

In the .NET Framework version 2.0, the compilers child element of the compilation element is deprecated in favor of the compilers element of the system.codeDom section. However, using the compilers child element of the compilation element is still valid and overrides the compilers element that is located in the system.codedom section.

Default Configuration

The following default compilation element is not explicitly configured in the Machine.config file or in the root Web.config file. However, it is the default configuration returned by application. Items are added to the assemblies, buildProviders, and expressionBuilders collections in the root Web.config file.

<compilation 
   tempDirectory="" 
   debug="false" 
   strict="false" 
   explicit="true" 
   batch="true" 
   batchTimeout="900" 
   maxBatchSize="1000" 
   maxBatchGeneratedFileSize="1000" 
   numRecompilesBeforeAppRestart="15" 
   defaultLanguage="vb" 
   urlLinePragmas="false" 
   assemblyPostProcessorType=""
>
   <assemblies>
       <clear />
   </assemblies>
   <buildProviders>
       <clear />
   </buildProviders>
   <expressionBuilders>
       <clear />
   </expressionBuilders>
</compilation>

The following default compilation element is configured in the Machine.config file in the .NET Framework version 1.1. Similar settings exist in the .NET Framework version 1.0, with the exception of version numbers.

<compilation debug="false" explicit="true" defaultLanguage="vb">
   <compilers>
      <compiler language="c#;cs;csharp" extension=".cs" type="Microsoft.CSharp.CSharpCodeProvider, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" warningLevel="1"/>
      <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb" type="Microsoft.VisualBasic.VBCodeProvider, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
      <compiler language="js;jscript;javascript" extension=".js" type="Microsoft.JScript.JScriptCodeProvider, Microsoft.JScript, Version=7.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/>
      <compiler language="VJ#;VJS;VJSharp" extension=".jsl" type="Microsoft.VJSharp.VJSharpCodeProvider, VJSharpCodeProvider, Version=7.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/></compilers>
   <assemblies>
      <add assembly="mscorlib"/>
      <add assembly="System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
      <add assembly="System.Web, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/>
      <add assembly="System.Data, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
      <add assembly="System.Web.Services, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/>
      <add assembly="System.Xml, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
      <add assembly="System.Drawing, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/>
      <add assembly="System.EnterpriseServices, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/>
      <add assembly="System.Web.Mobile, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/>
      <add assembly="*"/>
   </assemblies>
</compilation>

Example

The following code example demonstrates how to configure compilation settings for an application.

<configuration>
   <system.web>
      <compilation defaultLanguage="VB"
         targetFramework="4.0"
         debug="true"
         numRecompilesBeforeAppRestart="15">
         <assemblies>
            <add assembly="ADODB"/>
            <add assembly="*"/>
         </assemblies>

         <codeSubDirectories>
           <add directoryName="mySubDir1"/>
           <add directoryName="mySubDir2"/>
           <add directoryName="mySubDir3"/>
         </codeSubDirectories>

         <buildProviders>
            <buildProvider 
               extension=".mafx" type="BuildProviderType, 
                          BuildProviderAssembly"
            />
        </buildProviders>
     </compilation>
   </system.web>
</configuration>

Element Information

Configuration section handler

CompilationSection

Configuration member

Compilation

Configurable locations

Machine.config

Root-level Web.config

Application-level Web.config

Virtual or physical directory–level Web.config

Requirements

Microsoft Internet Information Services (IIS) 5.0, 5.1, or 6.0

.NET Framework 1.0, 1.1, 2.0

Visual Studio 2003, or Visual Studio 2005

See Also

Tasks

How to: Configure Specific Directories Using Location Settings

How to: Lock ASP.NET Configuration Settings

Reference

system.web Element (ASP.NET Settings Schema)

assemblies Element for compilation (ASP.NET Settings Schema)

buildProviders Element for compilation (ASP.NET Settings Schema)

codeSubDirectories Element for compilation (ASP.NET Settings Schema)

compilers Element for compilation (ASP.NET Settings Schema)

expressionBuilders Element for compilation (ASP.NET Settings Schema)

configuration Element (General Settings Schema)

System.Configuration

System.Web.Configuration

CompilationSection

Compilation

Concepts

ASP.NET Compilation Overview

ASP.NET Web Page Syntax Overview

ASP.NET Configuration File Hierarchy and Inheritance

Securing ASP.NET Configuration

ASP.NET Configuration Scenarios

.NET Framework Multi-Targeting for ASP.NET Web Projects

Other Resources

General Configuration Settings (ASP.NET)

ASP.NET Configuration Settings

ASP.NET Web Site Administration

ASP.NET Configuration Files

ASP.NET Configuration API