ASP.NET 編譯工具 (Aspnet_compiler.exe)
更新：2007 年 11 月
ASP.NET 編譯工具 (Aspnet_compiler.exe) 能讓您就地編譯 ASP.NET Web 應用程式，或是在編譯後部署至實際執行伺服器 (Production Server) 等目標位置。在編譯應用程式時，就地編譯有助於提升應用程式的效能，因為使用者第一次要求應用程式時並不會感到延遲。
編譯後進行部署則可以用兩種方式進行：一是移除所有原始程式檔 (例如，程式碼後置 (Code-Behind) 檔案和標記檔)，另一種則是保留標記檔。
.gif "注意事項") 注意事項： |
|---|
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]]
選項
選項 |
說明 |
|---|---|
-m metabasePath |
指定要編譯之應用程式的完整 IIS Metabase 路徑。IIS Metabase 屬於階層式的資訊存放區，可以用來設定 IIS。例如，預設 IIS 網站的 Metabase 路徑為 LM/W3SVC/1/ROOT。 這個選項無法與 -v 或 -p 選項合併使用。 |
-v virtualPath |
指定要編譯之應用程式的虛擬路徑。 如果也指定了 -p，就會使用伴隨的 physicalPath 參數值找出要編譯的應用程式，否則會使用 IIS Metabase，並且工具假設原始程式檔位於預設網站 (在 LM/W3SVC/1/ROOT Metabase 節點中指定) 底下。 這個選項無法與 -m 選項合併使用。 |
-p physicalPath |
指定包含所要編譯之應用程式的根目錄完整網路路徑或本機磁碟路徑。如果未指定 -p，則會使用 IIS Metabase 尋找目錄。 這個選項必須與 -v 選項合併，無法和 -m 選項合併使用。 |
-u |
指定 Aspnet_compiler.exe 必須建立先行編譯的應用程式，以便後續更新內容 (例如 .aspx 網頁)。 如果省略此選項，產生的應用程式只會包含編譯過的檔案，而無法在部署伺服器上進行更新。您只能藉由變更原始標記檔並重新編譯，以更新此應用程式。 這個選項必須包含 targetDir 參數。 |
-f |
指定工具必須覆寫 targetDir 目錄及其子目錄中的現有檔案。 |
-d |
覆寫在應用程式的來源組態檔中定義的設定，以強制針對要加入已編譯應用程式的資訊進行偵錯，否則，不發出任何偵錯輸出。 您不能使用 -d 選項來進行就地編譯；就地編譯會接受偵錯選項的組態設定。 |
targetDir |
包含已編譯應用程式的根目錄網路路徑或本機磁碟路徑。如果未包含 targetDir 參數，便會就地編譯應用程式。 |
-c |
指定必須完整地重建要編譯的應用程式，已編譯過的元件也會再編譯一次。如果省略此選項，工具便只會建置 (Build) 上次編譯之後應用程式做過修改的部分。 |
-errorstack |
指定如果工具無法編譯應用程式，便必須包含堆疊追蹤資訊。 |
-keyfile file |
指定必須將表示公開/私密金鑰組 (用來產生強式名稱 (Strong Name)) 所在檔案之名稱的 AssemblyKeyFileAttribute 套用至已編譯的組件。 這個選項必須與 -aptca 選項合併使用。如果屬性已套用至程式碼檔中的組件，則 Aspnet_compiler.exe 會擲回例外狀況。 |
-keycontainer container |
指定必須將表示公開/私密金鑰組 (用來產生強式名稱) 之容器名稱的 AssemblyKeyNameAttribute 套用至已編譯的組件。 這個選項必須與 -aptca 選項合併使用。如果屬性已套用至程式碼檔中的組件，則 Aspnet_compiler.exe 會擲回例外狀況。 |
-aptca |
指定必須將允許部分信任之呼叫端存取組件的 AllowPartiallyTrustedCallersAttribute 套用至 Aspnet_compiler.exe 產生的強式名稱組件。 這個選項必須與 -keyfile 或 -keycontainer 選項合併使用。如果屬性已套用至程式碼檔中的組件，則 Aspnet_compiler.exe 會擲回例外狀況。 |
-delaysign |
指定必須將 AssemblyDelaySignAttribute 套用至產生的組件，它表示組件只能使用公開金鑰語彙基元 (Token) 而非公開/私密金鑰組來簽署。 這個選項必須與 -keyfile 或 -keycontainer 選項合併使用。如果屬性已套用至程式碼檔中的組件，則 Aspnet_compiler.exe 會擲回例外狀況。 當您使用 -delaysign 選項時，Aspnet_compilier.exe 所產生的程式碼即可在程式碼完成簽署之前執行。您必須確定此段程式碼在簽署完成之前不會輕易遭到惡意使用者攻擊。 |
-fixednames |
指定必須為應用程式中的每個頁面產生一個組件。每個組件都必須以原始頁面的虛擬路徑來命名，除非名稱長度超過作業系統的檔名限制，才會產生雜湊做為組件名稱。 您不能使用 -fixednames 選項來進行就地編譯；就地編譯會接受編譯批次模式的組態設定。 |
-nologo |
隱藏著作權訊息。 |
-? |
顯示工具的命令語法和選項。 |
備註
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_GlobalResources 子目錄中的 .resx 檔和 .resource 檔 |
這些檔案會編譯成組件並放在 Bin 目錄中。主要輸出目錄底下不會建立 App_GlobalResources 子目錄，而且來源目錄中的 .resx 檔或 .resources 檔也不會複製到輸出目錄。
|
||
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_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