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 (Aspnet_compiler.exe) tool.
Note
For information about how to find the correct version of Aspnet_merge.exe, see Finding the Correct Version of Aspnet_merge.exe later in this topic.
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
Argument |
Description |
|---|---|
applicationPath |
(Required) Specifies the name of the folder that contains the application that you want to create assemblies for. This is the default merge operation. It creates fewer assemblies than the number generated by the compiler fixednames option. |
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 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. |
-? |
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.
There are two versions of the ASP.NET Merge tool:
The version that is provided with the .NET Framework 2.0. This version works only with assemblies that are created by the .NET Framework 2.0 version of the ASP.NET Compilation tool. 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. This version works only with assemblies that are created by the .NET Framework 4 version of the ASP.NET Compilation tool. 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 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.
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 Project Folder Structure.
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
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.
Scenario |
Notes |
|---|---|
Dynamic compilation (no precompilation) |
Dynamic compilation is useful in rapid development scenarios. Visual Studio uses dynamic compilation — when you press F5 or CTRL+F5, only the page that you are working on and its dependencies are compiled dynamically. This avoids a full Web-site compile. For more information, see Understanding ASP.NET Dynamic Compilation. |
Precompile to create a single assembly for each Web UI content file by using Aspnet_compiler.exe with the fixednames option. |
When you precompile with the fixednames option, you can make incremental updates to units as small as individual pages and redeploy only the changed pages. You can create both updatable and non-updatable precompiled sites by using the u option with the fixednames option. The fixednames option does not affect how you merge assemblies later by using the Merge tool. For a large site, the large number of assemblies that is created by the fixednames option can cause issues with release management or deployment. For more information, see ASP.NET Compilation Tool (Aspnet_compiler.exe). |
Merge to create an assembly for each Web UI content folder by using Aspnet_merge.exe with the prefix option. |
In this scenario, you can control assemblies at the UI content folder level. This scenario is like omitting the fixenames option when you use the Compilation tool. The difference is that the Merge tool gives you more control over the names of final assemblies that are derived from the root folder and from user-defined content folders. Top-level assemblies and static content are not affected. A potential drawback of this scenario is that if a file in a folder changes, you must redeploy the folder assembly and the modified page. You can merge both updatable and non-updatable precompiled sites by using the prefix option. This scenario is the default scenario if you run the Merge tool without options. |
Merge to create a single assembly for all the Web UI content files by using Aspnet_merge.exe with the w option. |
In this scenario, all UI content is merged into one assembly that has the name that you specify in the assemblyname parameter. This reduces the total number of assemblies in the final deployed site. However, it also requires that you redeploy the UI content assembly if any content file changes. Top-level assemblies and static content are not affected. |
Merge to create a single assembly for the whole Web site by using Aspnet_merge.exe with the o option. |
In this scenario, the final deployed site contains just one assembly that has the name that you specify in the assemblyname parameter. A single assembly makes it simple to deploy the site. However, it means that if any content anywhere in the site changes, you must re-create and redeploy the site assembly. Top-level assemblies (App_Code, App_GlobalResources, and App_WebReferences) are affected because they are included in the single assembly. Static content is unaffected. |
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.
Folder in precompiled site |
Merged assembly name using no Aspnet_merge.exe options |
|---|---|
\ |
Root.dll |
Admin |
Admin.dll |
The following table shows the merged assembly names when you use the prefix option and the NewName parameter.
Folder in precompiled site |
Merged assembly name using prefix Aspnet_merge.exe option |
|---|---|
\ |
NewName.dll |
Admin |
NewName.Admin.dll |
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 Web UI content of the precompiled site in the C:\PrecompiledSite directory into a single assembly and names the resulting assembly MyApp.dll.
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.
Version of .NET Framework |
Location of Aspnet_merge.exe file |
|---|---|
.NET Framework version 2.0, version 3.0, and version 3.5 (32-bit systems) |
C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin |
.NET Framework version 2.0, version 3.0, and version 3.5 (64-bit systems) |
C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin |
.NET Framework version 4 (32-bit systems) |
C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools |
.NET Framework version 4 (64-bit systems) |
C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools |
See Also
Reference
AllowPartiallyTrustedCallersAttribute
ASP.NET Compilation Tool (Aspnet_compiler.exe)
Concepts
.NET Framework Multi-Targeting for ASP.NET Web Projects
ASP.NET Side-by-Side Execution Overview