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.

aspnet_compiler  [-?]
                 [-m metabasePath | -v virtualPath [-p physicalPath]]
                 [[-u] [-f] [-d] [-fixednames] targetDir]
                 [-c]
                 [-errorstack]
                 [-nologo]
                 [[-keyfile file | -keycontainer container ] [-aptca] [-delaysign]]

Options

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.

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.

The following table describes how the ASP.NET Compilation tool handles different file types when the -u option is omitted.

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

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.

See Also

Concepts

Delay Signing an Assembly

Strong-Named Assemblies

Reference

AssemblyKeyFileAttribute

AssemblyKeyNameAttribute

AssemblyDelaySignAttribute

AllowPartiallyTrustedCallersAttribute

.NET Framework Tools

Strong Name Tool (Sn.exe)

ASP.NET IIS Registration Tool (Aspnet_regiis.exe)