ASP.NET Merge Tool (Aspnet_merge.exe)

The ASP.NET Merge tool (Aspnet_merge.exe) enables you to combine and manage assemblies that are created by the ASP.NET Compilation tool (Aspnet_compiler.exe).

aspnet_merge     [-?]
                 applicationPath
                 [-keyfile filename [-delaysign]]
                 [-o assemblyname | -w assemblyname | -prefix prefix]
                 [-copyattrs [assemblyfile]]
                 [-debug]
                 [-nologo]
                 [-errorstack]
                 [-r]
                 [-xmldocs]
                 [-a]
                 [-logfile logfile]
                 [-allowattrs textfile]

Arguments

Options

Option	Description
-keyfile filename	Specifies that the AssemblyKeyFileAttribute attribute should be applied to the compiled assembly. The attribute specifies the name of the file that contains the public and private key pair that is used to generate a strong name. If the input assemblies are signed and the Merge tool does not sign assemblies, you will receive a message that warns that the keys have been removed. If a key-file name is not specified, the Merge tool fails if one assembly has a public key and another assembly does not.
-delaysign	Specifies that the AssemblyDelaySignAttribute attribute should be applied to the generated assembly. This attribute specifies that an assembly should be signed only with the public key token instead of with the public and private key pair. This option must be combined with the-keyfile option. If the attribute is already applied to the assembly in code files, the Merge tool throws an exception. When you use the delaysign option, if strong name verification is not enabled, the code produced by the Merge tool can run before the code is signed. If strong name verification is not enabled, make sure that the code is not vulnerable to attack by malicious users during the time before signing is completed.
-o assemblyname	Specifies the name for a single, merged assembly for all Web UI content and top-level assemblies. All files that have the .compiled file name extension are modified to reference the single assembly. (Files with the .compiled extension are compiled from content such as .aspx, .master, and .ascx files.) This option cannot be combined with the w or prefix options. The assemblyname parameter is required.
-w assemblyname	Specifies the name for a single, merged assembly for all Web UI content (pages and user controls). All compiled .aspx, .master, and .ascx files are modified to reference the single assembly. This enables you to update UI elements separately from updating code. Top-level assemblies for local and global resources are not merged. This option cannot be combined with the o or prefix options. The assemblyname parameter is required.
-prefix prefix	Specifies a prefix for the names of assemblies. The root folder assembly has only the prefix parameter as the name of the assembly. Subfolder assemblies have the prefix parameter combined with the subfolder name. For example, if a subfolder is named Admin, the resulting assembly would be named prefix.Admin.dll. For Web sites that cannot be updated, the Compilation tool compiles themes and local resources into separate assemblies in the Bin folder. For Web sites that can be updated, themes and local resources are not compiled into assemblies in the Bin folder. Instead, they are left in their original folders in the application. Additionally, for updatable sites, the Merge tool modifies .aspx, .master, and .ascx files to point to the new, merged assembly for the folder in which the files reside. This option cannot be combined with the o or w options. The prefix parameter is required.
-copyattrs assemblyfile	Specifies that the merged assembly or assemblies should be assigned the same assembly attributes as the specified assembly. If assemblyFile is not specified, the App_Code assembly is used, even if the App_Code.dll top-level assembly is not included in the merged output. If there is an inconsistent attribute between an assembly to be merged and the assemblyFile assembly, an error is thrown. Use the a option to bypass the inconsistent attribute check, or use the allowattrs option to specify the attribute to exclude from the check. For attributes that are not included in the consistency check, see the description for the allowattrs option elsewhere in the table.
-debug	Specifies that debug output should be preserved in the merged assembly.
-nologo	Suppresses the copyright message.
-errorstack	Specifies that the tool should include stack trace information if it fails to compile the application.
-r	Removes the .compiled files for the main code assembly (code in the App_Code folder). Do not use this option if your application contains an explicit type reference to the main code assembly.
-xmldocs	Merges XML documentation files that are associated with the input assemblies. An XML file is included in the merged site's Bin folder.
-a	Forces the Merge tool to merge assemblies that do not all have the AllowPartiallyTrustedCallersAttribute applied, or that have inconsistent attributes. The AllowPartiallyTrustedCallersAttribute allows partially trusted callers access to an assembly and is specified during compilation by the Compilation tool. Important Note: When you use the a option, merged assemblies that were not previously marked as allowing partially trusted callers are marked with AllowPartiallyTrustedCallersAttribute. This can result in allowing partially trusted code to call the assembly.
-log logfile	Writes messages to the specified file.
-allowattrs textfile	Specifies a file that contains attributes to exclude when the tool is checking the consistency of attributes in merged assemblies. Each line of the file can be either the fully qualified name of an attribute or a fully qualified namespace. If a namespace is specified, all attributes found in that namespace will be excluded. Each attribute or namespace should be on a separate line. Some attributes do not have to be explicitly specified. The Merge tool outputs a warning if it encounters the following attributes, and then continues processing. System.CodeDom.Compiler.GeneratedCodeAttribute System.Runtime.CompilerServices.CompilationRelaxationsAttribute System.Runtime.CompilerServices.RuntimeCompatibilityAttribute System.Diagnostics.DebuggableAttribute Microsoft.JScript.ReferenceAttribute
-?	Displays command syntax and options for the tool.

