ASP.NET 合并工具 (Aspnet_merge.exe)

更新：2007 年 11 月

ASP.NET 合并工具 (Aspnet_merge.exe) 允许您合并和管理由 ASP.NET 编译工具 (Aspnet_compiler.exe) 创建的程序集。ASP.NET 合并工具可以处理使用 ASP.NET 2.0 版或更高版本创建的程序集。

可以使用 ASP.NET 编译工具预编译应用程序以进行部署。该工具为目标网站中的每个内容文件夹创建一个程序集，或者为每个内容文件创建一个程序集。ASP.NET 合并工具让您在进行部署和发布管理时拥有更大的灵活性。该工具允许您执行下列操作：

• 为整个网站创建一个程序集。

• 为每个网站文件夹创建一个程序集，并向程序集名称添加前缀。

• 仅为页面和控件等网站用户界面 (UI) 元素创建一个程序集。

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

参数

选项

选项	说明
-keyfile filename	指定 AssemblyKeyFileAttribute 属性应该应用于已编译的程序集。该属性指定包含用于生成强名称的公钥和私钥对的文件的名称。 如果输入程序集经过签名且合并工具没有对程序集签名，您将收到一条警告密钥已被移除的消息。 如果未指定密钥文件名且一个程序集有公钥而另一个程序集没有，则合并工具将失败。
-delaysign	指定 AssemblyDelaySignAttribute 属性应该应用于生成的程序集。此属性指定应该只使用公钥标记（而不使用公钥/私钥对）为程序集签名。 此选项必须与 -keyfile 选项一起使用。如果在代码文件中已经将该属性应用于程序集，合并工具将引发一个异常。 使用 delaysign 选项时，如果未启用强名称验证，合并工具生成的代码可以在得到签名之前运行。如果未启用强名称验证，请确保在签名完成之前的一段时间内该代码不会轻易遭到恶意用户的攻击。
-o assemblyname	为所有 Web UI 内容和顶级程序集合并后的单个程序集指定名称。文件扩展名为 .compiled 的所有文件都将修改为引用该单个程序集。（具有 .compiled 扩展名的文件是从 .aspx、.master 和 .ascx 文件等内容进行编译的。） 此选项不能与 w 选项或 prefix 选项一起使用。assemblyname 参数是必需的。
-w assemblyname	为所有 Web UI 内容（页面和用户控件）合并后的单个程序集指定名称。所有已编译的 .aspx、.master 和 .ascx 文件都将修改为引用该单个程序集。这样，更新 UI 元素和更新代码就可以单独进行了。 不合并本地资源和全局资源的顶级程序集。 此选项不能与 o 选项或 prefix 选项一起使用。assemblyname 参数是必需的。
-prefix prefix	为程序集名称指定前缀。根文件夹程序集仅用 prefix 参数作为其程序集名称。子文件夹程序集则用 prefix 参数与子文件夹名称的组合作为其程序集名称。例如，如果子文件夹的名称为 Admin，则产生的程序集将命名为 prefix.Admin.dll。 对于无法更新的网站，编译工具将主题和本地资源编译成 Bin 文件夹内单独的程序集。对于可以更新的网站，主题和本地资源没有编译成 Bin 文件夹内的程序集。而是将它们保留在应用程序中它们的原始文件夹内。此外，对于可更新站点，合并工具修改 .aspx、.master 和 .ascx 文件，以指向这些文件所在文件夹的合并后的新程序集。 此选项不能与 o 选项或 w 选项一起使用。prefix 参数是必需的。
-copyattrs assemblyfile	指定应该向合并后的一个或多个程序集分配与指定程序集相同的程序集属性。如果未指定 assemblyFile，即使 App_Code.dll 顶级程序集未包含在合并输出中，仍将使用 App_Code 程序集。如果要合并的程序集与 assemblyFile 程序集之间有不一致的属性，则将引发一个错误。使用 a 选项忽略不一致属性检查，或者使用 allowattrs 选项指定要从该检查中排除的属性。 有关一致性检查不包括的属性，请参见表中其他位置有关 allowattrs 选项的说明。
-debug	指定应该在合并后的程序集中保留调试输出。
-nologo	取消显示版权信息。
-errorstack	指定该工具应在未能编译应用程序时包括堆栈跟踪信息。
-r	移除主代码程序集（App_Code 文件夹中的代码）的 .compiled 文件。如果应用程序包含对主代码程序集的显式类型引用，则不要使用此选项。
-xmldocs	合并与输入程序集相关联的 XML 文档文件。XML 文件包含在已合并站点的 Bin 文件夹中。
-a	强制合并工具合并没有全部应用 AllowPartiallyTrustedCallersAttribute 或者具有不一致属性的程序集。AllowPartiallyTrustedCallersAttribute 允许部分受信任的调用方访问程序集，该属性在编译工具进行编译期间指定。 重要说明： 使用 a 选项时，将使用 AllowPartiallyTrustedCallersAttribute 来标记以前未标记为允许部分受信任的调用方的已合并程序集。这样便允许部分受信任的代码调用程序集。
-log logfile	将消息写入指定文件。
-allowattrs textfile	指定一个文件，该文件包含在该工具检查已合并程序集中属性的一致性时要排除的属性。该文件的每一行可以是属性的完全限定名或是完全限定的命名空间。如果指定的是命名空间，则该命名空间中的所有属性都将被排除。每个属性或命名空间都应在单独的一行上。 不必显式指定某些属性。合并工具在遇到下列属性时会输出一个警告，然后继续进行处理。 System.CodeDom.Compiler.GeneratedCodeAttribute System.Runtime.CompilerServices.CompilationRelaxationsAttribute System.Runtime.CompilerServices.RuntimeCompatibilityAttribute System.Diagnostics.DebuggableAttribute Microsoft.JScript.ReferenceAttribute
-?	显示该工具的命令语法和选项。

