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

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.

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

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.

See Also

Reference

AssemblyKeyFileAttribute

AssemblyKeyNameAttribute

AssemblyDelaySignAttribute

AllowPartiallyTrustedCallersAttribute

Sn.exe (Strong Name Tool)

ASP.NET IIS Registration Tool (Aspnet_regiis.exe)

BuildManager.TargetFramework

Concepts

Delay Signing an Assembly

Strong-Named Assemblies

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

ASP.NET Side-by-Side Execution Overview

Other Resources

.NET Framework Tools