Remarks

The ASP.NET Merge tool merges the output of the ASP.NET Compilation tool into fewer assemblies or a single assembly. This can make release management and deployment easier for large Web sites. You can use the ASP.NET Merge tool in three ways:

• Merge all compiler outputs into a single assembly.

• Merge each folder's Web UI content (Web pages, skins, and so on) into its own assembly.

• Merge all Web UI content in the site into a single assembly.

Assembly Groups

The Compilation tool creates assemblies differently depending on the type of the source file and folder. The output from the Compilation tool can be classified into two assembly groups. The Merge tool merges the two assembly groups differently.

The two assembly groups are as follows:

• Web UI content assemblies, which are generated from Web UI content files such as .aspx, .ascx, .master, .ashx, .skin, and local .resx files (in the App_LocalResources folder). How these assemblies are merged depends on whether the precompiled site is updatable, which is determined by the u option of the Compilation tool. If a compiled site is updatable, UI content can be updated without recompiling the site. When a Web site is updatable, the content files remain in their original folders and only the associated code files are merged. If the site is not updatable, .ascx, .master, and .skin content files are removed from their original folder. ASP.NET .aspx files are replaced with a marker file that has no content. UI content and code are merged in this case.

• Top-level assemblies, which are assemblies that are generated from application folders such as App_Code, App_GlobalResources, App_WebReferences. Top-level assemblies are also generated for special files such as Global.asax. Top-level assemblies are always compiled in the Bin folder of the deployment site. The final deployment site will not have an App_Code, App_GlobalResources, or App_WebReferences folder, or a Global.asax file. Instead, the final deployment site will have one or more assemblies in the Bin directory, depending on the options that are used with the Merge tool. User-defined folders are always compiled also, except that the final deployment site retains the user-defined folder when there are UI content files in it. For more information about reserved folders, see ASP.NET Web Site Layout.

Static content, such as files that have file name extensions such as .css, .gif, .htm, .html, .jpg, .js, are left in their locations in the precompiled directory structure. The Merge tool does not move or modify them.

Compilation and Merge Scenarios

With ASP.NET 2.0, you can use a combination of dynamic compilation, precompilation with the Compilation tool, and merging with the Merge tool to suit your deployment and release management goals. The following table lists different compilation and merge scenarios, and highlights when the Merge tool should be used.

Merging an Application for Deployment

You merge the assemblies for a Web site by running the Merge tool and specifying the location of the precompiled site with the applicationPath parameter. The ASP.NET Merge tool merges a precompiled site in place. In other words, it does not create a new merged copy of the precompiled site. The applicationPath parameter can be the final location for the Web application. Alternatively, the compiled application can be further deployed, such as by copying the directory.