备注

可以就地编译 ASP.NET Web 应用程序，也可以预编译它们以部署到某个目标位置（例如成品服务器）。就地编译应用程序称为“动态编译”，适用于快速开发方案。可以通过以下两种方式之一预编译应用程序以进行部署：

• 编译并移除所有源文件，例如代码隐藏文件和标记文件。

• 编译并保留标记文件，以使其能被更新。

预编译网站时，ASP.NET 合并工具提供的灵活性比单独使用 ASP.NET 编译工具可获得的灵活性更大。

ASP.NET 合并工具合并 ASP.NET 编译工具的输出以产生程序集。这些合并的程序集可以改进大型网站的发布管理和部署。可以通过以下三种方式来使用 ASP.NET 合并工具：

• 将所有输出合并成一个程序集。

• 将每个文件夹的 Web UI 内容（网页、外观等）合并成自己的程序集。

• 将站点中的所有 Web UI 内容合并成一个程序集。

下面的几节将介绍这些方案。有关使用 ASP.NET 合并工具的示例，请参见位于 MSDN 网站上的 Managing ASP.NET Precompiled Output for Deployment Using the aspnet_merge.exe Command（使用 aspnet_merge.exe 命令管理 ASP.NET 预编译的输出以进行部署）。

ASP.NET 合并工具包含在 Visual Studio Web Deployment Projects（Visual Studio Web 部署项目）中，后者是 Visual Studio 的外接程序，它允许您管理生成配置，指定预先生成任务和后期生成任务以及合并程序集。有关更多信息，请参见 Using Web Deployment Projects with Visual Studio 2005（通过 Visual Studio 2005 使用 Web 部署项目）。

程序集组

编译工具会以不同方式创建程序集，具体取决于源文件和文件夹的类型。可以将编译工具的输出分为两个程序集组。合并工具将以不同方式合并这两个程序集组。

这两个程序集组如下所示：

• Web UI 内容程序集，这些程序集从 .aspx、.ascx、.master、.ashx、.skin 等 Web UI 内容文件和本地 .resx 文件（位于 App_LocalResources 文件夹中）生成。这些程序集的合并方式取决于预编译站点是否可更新，而可更新与否由编译工具的 u 选项决定。如果编译的站点可更新，则可以更新 UI 内容而无需重新编译该站点。当网站可更新时，内容文件会保留在它们的原始文件夹内并且只合并相关联的代码文件。如果站点不可更新，则将从其原始文件夹中移除 .ascx、.master 和 .skin 内容文件。ASP.NET .aspx 文件将替换为没有内容的标记文件。在这种情况下，将合并 UI 内容和代码。

• 顶级程序集，这些程序集从 App_Code、App_GlobalResources、App_WebReferences 等应用程序文件夹中生成。还为 Global.asax 等特殊文件生成顶级程序集。始终在部署站点的 Bin 文件夹中对顶级程序集进行编译。最终部署站点将没有 App_Code、App_GlobalResources 或 App_WebReferences 文件夹，也没有 Global.asax 文件。而最终部署站点的 Bin 目录中将有一个或多个程序集，具体取决于与合并工具一起使用的选项。同样会始终编译用户定义的文件夹，只不过在用户定义的文件夹内有 UI 内容文件时，最终部署站点将保留这些文件夹。有关保留文件夹的更多信息，请参见 ASP.NET 网站布局。

静态内容（如具有 .css、.gif、.htm、.html、.jpg、.js 等文件扩展名的文件）保留在预编译目录结构中它们各自的位置。合并工具不移动或修改它们。

编译和合并方案

借助 ASP.NET 2.0，您可以结合使用动态编译、利用编译工具的预编译以及利用合并工具的合并来实现部署和发布管理目标。下表列出了不同的编译和合并方案，并着重介绍应该使用合并工具的情况。

