ASP.NET 編譯工具 (Aspnet_compiler.exe)

更新：2007 年 11 月

ASP.NET 編譯工具 (Aspnet_compiler.exe) 能讓您就地編譯 ASP.NET Web 應用程式，或是在編譯後部署至實際執行伺服器 (Production Server) 等目標位置。在編譯應用程式時，就地編譯有助於提升應用程式的效能，因為使用者第一次要求應用程式時並不會感到延遲。

編譯後進行部署則可以用兩種方式進行：一是移除所有原始程式檔 (例如，程式碼後置 (Code-Behind) 檔案和標記檔)，另一種則是保留標記檔。

注意事項：
ASP.NET 2.0 之前的版本並未提供 ASP.NET 編譯工具。

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

選項

備註

ASP.NET 編譯工具一般有兩種用法：一是就地編譯，一是編譯後進行部署，後者需指定目標輸出目錄。下列各節描述這些案例。

就地編譯應用程式

ASP.NET 編譯工具可以就地編譯應用程式，亦即模擬向應用程式提出多個要求的行為，藉此產生一般的編譯。先行編譯之網站的使用者並不會感覺到第一個要求所進行之網頁編譯而造成的延遲。

請注意若您是使用模擬帳戶，則該帳戶和登入的使用者帳戶都必須具有目標的寫入權限，才能讓先行編譯成功。

就地先行編譯網站時，會出現下列情形：

• 網站仍維持其檔案和目錄結構。

• 您必須具備伺服器上的網站所使用之所有程式語言編譯器。

• 如果任何檔案發生編譯失敗，則整個網站的編譯也會失敗。

您也可以在應用程式加入新的原始程式檔之後，重新編譯該應用程式。除非加入了 -c 選項，否則工具只會編譯新增或變更過的檔案。

注意事項：
編譯包含巢狀應用程式的應用程式，並不會連同該巢狀應用程式也一起編譯，巢狀應用程式必須個別進行編譯。

注意事項：
當您編譯含有主版頁面 (Master Page) 的 Web 應用程式時，如果將應用程式編譯為可更新的站台而發生命名衝突時，編譯可能會失敗。如果主版頁面的名稱與衍生自主版頁面之內容頁面的命名空間名稱相符，就可能發生衝突(此繼承關係是由 @ Page 指示詞的 Inherits 屬性建立)。若要解決此問題，您可以變更主版頁面的類別名稱、變更命名空間名稱，或將應用程式編譯為不可更新。

編譯應用程式以進行部署

只要指定 targetDir 參數，即可編譯應用程式以進行部署 (編譯至目標位置)。targetDir 可以是 Web 應用程式的最終位置，也就是說已編譯的應用程式可以進一步地進行部署。

若使用 -u 選項編譯應用程式，您可以只修改已編譯應用程式中的特定檔案，而不需重新編譯整個應用程式。Aspnet_compiler.exe 會區分靜態和動態檔案類型，並在建立產生的應用程式時，以不同的方式處理這兩種檔案類型。

靜態檔案類型是指沒有關聯編譯器或組建提供者的檔案類型，例如使用 .css、.gif、.htm、.html、.jpg 和 .js 和其他副檔名的檔案。這些檔案只會複製到目標位置，並維持它們在目錄結構中的相對位置。

動態檔案類型是指，具有關聯編譯器或組建提供者的檔案類型，其中包括具有諸如 .asax、.ascx、.ashx、.aspx、.browser 和 .master 等 ASP.NET 特定副檔名的檔案。ASP.NET 編譯工具會從這些檔案產生組件。如果省略 -u 選項，工具還是會建立副檔名為 .COMPILED 的檔案，將原始程式檔對應至它們的組件。為了確保已保留應用程式來源的目錄結構，工具會在目標應用程式的對應位置產生預留位置檔案。

您必須使用 -u 選項來指示已編譯的應用程式是可以修改的，否則後續的修改會遭到忽略，或造成執行階段錯誤。

下列表格描述加上 -u 選項時，ASP.NET 編譯工具如何處理不同的檔案類型。

檔案類型	編譯器動作
.ascx、aspx、.master	這些檔案分為標記和原始程式碼，其中包含程式碼後置的檔案。原始程式碼會編譯成組件，而組件的名稱衍生自雜湊演算法的組件，並且這些組件會放在 Bin 目錄中。所有內嵌 (Inline) 程式碼 (也就是以 <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_Code 子目錄中的程式碼之前，必須先將 App_GlobalResources 子目錄中的資源檔編譯成組件。不支援編譯資源檔後再行修改。
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 檔	主題 (Theme) 會編譯成組件並放在 Bin 目錄中。Stub 檔是為 .skin 檔建立的，並且會放在對應的輸出目錄中。靜態檔案 (例如 .css) 會複製到輸出目錄。
.browser Web.config 靜態檔案類型 組件已經在 Bin 目錄中	這些檔案會以現況複製到輸出目錄。

固定的組件名稱

在諸如使用 MSI Windows Installer 部署 Web 應用程式的某些案例中，必須使用一致的檔名和內容以及一致的目錄結構，才能識別組件或組態設定以進行更新。在那些情況中，您可以使用 -fixednames 選項來指定 ASP.NET 編譯工具必須為每個原始程式檔編譯組件，而不是使用 xxx，將數個網頁編譯成組件。但這麼做可能造成組件數目過於龐大，因此如果您擔心延展性 (Scalability) 的問題，請謹慎小心使用此選項。

強式名稱編譯

提供 -aptca、-delaysign、-keycontainer 和 -keyfile 等選項，是為了讓您能夠使用 Aspnet_compiler.exe 來建立強式名稱的組件，不需另外使用強式名稱工具 (Sn.exe)。這些選項分別對應到 AllowPartiallyTrustedCallersAttribute、AssemblyDelaySignAttribute、AssemblyKeyNameAttribute 和 AssemblyKeyFileAttribute。由於每個選項都會將對應的屬性 (Attribute) 套用至已編譯的組件，而且屬性 (Attribute) 會以 AttributeUsageAttribute 標示 (其 AllowMultiple 屬性 (Property) 設為 false)，因此，在已經以這其中一個屬性 (Attribute) 標示的原始程式碼上使用這些金鑰，將會造成編譯失敗。

關聯的 ASP.NET 類別

System.Web.Compilation 命名空間中的數個類別，都可以讓程式碼從 IIS 環境之外存取或叫用 (Invoke) 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

下列命令會編譯預設 Metabase 路徑下的 WebService2 服務，以編譯的應用程式覆寫 SampleWebService 目標目錄。

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

請參閱

概念

延遲簽署組件

強式名稱的組件

參考

AssemblyKeyFileAttribute

AssemblyKeyNameAttribute

AssemblyDelaySignAttribute

AllowPartiallyTrustedCallersAttribute

.NET Framework 工具

強式名稱工具 (Sn.exe)

ASP.NET IIS 註冊工具 (Aspnet_regiis.exe)