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]

引數

引數

描述

applicationPath

(必要項) 指定包含要建立組件之應用程式的資料夾名稱。這是預設合併作業。它所建立的組件會比編譯器的 fixednames 選項產生的數目少。

選項

選項

描述

-keyfile filename

指定 AssemblyKeyFileAttribute 屬性應套用到編譯的組件。這個屬性會指定包含公開和私密金鑰組 (用來產生強式名稱) 的檔案名稱。

如果輸入組件已簽署，但合併工具沒有簽署組件，您會收到訊息，警告金鑰已移除。

如果沒有指定金鑰檔名稱，當一個組件有公開金鑰，而另一個組件沒有時，合併工具會失敗。

-delaysign

指定 AssemblyDelaySignAttribute 屬性應套用到產生的組件。這個屬性會指定組件只能使用公開金鑰語彙基元 (Token) 而非公開和私密金鑰組來簽署。

這個選項必須與 -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 組件，即使 App_Code.dll 最上層組件未包含在合併輸出中。如果要合併的組件與 assemblyFile 組件之間有不一致的屬性，將會擲回錯誤。請使用 a 選項來略過不一致屬性檢查，或者使用 allowattrs 選項來指定要排除在檢查以外的屬性。

如需沒有包含在一致性檢查中的屬性，請參閱本表中其他有關 allowattrs 選項的描述。

-debug

指定偵錯輸出應保留在合併的組件中。

-nologo

隱藏著作權訊息。

-errorstack

指定如果工具無法編譯應用程式，便必須包含堆疊追蹤資訊。

-r

從主程式碼組件 (App_Code 資料夾中的程式碼) 移除 .compiled 檔案。如果應用程式含有主程式碼組件的明確型別參考，請不要使用這個選項。

-xmldocs

合併與輸入組件關聯的 XML 文件檔。合併網站的 Bin 資料夾會包含一個 XML 檔案。

-a

強制合併工具將並非全部都套用 AllowPartiallyTrustedCallersAttribute 的組件合併，或將擁有不一致屬性的組件合併。AllowPartiallyTrustedCallersAttribute 允許部分信任的呼叫端存取組件，這是在編譯期間由編譯工具指定的。

重要事項：

當您使用 a 選項時，先前未標記為允許部分信任呼叫端的合併組件，現在會使用 AllowPartiallyTrustedCallersAttribute 加以標記。這可讓部分信任的程式碼呼叫組件。

-log logfile

將訊息寫入指定的檔案。

-allowattrs textfile

指定工具在檢查合併組件中的屬性一致性時，包含要排除屬性的檔案。檔案中的每一行可以是屬性的完整名稱或完整的命名空間。如果指定命名空間，就會排除在該命名空間中找到的所有屬性。每個屬性或命名空間都應放在個別一行。

部分屬性並不需要明確指定。合併工具會在遇到下列屬性時輸出警告，然後再繼續處理。

-?

顯示工具的命令語法和選項。

備註

ASP.NET Web 應用程式可就地編譯，或可先行編譯再部署至實際執行伺服器 (Production Server) 等目標位置。就地編譯應用程式稱為「動態編譯」(Dynamic Compilation)，適合用於快速開發案例。先行編譯應用程式再部署則可以用兩種方式進行：

  • 編譯並移除所有原始程式檔 (Source File)，例如程式碼後置 (Code-Behind) 檔案和標記檔案。

  • 編譯並保留標記檔案，以便更新它們。

當您先行編譯網站時，搭配使用 ASP.NET 合併工具與單獨使用 ASP.NET 編譯工具相較，可提供更多的彈性。

ASP.NET 合併工具可合併 ASP.NET 編譯工具的輸出來產生組件。這些合併組件有助於大型網站的發行管理和部署。您可用三種方式來使用 ASP.NET 合併工具：

  • 將所有輸出合併成單一組件。

  • 將每個資料夾的 Web UI 內容 (網頁、面板等) 合併到其本身的組件。

  • 將網站中的所有 Web UI 內容合併成單一組件。

下列各節描述這些案例。如需使用 ASP.NET 合併工具的範例，請參閱 MSDN 網站上的使用 aspnet_merge.exe 的命令管理 ASP.NET 先行編譯的輸出以便進行部署 (英文)。

ASP.NET 合併工具隨附在 Visual Studio Web 開發專案中，是 Visual Studio 的增益集 (Add-In)，可讓您管理建置組態、指定建置前後的工作，以及合併組件。如需詳細資訊，請參閱在 Visual Studio 2005 中使用 Web 部署專案 (英文)。

組件群組

編譯工具會根據原始程式檔和資料夾的類型而定，以不同方式建立組件。編譯工具的輸出可分類為兩個「組件群組」(Assembly Group)。合併工具會以不同的方式合併這兩種組件群組。

這兩種組件群組如下：

  • Web UI 內容組件，這是從 Web UI 內容檔產生的，例如 .aspx、.ascx、.master、.ashx、.skin 和本機 .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 中，您可以將編譯工具的動態編譯和先行編譯功能與合併工具的合併功能搭配使用，以達成您的部署和發行管理目標。下表列出不同的編譯與合併案例，並特別說明何時應使用合併工具。

情節

備註

動態編譯 (無先行編譯)

