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

利用 ASP.NET 编译工具 (Aspnet_compiler.exe) 可以就地编译 ASP.NET Web 应用程序,也可以为部署到某个目标位置(例如成品服务器)编译 ASP.NET Web 应用程序。就地编译有助于提高应用程序的性能,因为在编译应用程序的过程中,最终用户可以避免第一次请求应用程序而导致的延迟。

可以通过以下两种方法之一执行用于部署的编译:一种方法移除所有源文件,例如代码隐藏文件和标记文件;另一种方法保留标记文件。

备注

早于 ASP.NET 2.0 版的 ASP.NET 版本中没有 ASP.NET 编译工具。

aspnet_compiler  [-?]
                 [-m metabasePath | -v virtualPath [-p physicalPath]]
                 [[-u] [-f] [-d] [-fixednames] targetDir]
                 [-c]
                 [-errorstack]
                 [-nologo]
                 [[-keyfile file | -keycontainer container ] [-aptca] [-delaysign]]

选项

选项 说明

-m metabasePath

指定要编译的应用程序的完整 IIS 元数据库路径。IIS 元数据库是用于配置 IIS 的分层信息存储区。例如,默认 IIS 网站的元数据库路径是 LM/W3SVC/1/ROOT。

此选项不能与 -v 选项或 -p 选项一起使用。

-v virtualPath

指定要编译的应用程序的虚拟路径。

如果还指定了 -p,则使用伴随的 physicalPath 参数的值来定位要编译的应用程序。否则,将使用 IIS 元数据库,并且此工具假定源文件位于默认网站(在 LM/W3SVC/1/ROOT 元数据库节点中指定)中。

此选项不能与 -m 选项一起使用。

-p physicalPath

指定包含要编译的应用程序的根目录的完整网络路径或完整本地磁盘路径。如果未指定 -p,则使用 IIS 元数据库来查找目录。

此选项必须与 -v 选项一起使用,不能与 -m 选项一起使用。

-u

指定 Aspnet_compiler.exe 应创建一个预编译的应用程序,该应用程序允许对内容(例如 .aspx 页)进行后续更新。

如果省略该选项,生成的应用程序将仅包含编译的文件,而无法在部署服务器上进行更新。只能通过更改源标记文件并重新编译来更新应用程序。

必须包括参数 targetDir。

-f

指定该工具应该改写 targetDir 目录及其子目录中的现有文件。

-d

重写应用程序源配置文件中定义的设置,强制在编译的应用程序中包括调试信息。否则,将不会发出调试输出。

不能将 -d 选项用于就地编译;就地编译使用调试选项的配置设置。

targetDir

将包含编译的应用程序的根目录的网络路径或本地磁盘路径。如果未包括 targetDir 参数,则就地编译应用程序。

-c

指定应完全重新生成要编译的应用程序。已经编译的组件将重新进行编译。如果省略此选项,该工具将仅生成应用程序中自上次执行编译以来被修改的那些部分。

-errorstack

指定该工具应在未能编译应用程序时包括堆栈跟踪信息。

-keyfile file

指定应该将 AssemblyKeyFileAttribute(指示包含用于生成强名称的公钥/私钥对的文件名)应用于编译好的程序集。

此选项必须与 -aptca 选项一起使用。如果代码文件中已经将该属性应用于程序集,Aspnet_compiler.exe 将引发一个异常。

-keycontainer container

指定应该将 AssemblyKeyNameAttribute(指示用于生成强名称的公钥/私钥对的容器名)应用于编译好的程序集。

此选项必须与 -aptca 选项一起使用。如果代码文件中已经将该属性应用于程序集,Aspnet_compiler.exe 将引发一个异常。

-aptca

指定应该将 AllowPartiallyTrustedCallersAttribute(允许部分受信任的调用方访问程序集)应用于 Aspnet_compiler.exe 生成的具有强名称的程序集。

此选项必须与 -keyfile-keycontainer 选项一起使用。如果代码文件中已经将该属性应用于程序集,Aspnet_compiler.exe 将引发一个异常。

-delaysign

指定应该将 AssemblyDelaySignAttribute(指示应该只使用公钥标记对程序集进行签名,而不使用公钥/私钥对)应用于生成的程序集。

此选项必须与 -keyfile-keycontainer 选项一起使用。如果代码文件中已经将该属性应用于程序集,Aspnet_compiler.exe 将引发一个异常。

使用 -delaysign 选项时,Aspnet_compilier.exe 生成的代码在完成代码签名之前即可运行。必须确保该代码在完成签名之前不易受到恶意用户的攻击。

-fixednames

指定应该为应用程序中的每一页生成一个程序集。每个程序集的名称使用原始页的虚拟路径,除非此名称超过操作系统的文件名限制。如果超过限制,将生成一个哈希值,并将其用于程序集名称。

不能将 -fixednames 选项用于就地编译;就地编译使用编译批处理模式的配置设置。

-nologo

取消显示版权信息。

-?

显示该工具的命令语法和选项。

备注

