ASP.NET Web applications can be compiled in place, or they can be precompiled for deployment to a target location, such as a production server. Compiling an application in place is called dynamic compilation and is useful in rapid development scenarios. Precompiling an application for deployment can be performed in one of two ways:
Compiling and removing all source files, such as code-behind and markup files.
Compiling and retaining the markup files so that they can be updated.
The ASP.NET Merge tool provides additional flexibility when you precompile the Web site beyond what you can achieve with the ASP.NET Compilation tool alone.
The ASP.NET Merge tool merges the output of the ASP.NET Compilation tool to produce assemblies. These merged assemblies can improve release management and deployment for large Web sites. You can use the ASP.NET Merge tool in three ways:
Merge all 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.
The following sections describe these scenarios. For examples of using the ASP.NET Merge tool, see Managing ASP.NET Precompiled Output for Deployment Using the aspnet_merge.exe Command on the MSDN Web site.
The ASP.NET Merge tool is included in Visual Studio Web Deployment Projects, an add-in for Visual Studio that lets you manage build configurations, specify pre-build and post-build tasks, and merge assemblies. For more information, see Using Web Deployment Projects with Visual Studio 2005.
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.
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:
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.