動態編譯 (Compilation) 適合用於快速開發案例。當您按 F5 或 CTRL+F5 時，Visual Studio 便會使用動態編譯，但是只有您正在處理的網頁及其相依性會進行動態編譯。這可避免編譯整個網站。

如需詳細資訊，請參閱瞭解 ASP.NET 動態編譯。

藉由使用 Aspnet_compiler.exe 和 fixednames 選項來進行先行編譯，為每個 Web UI 內容檔建立單一組件

當您使用 fixednames 選項進行先行編譯時，可以將累加更新的單位設成個別網頁，然後只重新部署變更過的網頁。您可以使用 u 選項搭配 fixednames 選項，來建立可更新和不可更新的先行編譯網站。fixednames 選項不會影響您稍後使用合併工具來合併組件的方式。

若為大型網站，fixednames 選項會建立大量組件，而這可能會造成發行管理和部署的問題。

如需詳細資訊，請參閱 ASP.NET 編譯工具 (Aspnet_compiler.exe)。

藉由使用 Aspnet_merge.exe 和 prefix 選項來進行合併，為每個 Web UI 內容資料夾建立一個組件

在這個案例中，您可以在 UI 內容資料夾層級控制組件。這個案例就如同使用編譯工具時省略 fixenames 選項。差異在於，合併工具可讓您進一步控制衍生自根資料夾和使用者定義內容資料夾的最後組件名稱。最上層組件和靜態內容不受影響。

這個案例的缺點可能是如果資料夾中有檔案變更，就必須重新部署資料夾組件和變更過的網頁。

您可以使用 prefix 選項來合併可更新和不可更新的先行編譯網站。如果執行合併工具時沒有指定選項，這個案例就是預設案例。

藉由使用 Aspnet_merge.exe 和 w 選項來進行合併，為所有 Web UI 內容檔建立單一組件

在這個案例中，所有 UI 內容都會合併到一個組件，此組件會以您在 assemblyname 參數中指定的名稱命名。這可減少最後部署網站中的組件總數。不過，如果任何內容檔變更，您就必須重新部署 UI 內容組件。

最上層組件和靜態內容不受影響。

藉由使用 Aspnet_merge.exe 和 o 選項來進行合併，為整個網站建立單一組件

在這個案例中，最後部署的網站只包含一個組件，其名稱是您在 assemblyname 參數中所指定的名稱。單一組件可讓網站容易部署。不過，這表示如果網站中有任何一處的任何內容變更，就必須重新建立和重新部署網站組件。

最上層組件 (App_Code、App_GlobalResources 和 App_WebReferences) 由於包含在這個單一組件中，因此會受到影響。靜態內容不受影響。

合併應用程式以進行部署

您可以執行合併工具並使用 applicationPath 參數指定先行編譯網站的位置，來合併網站的組件。ASP.NET 合併工具會就地合併先行編譯的網站。也就是說，它不會建立先行編譯網站的新合併複本。The applicationPath 參數可以是 Web 應用程式的最終位置。或者，編譯的應用程式可再進一步部署，例如藉由複製目錄來部署。

當合併工具合併先行編譯的網站時，會保留動態檔案出現在先行編譯步驟中的位置。合併工具對動態檔案的內容所做的唯一變更，就是變更 @ Page、@ Control 和 @ Master 指示詞。這可確定具有這些指示詞的檔案繼承自 Bin 資料夾中的正確合併組件。如需編譯工具如何處理檔案類型的詳細資訊，請參閱 ASP.NET 編譯工具 (Aspnet_compiler.exe) 的＜備註＞一節。

對於衍生自使用者定義資料夾 (包括根網站資料夾) 的組件，部分合併選項可建立不同於先行編譯網站中所出現的名稱。例如，下表顯示在合併工具沒有使用選項時的合併組件名稱。每個使用者定義資料夾的組件名稱都是 App_Web_nnnn.dll，其中 nnnn 是內部產生的雜湊值。

先行編譯網站中的資料夾

不使用 Aspnet_merge.exe 選項時的合併組件名稱

\

Root.dll

Admin

Admin.dll

下表顯示使用 prefix 選項和 NewName 參數時的合併組件名稱。

先行編譯網站中的資料夾

使用 Aspnet_merge.exe 前置字元選項的合併組件名稱

\

NewName.dll

Admin

NewName.Admin.dll

在不可更新的合併網站中，佈景主題會以不同方式處理。在先行編譯的未合併網站中，每個佈景主題都各有一個組件。每個組件會命名為 App_Theme_ThemeName.dll。在合併的網站中，只有一個名為 Theme.dll 的組件。如果先行編譯的網站可以更新，合併的 Bin 資料夾中就沒有以佈景主題為基礎的組件。

合併程序疑難排解

編譯或合併網站時，組件的路徑可能會超過 Microsoft Windows 所允許的檔案路徑長度上限。在這種情況下，當您從合併的組件要求資源時，會擲回 HttpException 錯誤，指出資源未先行編譯，因此無法要求。

Microsoft Windows 的檔案路徑長度上限為 260 個字元。如果組件的路徑超過此限制，就必須縮短網站或其子資料夾的路徑。您可能也必須停用 Web.config 檔案中的陰影複製，方式是使用 hostingEnvironment 項目的 ShadowCopyBinAssemblies 屬性。如需檔案名稱的詳細資訊，請參閱 MSDN 網站上的命名檔案 (英文)。

當您使用合併工具和 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。在合併的網站中，所有 Web 網站 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)