可以通过以下两种常用方式来使用 ASP.NET 编译工具:就地编译和为部署进行的编译,后者需要指定目标输出目录。下面的几节将介绍这些方案。

就地编译应用程序

ASP.NET 编译工具可以就地编译应用程序,也就是说,它模仿对应用程序发出多个请求的行为,从而导致进行常规编译。预编译站点的用户将不会遇到因第一次请求而编译页面带来的延迟。

请注意,如果使用的是模拟帐户,则该帐户和登录用户帐户都必须具有对目标的写访问权限,预编译才能成功。

就地预编译站点时,请注意下列事项:

  • 站点将保留它的文件和目录结构。

  • 服务器上必须具有供此站点使用的所有编程语言的编译器。

  • 如果任何文件编译失败,整个站点的编译将失败。

还可以在向应用程序添加新的源文件之后就地重新编译应用程序。除非包括 -c 选项,否则该工具仅编译新文件和更改过的文件。

备注

编译包含嵌套应用程序的应用程序时,不会编译嵌套应用程序。必须单独编译嵌套应用程序。

为进行部署编译应用程序

通过指定 targetDir 参数来编译应用程序以进行部署(编译到某个目标位置)。targetDir 可以是 Web 应用程序的最终位置;也可以进一步部署编译好的应用程序。

使用 -u 选项将以下面的方式编译应用程序:可以对编译好的应用程序中的某些文件做出更改,而无需重新编译该应用程序。Aspnet_compiler.exe 区分静态和动态文件类型之间的不同,并在创建生成的应用程序时,以不同的方式对它们进行处理。

静态文件类型是指那些没有关联的编译器或生成提供程序的文件类型,例如具有 .css、.gif、.htm、.html、.jpg、.js 等扩展名的文件。这些文件只是复制到目标位置,并且在保留的目录结构中保持它们的相对位置。

动态文件类型是指那些具有关联的编译器或生成提供程序的文件类型,包括具有 ASP.NET 特定文件扩展名(如 .asax、.ascx、.ashx、.aspx、.browser、.master 等等)的文件。ASP.NET 编译工具从这些文件生成程序集。如果省略 -u 选项,该工具还会创建具有文件扩展名 .COMPILED 的文件,这些文件将原始源文件映射到它们的程序集。为确保保留应用程序源的目录结构,该工具在目标应用程序的相应位置中生成占位符文件。

必须使用 -u 选项,以指示可以修改编译好的应用程序的内容。否则,将忽略后续修改或者导致运行时错误。

下表描述了在包括 -u 选项的情况下,ASP.NET 编译工具是如何处理不同的文件类型的。

文件类型 编译器操作

.ascx、.aspx、.master

这些文件将被拆分为标记和源代码,其中包括代码隐藏文件。源代码编译到程序集中,其名称派生于哈希算法,且程序集放置在 Bin 目录中。任何内联代码(即包含在 <script runat="server"> 元素中的代码)都包括在标记中,不进行编译。将创建与源文件同名的新文件来包含标记,新文件位于相应的输出目录中。

.ashx、.asmx

这些文件不进行编译,而是原样移动到输出目录中。如果希望编译处理程序代码,请将这些代码放入 App_Code 目录的源代码文件中。

.cs、.vb、.jsl、.cpp

(不包括先前列出的文件类型的代码隐藏文件)

这些文件会进行编译,并作为资源包含在引用它们的程序集中。源文件不复制到输出目录中。如果不引用代码文件,则这些文件不会进行编译。

自定义文件类型

这些文件不进行编译。这些文件复制到相应的输出目录中。

App_Code 子目录中的源代码文件

这些文件编译到程序集中,且放置在 Bin 目录中。

备注

App_Code 目录中的静态文件类型不复制到输出目录中。

App_GlobalResources 子目录中的 .resx 和 .resource 文件

这些文件编译到程序集中,且放置在 Bin 目录中。不会在主输出目录中创建 App_GlobalResources 子目录,且不会将源目录中的 .resx 或 .resources 文件复制到输出目录中。

备注

App_GlobalResources 子目录中的资源文件先编译到程序集中,然后编译 App_Code 子目录中的代码。不支持在编译之后修改资源文件。

App_LocalResources 子目录中的 .resx 和 .resource 文件

这些文件不进行编译,它们复制到相应的输出目录中。

App_Themes 子目录中的 .skin 文件

.skin 文件和静态主题文件不进行编译,它们复制到相应的输出目录中。

.browser

Web.config

静态文件类型

Bin 目录中已存在的程序集

这些文件原样复制到输出目录中。

下表描述了在省略 -u 选项的情况下,ASP.NET 编译工具是如何处理不同的文件类型的。

备注

不会提供阻止您修改已编译应用程序的源代码的警告。

文件类型 编译器操作

.aspx、.asmx、.ashx、.master

这些文件被拆分为标记和源代码,其中包括代码隐藏文件和包含在 <script runat="server"> 元素中的任何代码。源代码编译到程序集中,其名称派生于哈希算法。生成的程序集放置在 Bin 目录中。任何内联代码(即包含在 <%%> 括号之间的代码)包括在标记中,不进行编译。编译器将创建新文件,以包括与源文件同名的标记。这些生成的文件放置在 Bin 目录中。编译器还会创建与源文件同名的文件,但新创建的文件具有扩展名 .COMPILED 且包含映射信息。.COMPILED 文件放置在与源文件的原始位置相对应的输出目录中。

