ASP.NET Compilation Tool (Aspnet_compiler.exe)
The ASP.NET Compilation tool (Aspnet_compiler.exe) enables you to compile an ASP.NET Web application, either in place or for deployment to a target location such as a production server. In-place compilation helps application performance because end users do not encounter a delay on the first request to the application while the application is compiled. Compilation for deployment can be performed in one of two ways: one that removes all source files, such as code-behind and markup files, or one that retains the markup files.
Note
For information about how to find the correct version of Aspnet_compiler.exe, see Finding the Correct Version of Aspnet_compiler.exe later in this topic.
aspnet_compiler [-?]
[-m metabasePath | -v virtualPath [-p physicalPath]]
[[-u] [-f] [-d] [-fixednames] targetDir]
[-c]
[-errorstack]
[-nologo]
[[-keyfile file | -keycontainer container ] [-aptca] [-delaysign]]
Options
Option |
Description |
|---|---|
-m metabasePath |
Specifies the full IIS metabase path of the application to be compiled. The IIS metabase is a hierarchical information store that is used to configure IIS. For example, the metabase path to the default IIS Web site is LM/W3SVC/1/ROOT. This option cannot be combined with the -v or -p options. |
-v virtualPath |
Specifies the virtual path of the application to be compiled. If -p is also specified, the value of the accompanying physicalPath parameter is used to locate the application to be compiled. Otherwise, the IIS metabase is used, and the tool assumes that the source files are located under the default Web site (specified in the LM/W3SVC/1/ROOT metabase node). This option cannot be combined with the -m option. |
-p physicalPath |
Specifies the full network path or local disk path of the root directory that contains the application to be compiled. If -p is not specified, the IIS metabase is used to find the directory. This option must be combined with the -v option, and cannot be combined with the -m option. |
-u |
Specifies that Aspnet_compiler.exe should create a precompiled application that allows subsequent updates of contents such as .aspx pages. If this option is omitted, the resulting application contains only compiled files and cannot be updated on the deployment server. You can update the application only by changing the source markup files and recompiling. The targetDir parameter must be included. When you use this option, code blocks in .aspx files (that is, code located in script elements or between <% and %> tags) are not compiled. Therefore, if there are compile errors in those code blocks, you will see the error only at run time, because the .aspx file is fully compiled only then. It is generally unsafe to use this option for a site that relies on code blocks in .aspx files. |
-f |
Specifies that the tool should overwrite existing files in the targetDir directory and its subdirectories. |
-d |
Overrides settings defined in the application's source configuration files to force debug information to be included in the compiled application. Otherwise, no debug output is emitted. You cannot use the -d option for in-place compilation; in-place compilation honors configuration settings for debugging options. |
targetDir |
The network path or local disk path to the root directory that will contain the compiled application. If the targetDir parameter is not included, the application is compiled in place. |
-c |
Specifies that the application to be compiled should be fully rebuilt. Components that have already been compiled are compiled again. If this option is omitted, the tool builds only those parts of the application that have been modified since compilation was last performed. |
-errorstack |
Specifies that the tool should include stack trace information if it fails to compile the application. |
-keyfile file |
Specifies that the AssemblyKeyFileAttribute, which indicates the name of the file containing the public/private key pair that is used to generate a strong name, should be applied to the compiled assembly. This option must be combined with the -aptca option. If the attribute is already applied to the assembly in code files, Aspnet_compiler.exe throws an exception. |
-keycontainer container |
Specifies that the AssemblyKeyNameAttribute, which indicates the name of the container for the public/private key pair that is used to generate a strong name, should be applied to the compiled assembly. This option must be combined with the -aptca option. If the attribute is already applied to the assembly in code files, Aspnet_compiler.exe throws an exception. |
-aptca |
Specifies that the AllowPartiallyTrustedCallersAttribute, which allows partially trusted callers access to an assembly, should be applied to the strongly named assembly that Aspnet_compiler.exe generates. This option must be combined with the -keyfile or -keycontainer option. If the attribute is already applied to the assembly in code files, Aspnet_compiler.exe throws an exception. |
-delaysign |
Specifies that the AssemblyDelaySignAttribute, which indicates that an assembly should be signed only with the public key token rather than with the public/private key pair, should be applied to the generated assembly. This option must be combined with the -keyfile or -keycontainer option. If the attribute is already applied to the assembly in code files, Aspnet_compiler.exe throws an exception. When you use the -delaysign option, the code produced by Aspnet_compilier.exe can run before the code is signed. You must ensure that the code is not vulnerable to malicious users before signing is completed. |
-fixednames |
Specifies that one assembly should be generated for each page in the application. Each assembly is named with the virtual path of the original page unless the name would exceed the operating system limit for file names, in which case a hash is generated and used for the assembly name. You cannot use the -fixednames option for in-place compilation; in-place compilation honors configuration settings for compilation batch mode. |
-nologo |
Suppresses the copyright message. |
-? |
Displays command syntax and options for the tool. |
Remarks
There are two versions of the ASP.NET Compilation tool:
The version that is provided with the .NET Framework 2.0. Use this version for Web applications that are deployed in application pools that are associated with the .NET Framework 2.0 CLR. The Web applications can target the .NET Framework 2.0, the .NET Framework 3.0, or the .NET Framework 3.5.
The version that is provided with the .NET Framework 4. Use this version for Web applications that are deployed in application pools that are associated with the .NET Framework 4 CLR. The Web applications can target the .NET Framework 2.0, the .NET Framework 3.0, the .NET Framework 3.5, or the .NET Framework 4. When this version is used for Web sites that target the .NET Framework 2.0, the .NET Framework 3.0, or the .NET Framework 3.5, it provides improved error reporting compared to the .NET Framework 2.0 version.
For more information about how to develop, compile, and deploy Web sites that target specific versions of the .NET Framework, see .NET Framework Multi-Targeting for ASP.NET Web Projects and ASP.NET Side-by-Side Execution Overview. For information about how the ASP.NET Compilation tool determines which version of the .NET Framework a Web site targets, see the BuildManager.TargetFramework property.
The ASP.NET Compilation tool can be used in two general ways: for in-place compilation and compilation for deployment, where a target output directory is specified. The following sections describe these scenarios.
Compiling an Application in Place
The ASP.NET Compilation tool can compile an application in place, that is, it mimics the behavior of making multiple requests to the application, thus causing regular compilation. Users of a precompiled site will not experience a delay caused by compiling the page on first request.
Note that if you are using an impersonated account, both the account and the logon user account must have write access to the target for precompilation to succeed.
When you precompile a site in place, the following items apply:
The site retains its files and directory structure.
You must have compilers for all programming languages used by the site on the server.
If any file fails compilation, the entire site fails compilation.
You can also recompile an application in place after adding new source files to it. The tool compiles only the new or changed files unless you include the -c option.
Note
Compilation of an application that contains a nested application does not compile the nested application. The nested application must be compiled separately.
Note
When you compile a Web application that includes master pages, compilation can fail if you compile the application as an updatable site and a naming conflict occurs. The conflict can occur if the name of the master page matches the name of the namespace for a content page that derives from the master page. (The inheritance relationship is established by the Inherits attribute of the @ Page directive). To work around this issue, you can either change the class name of the master page or change the namespace name, or you can compile the application as non-updatable.
Note
If you use the .NET Framework 4 version of the tool to precompile a Web site in place, and if the site targets an earlier version of the .NET Framework and is associated with an application pool that targets the .NET Framework 2.0 CLR, the first request to the Web application will cause dynamic compilation as if the site had not been precompiled. This is because the command-line compiler compiles into temporary folders that are not recognized by the .NET Framework 2.0 CLR.
Compiling an Application for Deployment
You compile an application for deployment (compilation to a target location) by specifying the targetDir parameter. The targetDir can be the final location for the Web application, or the compiled application can be further deployed.
Using the -u option compiles the application in such a way that you can make changes to certain files in the compiled application without recompiling it. Aspnet_compiler.exe makes a distinction between static and dynamic file types, and handles them differently when creating the resulting application.
Static file types are those that do not have an associated compiler or build provider, such as files whose names have extensions such as .css, .gif, .htm, .html, .jpg, .js and so on. These files are simply copied to the target location, with their relative places in the directory structure preserved.
Dynamic file types are those that have an associated compiler or build provider, including files with ASP.NET-specific file name extensions such as .asax, .ascx, .ashx, .aspx, .browser, .master, and so on. The ASP.NET Compilation tool generates assemblies from these files. If the -u option is omitted, the tool also creates files with the file name extension .COMPILED that map the original source files to their assembly. To ensure that the directory structure of the application source is preserved, the tool generates placeholder files in the corresponding locations in the target application.
You must use the -u option to indicate that the content of the compiled application can be modified. Otherwise, subsequent modifications are ignored or cause run-time errors.
The following table describes how the ASP.NET Compilation tool handles different file types when the -u option is included.
File type |
Compiler action |
|---|---|
.ascx, .aspx, .master |
These files are split into markup and source code, which includes code-behind files. Source code is compiled into assemblies, with names that are derived from a hashing algorithm, and the assemblies are placed in the Bin directory. Any inline code, that is, code enclosed in <script runat="server"> elements, is included with markup and not compiled. New files with the same name as the source files are created to contain the markup and placed in the corresponding output directories. |
.ashx, .asmx |
These files are not compiled and are moved to the output directories as is and not compiled. If you wish to have the handler code compiled, place the code into source code files in the App_Code directory. |
.cs, .vb, .jsl, .cpp (not including code-behind files for the file types listed earlier) |
These files are compiled and included as a resource in assemblies that reference them. Source files are not copied to the output directory. If a code file is not referenced, it is not compiled. |
Custom file types |
These files are not compiled. These files are copied to the corresponding output directories. |
Source code files in the App_Code subdirectory |
These files are compiled into assemblies and placed in the Bin directory. Note Static file types in the App_Code directory are not copied to the output directories. |
.resx and .resource files in the App_GlobalResources subdirectory |
These files are compiled into assemblies and placed in the Bin directory. No App_GlobalResources subdirectory is created under the main output directory, and no .resx or .resources files located in the source directory are copied to the output directories. Note The resource files in the App_GlobalResources subdirectory are compiled into assemblies before code in the App_Code subdirectory is compiled. Modification of resource files after compilation is not supported. |
.resx and .resource files in the App_LocalResources subdirectory |
These files are not compiled and are copied to the corresponding output directories. |
.skin files in the App_Themes subdirectory |
The .skin files and static theme files are not compiled and are copied to the corresponding output directories. |
.browser Web.config Static file types Assemblies already present in the Bin directory |
These files are copied as is to the output directories. |
The following table describes how the ASP.NET Compilation tool handles different file types when the -u option is omitted.
Note
No warnings are provided to prevent you from modifying the source code of a compiled application.
File type |
Compiler action |
|---|---|
.aspx, .asmx, .ashx, .master |
These files are split into markup and source code, which includes both code-behind files and any code that is enclosed in <script runat="server"> elements. Source code is compiled into assemblies, with names that are derived from a hashing algorithm. The resulting assemblies are placed in the Bin directory. Any inline code, that is, code enclosed between the <% and %> brackets, is included with markup and not compiled. The compiler creates new files to contain the markup with the same name as the source files. These resulting files are placed in the Bin directory. The compiler also creates files with the same name as the source files but with the extension .COMPILED that contain mapping information. The .COMPILED files are placed in the output directories corresponding to the original location of the source files. |
.ascx |
These files are split into markup and source code. Source code is compiled into assemblies and placed in the Bin directory, with names that are derived from a hashing algorithm. No markup files are generated. |
.cs, .vb, .jsl, .cpp (not including code-behind files for the file types listed earlier) |
Source code that is referenced by the assemblies generated from .ascx, .ashx, or .aspx files is compiled into assemblies and placed in the Bin directory. No source files are copied. |
Custom file types |
These files are compiled like dynamic files. Depending on the type of file they are based on, the compiler can place mapping files in the output directories. |
Files in the App_Code subdirectory |
Source code files in this subdirectory are compiled into assemblies and placed in the Bin directory. Note Static file types in the App_Code directory are not copied to the output directories. |
Files in the App_GlobalResources subdirectory |
These files are compiled into assemblies and placed in the Bin directory. No App_GlobalResources subdirectory is created under the main output directory. If the configuration file specifies appliesTo="All", .resx and .resources files are copied to the output directories. They are not copied if they are referenced by a BuildProvider. |
.resx and .resource files in the App_LocalResources subdirectory |
These files are compiled into assemblies with unique names and placed in the Bin directory. No .resx or .resource files are copied to the output directories. |
.skin files in the App_Themes subdirectory |
Themes are compiled into assemblies and placed in the Bin directory. Stub files are created for .skin files and placed in the corresponding output directory. Static files (such as .css) are copied to the output directories. |
.browser Web.config Static file types Assemblies already present in the Bin directory |
These files are copied as is to the output directory. |
Fixed Assembly Names
The ASP.NET Compilation tool generates assembly names at compile time and regenerates them with each subsequent compilation. These generated assembly names work well with Web sites that are deployed as a whole; they are not well suited to Web sites that need to release updates to specific portions of the Web site without redeploying the entire Web site.
You can use the -fixednames switch for the ASP.NET Compilation tool to generate fixed-assembly names. When you use the -fixednames switch, the ASP.NET Compilation tool will do the following:
Create an assembly for each .aspx page in the application. This can lead to a large number of assemblies, so if you are concerned with scalability you should use this option with caution.
Use the virtual path to the page as the name of the page's assembly. If the length of the virtual path exceeds the file-name length limit of the operating system, the tool uses a hash of the virtual path instead.
Compile the files in top-level directories, such as the App_Code directory, into a single assembly (like default compilation).
Strong-Name Compilation
You can digitally sign the assemblies produced by the ASP.NET Compilation Tool (Aspnet_compiler.exe) to help improve the security of your Web application. Signing an assembly with a strong name makes it more difficult for attackers to introduce malicious code into your application. For more information about signed assemblies, see Strong-Named Assemblies and Creating and Using Strong-Named Assemblies.
The -aptca, -delaysign, -keycontainer and -keyfile options are provided so that you can use Aspnet_compiler.exe to create strongly named assemblies without using the Sn.exe (Strong Name Tool) separately. These options correspond, respectively, to AllowPartiallyTrustedCallersAttribute, AssemblyDelaySignAttribute, AssemblyKeyNameAttribute, and AssemblyKeyFileAttribute. Because each option applies the corresponding attribute to the compiled assembly, and because the attributes are marked with an AttributeUsageAttribute whose AllowMultiple property is set to false, using these keys on source code that has already been marked with one of these attributes causes compilation to fail.
Whenever you sign an assembly with either the -keyfile or -keycontainer switch, you must also specify that the AllowPartiallyTrustedCallersAttribute attribute be applied to the assembly by using the -aptca switch. If you do not specify the -aptca switch, your assembly cannot be called by the ASP.NET process, and Aspnet_compiler.exe throws an exception.
Associated ASP.NET Classes
Several classes in the System.Web.Compilation namespace enable your code to access or invoke Aspnet_compiler.exe outside of the IIS environment. The ClientBuildManager class provides the PrecompileApplication method to compile an application. The ClientBuildManager class also works with the ClientBuildManagerParameter class, which enables you to specify PrecompilationFlags that correspond to the options used by this tool, and similarly, to specify strong name keys.
Examples
The following command compiles the WebApplication1 application in place, specifying a virtual path for the application:
Aspnet_compiler -v /WebApplication1
The following command compiles the application in place, specifying a physical path for the application. The slash with the /v switch specifies that the compiler will use the physical path as the root when it resolves application root references (for example, with the tilde (~) operator).
Aspnet_compiler –p "c:\Documents and Settings\Default\My Documents\MyWebApplications\WebApplication1" –v /
The following command compiles the WebApplication1 application in place, and the tool adds stack trace information if it must report errors.
Aspnet_compiler -v /WebApplication1 -errorstack
The following command compiles the WebApplication1 application for deployment, using the physical directory path. It also adds two attributes to the output assemblies. It uses the -keyfile option to add an AssemblyKeyFileAttribute attribute, which specifies that the Key.sn file contains the public/private key pair information that the tool should use to provide strong names for the generated assemblies. The command also uses the -aptca option to add an AllowPartiallyTrustedCallersAttribute attribute to the generated assemblies. The compiled Web application is created in the directory c:\applicationTarget.
Aspnet_compiler -v /WebApplication1 -p "c:\Documents and Settings\Default\My Documents\MyWebApplications\WebApplication1" -keyfile "c:\Documents and Settings\Default\My Documents\Key.sn" -aptca c:\applicationTarget
The following command compiles the WebApplication1 application for deployment and update.
Aspnet_compiler -v /WebApplication1 -p "c:\Documents and Settings\Default\My Documents\MyWebApplications\WebApplication1" c:\applicationTarget -u
The following command compiles the WebService2 service under the default metabase path, overwriting the SampleWebService target directory with the compiled application.
Aspnet_compiler -m /LM/W3SVC/1/ROOT/WebService2 -f c:\InetPub\wwwroot\SampleWebService
The following command creates signed assemblies using a key file.
aspnet_compiler -v virtualPath targetPath -keyfile keyFile.snk -aptca
The virtualPath parameter indicates the Internet Information Services (IIS) virtual path of your Web site; the targetPath parameter indicates a physical path to the directory for the compiled Web site; and keyFile.snk indicates the name of the key file.
The following command creates signed assemblies using a key container file.
aspnet_compiler -v virtualPath targetPath -keycontainer keyContainer.snk -atpca
For information about how to create a key file or key container file, see How to: Create a Public/Private Key Pair.
Finding the Correct Version of Aspnet_compiler.exe
The Aspnet_compiler.exe tool is installed in the Microsoft.NET Framework directory. If the computer is running multiple .NET Framework versions side-by-side, multiple versions of the tool might be installed. The following table lists the locations where the tool is installed for different versions of the .NET Framework.
Version of .NET Framework |
Location of Aspnet_compiler.exe file |
|---|---|
.NET Framework version 2.0, version 3.0, and version 3.5 (32-bit systems) |
%windir%\Microsoft.NET\Framework\v2.0.50727 |
.NET Framework version 2.0, version 3.0, and version 3.5 (64-bit systems) |
%windir%\Microsoft.NET\Framework64\v2.0.50727 |
.NET Framework version 4 (32-bit systems) |
%windir%\Microsoft.NET\Framework\v4.0.30319 |
.NET Framework version 4 (64-bit systems) |
%windir%\Microsoft.NET\Framework64\v4.0.30319 |
See Also
Reference
AllowPartiallyTrustedCallersAttribute
ASP.NET IIS Registration Tool (Aspnet_regiis.exe)
Concepts
.NET Framework Multi-Targeting for ASP.NET Web Projects
ASP.NET Side-by-Side Execution Overview