合并应用程序以进行部署

通过运行合并工具并使用 applicationPath 参数指定预编译站点的位置来合并网站的程序集。ASP.NET 合并工具就地合并预编译站点。换言之，它不会创建预编译站点的新合并副本。applicationPath 参数可以是 Web 应用程序的最终位置。或者，还可以通过复制目录等方式进一步部署编译后的应用程序。

当合并工具合并预编译站点时，它将保留动态文件显示在预编译步骤中的位置。合并工具对动态文件的内容所做的唯一更改是更改 @ Page、@ Control 和 @ Master 指令。它确保具有这些指令的文件从 Bin 文件夹中正确的合并程序集中继承。有关编译工具如何处理文件类型的详细信息，请参见 ASP.NET 编译工具 (Aspnet_compiler.exe) 的“备注”部分

对于从用户定义的文件夹（包括根站点文件夹）中派生的程序集，一些合并选项创建的名称可能不同于预编译站点中显示的名称。例如，下表显示了不对合并工具使用任何选项时合并后的程序集的名称。每个用户定义的文件夹的程序集名称是 App_Web_nnnn.dll，其中，nnnn 是内部生成的哈希值。

下表显示了使用 prefix 选项和 NewName 参数时合并后的程序集的名称。

在不可更新的合并站点中对主题进行不同的处理。在未合并的预编译站点中，每个主题都有单独的程序集。每个程序集都命名为 App_Theme_主题名.dll。在合并的站点中，有一个名称为 Theme.dll 的程序集。如果预编译站点可更新，则在合并的 Bin 文件夹内没有基于主题的程序集。

合并过程疑难解答

在编译或合并网站时，程序集的路径可能会长于 Microsoft Windows 中文件路径的最大允许长度。在此情况下，当您从合并后的程序集中请求资源时，则会引发 HttpException 错误，指示该资源没有预编译并且无法被请求。

Microsoft Windows 中最大文件路径长度为 260 个字符。如果程序集的路径超过此限制，则必须缩短网站或其子文件夹的路径。您还必须通过使用 hostingEnvironment 元素的 ShadowCopyBinAssemblies 属性在 Web.config 文件中禁用影像复制。有关文件名的更多信息，请参见位于 MSDN 网站上的 Naming a File（文件命名）。

使用合并工具与 o 选项为站点创建单个程序集时，如果合并过程创建循环引用，则将发生错误。有两种方法适合这种情况：

• 改用 w 选项，这样包含循环引用的源文件将一直为外部引用并且不被合并。

• 将循环引用中涉及到控件分离到不同目录中。

合并具有不一致属性的程序集时，请遵循以下准则以确保合并操作成功：

• 使用 allowattrs 选项列出不一致的属性。

• 使用 copyattrs 选项，并确保所有要合并的程序集都具有匹配的属性。

• 使用 a 选项。

签名程序集

delaysign 和 keyfile 选项允许您使用合并工具创建强名称程序集而无需使用强名称工具 (Sn.exe)。delaysign 选项对应于 AssemblyDelaySignAttribute 属性，keyfile 选项对应于 AssemblyKeyFileAttribute 属性。

每个选项将对应的属性应用于合并的程序集。所应用的属性 (Attribute) 使用 AllowMultiple 属性 (Property) 设置为 false 的 AttributeUsageAttribute 属性 (Attribute) 进行标记。因此，在合并已使用这些属性之一标记的程序集时，如果您使用了这些选项，合并将失败。

示例

下面的命令合并 C:\PrecompiledSite 目录中预编译站点的程序集。

Aspnet_merge C:\PrecompiledSite

下面的命令合并 C:\PrecompiledSite 目录中预编译站点的程序集，并使用 KeyFile.snk 文件对合并的程序集签名。在合并的站点中，每个预编译站点文件夹都有一个程序集。

Aspnet_merge C:\PrecompiledSite -keyfile KeyFile.snk

下面的命令将 C:\PrecompiledSite 目录中预编译站点的所有程序集合并成一个程序集，并将生成的程序集命名为 MyApp.dll。在合并的站点中，所有网站 UI 内容有一个程序集。

Aspnet_merge C:\PrecompiledSite -w MyApp.dll

下面的命令将 C:\PrecompiledSite 目录中预编译站点的所有程序集合并成一个程序集，并将生成的程序集命名为 MyApp.dll。

Aspnet_merge C:\PrecompiledSite -o MyApp.dll

请参见

概念

延迟为程序集签名

具有强名称的程序集

参考

AssemblyKeyFileAttribute

AssemblyKeyNameAttribute

AssemblyDelaySignAttribute

AllowPartiallyTrustedCallersAttribute

.NET Framework 工具

强名称工具 (Sn.exe)

ASP.NET 编译工具 (Aspnet_compiler.exe)