When the Merge tool merges a precompiled site, it preserves the location of dynamic files as they appear in the precompiled step. The only change that the Merge tool makes to the content of dynamic files is to change @ Page, @ Control, and @ Master directives. It makes sure that files that have these directives inherit from the correct merged assembly in the Bin folder. For details about how the Compilation tool treats file types, see the "Remarks" section of ASP.NET Compilation Tool (Aspnet_compiler.exe)

For assemblies that are derived from user-defined folders (including the root site folder), some merge options can create names that differ from those that appear in the precompiled site. For example, the following table shows the merged assembly names when no options are used with the Merge tool. The assembly name for each user-defined folder is App_Web_nnnn.dll, where nnnn is an internally generated hash value.

The following table shows the merged assembly names when you use the prefix option and the NewName parameter.

Themes are treated differently in a merged site that is not updatable. In the precompiled, unmerged site, there is a separate assembly for each theme. Each assembly is named App_Theme_ThemeName.dll. In the merged site, there is one assembly named Theme.dll. If the precompiled site is updatable, there are no assemblies based on themes in the merged Bin folder.

Troubleshooting the Merge Process

While a Web site is being compiled or merged, the path of an assembly might become longer than the maximum allowed length for a file path in Microsoft Windows. In that case, when you request a resource from the merged assembly, an HttpException error is thrown that indicates that the resource was not precompiled and cannot be requested.

The maximum file path length in Microsoft Windows is 260 characters. If the path of an assembly exceeds this limit, you must either shorten the path of the Web site or of its subfolders. You might also have to disable shadow copying in the Web.config file by using the ShadowCopyBinAssemblies property of the hostingEnvironment element. For more information about file names, see Naming a File on the MSDN Web site.

When you use the Merge tool with the o option to create a single assembly for the site, an error will occur if the merge process creates circular references. There are two workarounds for this situation:

• Use the w option instead so that the source file that contains the circular reference remains an external reference and is not merged.

• Separate the controls that are involved in a circular reference into different directories.

When you merge assemblies that have inconsistent attributes, use the following guidelines to make sure that the merge operation succeeds:

• List inconsistent attributes by using the allowattrs option.

• Use the copyattrs options and make sure that all assemblies to be merged have matching attributes.

• Use the a option.

Signing Assemblies

The delaysign and keyfile options let you use the Merge tool to create strongly named assemblies without using the Strong Name tool (Sn.exe). The delaysign options corresponds to the AssemblyDelaySignAttribute attribute, and the keyfile option corresponds to the AssemblyKeyFileAttribute attribute.

Each option applies the corresponding attribute to the merged assembly. The attributes being applied are marked with an AttributeUsageAttribute attribute whose AllowMultiple property is set to false. Therefore, if you use these options when you merge assemblies that are already marked with one of the attributes, merging will fail.

Examples

The following command merges the assemblies of the precompiled site in the C:\PrecompiledSite directory.

Aspnet_merge C:\PrecompiledSite

The following command merges assemblies of a precompiled site in the C:\PrecompiledSite directory and signs the merged assemblies by using the KeyFile.snk file. The merged site will have one assembly for each precompiled site folder.

Aspnet_merge C:\PrecompiledSite -keyfile KeyFile.snk

The following command merges all assemblies of the precompiled site in the C:\PrecompiledSite directory into a single assembly and names the resulting assembly MyApp.dll. The merged site will have one assembly for all Web site UI content.

Aspnet_merge C:\PrecompiledSite -w MyApp.dll

The following command merges all assemblies of the precompiled site in the C:\PrecompiledSite directory into a single assembly and names the resulting assembly MyApp.dll.

Aspnet_merge C:\PrecompiledSite -o MyApp.dll

For more examples that show how to use the ASP.NET Merge tool, see Managing ASP.NET Precompiled Output for Deployment Using the aspnet_merge.exe Command on the MSDN Web site.

Finding the Correct Version of Aspnet_merge.exe

Aspnet_merge.exe 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 Compilation Tool (Aspnet_compiler.exe)