.ascx

这些文件被拆分为标记和源代码。源代码编译到程序集中,且放置在 Bin 目录中,其名称派生于哈希算法。不生成标记文件。

.cs、.vb、.jsl、.cpp

(不包括先前列出的文件类型的代码隐藏文件)

从 .ascx、.ashx 或 .aspx 文件生成的程序集所引用的源代码编译到程序集中,且放置在 Bin 目录中。不复制源文件。

自定义文件类型

这些文件像动态文件一样进行编译。编译器可以将映射文件放置在输出目录中,具体取决于它们所基于的文件类型。

App_Code 子目录中的文件

该子目录中的源代码文件编译到程序集中,且放置在 Bin 目录中。

备注

App_Code 目录中的静态文件类型不复制到输出目录中。

App_GlobalResources 子目录中的文件

这些文件编译到程序集中,且放置在 Bin 目录中。不会在主输出目录下创建 App_GlobalResources 子目录。如果配置文件指定了 appliesTo="All",则 .resx 和 .resources 文件复制到输出目录中。如果这些文件被 BuildProvider 引用,则不会被复制。

App_LocalResources 子目录中的 .resx 和 .resource 文件

这些文件编译到程序集中,具有唯一的名称,且放置在 Bin 目录中。不会将 .resx 或 .resource 文件复制到输出目录中。

App_Themes 子目录中的 .skin 文件

主题文件编译到程序集中,且放置在 Bin 目录中。为 .skin 文件创建 stub(存根)文件,并将它们放置在相应的输出目录中。静态文件(如 .css)复制到输出目录中。

.browser

Web.config

静态文件类型

Bin 目录中已存在的程序集

这些文件原样复制到输出目录中。

固定的程序集名称

某些方案(例如使用 MSI Windows Installer 部署 Web 应用程序)要求使用一致的文件名和内容以及一致的目录结构,以标识要更新的程序集或配置设置。在这些情况下,可以使用 -fixednames 选项来指定 ASP.NET 编译工具应该为每个源文件编译一个程序集,而不是使用将多页编译到程序集中的方式。这样会导致生成大量的程序集,因此,如果您担心可伸缩性,则应小心使用此选项。

强名称编译

提供了 -aptca-delaysign-keycontainer-keyfile 选项,以便您可以使用 Aspnet_compiler.exe 来创建具有强名称的程序集,而无需另外使用强名称工具 (Sn.exe)。这些选项分别对应于 AllowPartiallyTrustedCallersAttributeAssemblyDelaySignAttributeAssemblyKeyNameAttributeAssemblyKeyFileAttribute。由于每个选项都将相应的属性应用于编译好的程序集,且使用 AttributeUsageAttribute(其 AllowMultiple 属性设置为 false)对属性进行了标记,因此,在已经使用这些属性之一进行了标记的源代码上使用这些密钥会导致编译失败。

关联的 ASP.NET 类

通过 System.Web.Compilation 命名空间中的几个类,可以允许代码从 IIS 环境之外访问或调用 Aspnet_compiler.exe。ClientBuildManager 类提供了 PrecompileApplication 方法用于编译应用程序。ClientBuildManager 类还可以与 ClientBuildManagerParameter 类一起使用,允许您指定对应于此工具使用的选项的 PrecompilationFlags,同样,还允许您指定强名称密钥。

示例

下面的命令就地编译 WebApplication1 应用程序:

Aspnet_compiler -v /WebApplication1

下面的命令就地编译 WebApplication1 应用程序,如果必须报告错误,该工具还会添加堆栈跟踪信息。

Aspnet_compiler -v /WebApplication1 -errorstack

下面的命令使用物理目录路径,编译用于部署的 WebApplication1 应用程序。它还向输出程序集添加两个属性。它使用 -keyfile 选项添加一个 AssemblyKeyFileAttribute 属性,该属性指定 Key.sn 文件包含公钥/私钥对信息,该工具应使用这些信息为生成的程序集指定强名称。该命令还使用 -aptca 选项将一个 AllowPartiallyTrustedCallersAttribute 属性添加到生成的程序集。编译后的 Web 应用程序将在目录 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

下面的命令在默认的元数据库路径下编译 WebService2 服务,并用编译后的应用程序改写 SampleWebService 目标目录。

Aspnet_compiler -m /LM/W3SVC/1/ROOT/WebService2 -f c:\InetPub\wwwroot\SampleWebService

请参见

参考

.NET Framework 工具
强名称工具 (Sn.exe)
ASP.NET IIS 注册工具 (Aspnet_regiis.exe)
AssemblyKeyFileAttribute
AssemblyKeyNameAttribute
AssemblyDelaySignAttribute
AllowPartiallyTrustedCallersAttribute

概念

延迟为程序集签名
具有强名称的程序集