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
The ASP.NET Compilation tool is not available with versions of ASP.NET earlier than ASP.NET version 2.0.
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. |
-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
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.
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 |
.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 |
.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 |
.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
Some scenarios, such as deploying a Web application using the MSI Windows Installer, require the use of consistent file names and contents, as well as consistent directory structures to identify assemblies or configuration settings for updates. In those cases, you can use the -fixednames option to specify that the ASP.NET Compilation tool should compile an assembly for each source file instead of using the where multiple pages are compiled into assemblies. This can lead to a large number of assemblies, so if you are concerned with scalability you should use this option with caution.
Strong-Name Compilation
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 Strong Name Tool (Sn.exe) 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.
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:
Aspnet_compiler -v /WebApplication1
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 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
See Also
Reference
.NET Framework Tools
Strong Name Tool (Sn.exe)
ASP.NET IIS Registration Tool (Aspnet_regiis.exe)
AssemblyKeyFileAttribute
AssemblyKeyNameAttribute
AssemblyDelaySignAttribute
AllowPartiallyTrustedCallersAttribute