原生映像產生器 (Ngen.exe) 舊版語法

  • 發行項

這個主題中的資訊主要是為 .NET Framework 1.0 版和 1.1 版的使用者提供。 如需 2.0 版的語法，請參閱Ngen.exe (原生映像產生器)。

原生映像產生器會從 Managed 組件建立原生映像，並且將它安裝到本機電腦上的原生映像快取中。 原生映像快取是全域組件快取的保留區。 一旦您為組件建立原生映像，執行階段就會在每次執行組件時自動使用該原生映像。 您不需要執行任何其他程序讓執行階段使用原生映像。 在組件上執行 Ngen.exe 可以讓組件載入和在執行上更快速，因為它是從原生映像快取還原程式碼和資料結構，而不是以動態方式產生它們。

ngen [options] [assemblyName |assemblyPath ]

參數

引數

描述

assemblyName

要對它產生原生映像的組件名稱。 組件必須位於目前的目錄中。 您可以提供如 myAssembly 的部分指定組件名稱，或如 myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5 的完整指定組件名稱。 如果您要 Ngen.exe 尋找和使用某個組件的發行者原則檔，您就必須使用完整指定的組件名稱。

assemblyPath

要對它產生原生映像的組件明確路徑。 您可以指定組件的完整路徑 (例如 c:\applications\myApp\myApp.exe)、相對路徑 (例如.. applications\myApp\myApp.exe，或者像是 myApp.exe 的檔案名稱。

如果您指定如 myApp.exe 的檔案名稱，而不是完整或相對路徑，組件就必須位於目前的目錄。

若要允許 Ngen.exe 將組件識別為可執行檔並找到它的組態檔，您應該使用 assemblyPath 引數指定具有 .exe 副檔名的組件。

如果您在命令列指定一個以上的組件，其中只有一個組件可以是可執行檔。 這個工具會將可執行檔的繫結屬性 (應用程式基底及任何組態檔) 套用至您指定的其他組件。

選項

描述

/debug

產生要由偵錯工具在一般偵錯模式下使用的原生映像。

/debugopt

產生要由偵錯工具在 Common Language Runtime 的最佳化偵錯模式中使用的原生映像。 如需關於如何啟動這個模式的詳細資訊，請參閱偵錯工具的文件。

/delete [assemblyName | assemblyPath |

*]

刪除原生映像快取中由 assemblyName 或 assemblyPath 所指定的原生映像。 如果您指定 '*' 參數，工具就會刪除原生映像快取中的所有原生映像。 如果您沒有使用 /delete 選項指定參數，工具就會顯示錯誤訊息。

當您解除安裝某個 .NET Framework 版本時，解除安裝程序會使用 /delete 選項移除要解除安裝之 .NET Framework 版本的所有原生映像。 這包括安裝期間為 .NET Framework 組件所建立的原生映像，以及使用者為自訂組件所建立的任何原生映像。 如果您使用 /show 選項指定 /delete * 選項，工具就會顯示它所刪除的原生映像清單。

當多個 .NET Framework 版本同時安裝在相同電腦上時，若要刪除某個原生映像，您必須使用建立這個原生映像所使用的相同 Ngen.exe 版本。

注意事項注意事項
這個選項只會影響使用 Ngen.exe 產生的原生映像。它並不會影響實際的組件。

/help

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

/nologo

隱藏 Microsoft 程式啟始資訊顯示。

/prof

產生要由使用檢測之程式碼的分析工具 (Profiler) 使用的原生映像。 請參閱分析工具的文件，判斷您的分析工具是否需要檢測的程式碼。

/show

顯示原生映像快取中由 assemblyName 或 assemblyPath 所指定的現有檔案。 如果您沒有指定引數，這個工具會顯示原生映像快取的整個內容。 這個選項會顯示來源組件的組件定義資訊，和每一原生映像的任何特殊程式碼組態選項。

如果您使用 /delete * 選項指定這個映像，工具就會顯示它所刪除的原生映像清單。

/showversion

顯示 Ngen.exe 將用來為指定組件產生原生映像的執行階段版本。 當多個 .NET Framework 版本同時安裝在相同電腦上時，請使用這個選項決定工具要使用的版本。 如需執行多個執行階段版本的詳細資訊，請參閱並存執行。

注意事項注意事項
這個選項不會產生原生映像。

/silent

隱藏成功訊息的顯示。

/?

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

備註

Ngen.exe 不使用標準的組件探測規則尋找您在命令列上指定的組件。 Ngen.exe 只會在您指定之組件的目前目錄中尋找。 因此，若要允許 Ngen.exe 尋找您的組件，您應該將工作目錄設為包含您想為其建立原生映像之組件的目錄，或指定明確的組件路徑。

原生映像是含有已編譯且依處理器而異之機器碼 (Machine Code) 的檔案。 請注意，Ngen.exe 產生的原生映像無法跨應用程式定義域共用。 因此，您無法在需要跨應用程式定義域共用組件的應用程式案例中使用 Ngen.exe。

以 Ngen.exe 預先編譯組件可以加速應用程式的啟動時間，因為執行程式碼所需的大部分工作都已在事先完成了。 因此，在您確定 Just-In-Time (JIT) 編譯所使用之 CPU 行程會使效能變慢的地方，更適合對用戶端應用程式使用 Ngen.exe。

注意事項注意事項

若要執行 Ngen.exe，您必須具有系統管理員權限。

因為有許多因素會影響應用程式的啟動時間，您應該仔細判斷哪些應用程式會受益於 Ngen.exe 的使用。 請藉由執行候選組件的 JIT 編譯和先行編譯版本，在該組件的使用環境中進行實驗。 這樣可以讓您比較在不同編譯配置下執行之相同組件的啟動時間。

當您產生了組件的原生映像後，執行階段會在每次執行組件時自動嘗試找出並且使用這個原生映像。 例如，如果您是在偵錯或分析案例中執行組件，執行階段會去尋找以 /debug、/debugopt 或 /prof 選項產生的原生映像。 如果執行階段找不到符合的原生映像，就會還原成標準 JIT 編譯。

如果您在具有可偵錯程式碼屬性的組件上執行 Ngen.exe，那麼這個工具便會依據該屬性的旗標自動產生程式碼，就如同您已經指定了 /debug 或 /debugopt 選項一樣。

如果 Ngen.exe 在組件上碰到它無法產生機器碼的任何方法，它會將它們從原生映像排除。 當執行階段執行這些組件時，它將會對這些沒有包括在原生映像中的方法還原成 JIT 編譯。

當您使用 Ngen.exe 來建立組件的原生映像時，輸出會依您指定的命令列選項和電腦上的某些設定而有所不同。 這些設定包括下列：

  • .NET Framework 的版本。

  • CPU 類型。

  • 作業系統版本。

  • 組件的確切識別 (重新編譯會變更識別)。

  • 這個組件所參考之所有組件的確切識別 (重新編譯會變更識別)。

  • 安全性因素。

Ngen.exe 會在產生原生映像時記錄這項資訊。 當您執行組件時，執行階段會尋找由符合電腦目前執行環境之選項和設定所產生的原生映像。 如果找不到符合的原生映像，執行階段就會還原成組件的 JIT 編譯。 下列對電腦設定和環境的變更會使原生映像變成無效：

  • .NET Framework 的版本。

    如果您對 .NET Framework 套用更新，則以 Ngen.exe 手動建立的所有原生映像會變成無效。 這些組件仍會執行，但執行階段將不會載入組件的對應原生映像。 您必須為這些組件手動建立新的原生映像。

    .NET Framework 會自動為它所安裝的 .NET Framework 程式庫建立新的原生映像。

  • CPU 類型。

    如果您將電腦的處理器升級為新的處理器系列，所有儲存在原生映像快取的原生映像都會變成無效。

  • 作業系統版本。

    如果電腦上執行的作業系統版本變更，所有儲存在原生映像快取的原生映像都會變成無效。

  • 組件的確切識別。

    如果您重新編譯某個組件，這個組件對應的原生映像會變成無效。

  • 這個組件所參考之任一組件的確切識別。

    如果您重新編譯某個組件參考的任一組件，這個組件的對應原生映像就會變成無效。

  • 安全性因素。

    變更電腦安全性原則，以限制先前對組件允許的使用權限，會使該組件先前已編譯的原生映像變成無效。 尤其，撤銷下列其中一個使用權限會造成組件目前的原生映像變成無效：

    如果您將程式碼存取安全性關閉，而在某個組件上執行 Ngen.exe，則當程式碼存取安全性開啟時，它所產生的原生映像將變成無效。 請注意，程式碼存取安全性預設是開啟的。

    如需 Common Language Runtime 如何管理程式碼存取安全性以及如何利用使用權限的詳細資訊，請參閱程式碼存取安全性。

    注意事項注意事項

    在 1.0 版的 Common Language Runtime 中，並不會自動建立和刪除變成無效的原生映像。您必須使用 Ngen.exe 以手動方式建立和刪除所有原生映像。

如果您使用 Ngen.exe 在安裝期間產生某個應用程式的原生映像，您必須指定應用程式檔案名稱以及應用程式在進行編譯所參考之 .dll 檔案的完整指定組件名稱。 提供應用程式參考之 DLL 的完整指定組件名稱，可以讓 Ngen.exe 存取參考組件的發行者原則檔。 未來，如果 DLL 更新且發行者原則用來做為版本重新導向，則 Ngen.exe 就會套用這個發行者原則。

您可以在應用程式上執行 Ildasm.exe ，並檢視其組件資訊清單，取得所要使用的完整指定組件名稱。 資訊清單會顯示應用程式在進行編譯時所參考之 DLL 的組件名稱、版本、文化特性及公開金鑰語彙基元 (Token)。 例如，如果您想為使用 myLibrary.dll、1.0.0.0 版、culture=neutral 和 PublicKeyToken=0038abc9deabfle5 編譯、稱為 ClientApp.exe 的應用程式建立原生映像，請使用 ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5" 命令。

請注意，先前的範例不會對 myLibrary.dll 所參考的組件產生原生映像。 若要決定 myLibrary.dll 參考的完整指定組件名稱，請在 myLibrary.dll 上執行 Ildasm.exe。 例如，如果您在 myLibrary.dll 上執行 Ildasm.exe，並判斷它參考 myMath.dll 1.0.0.0 版，文化特性 = 中性，而且 PublicKeyToken = 0039def8abcbste7，請使用下列命令，為 ClientApp.exe 之組件參考的整個樹狀目錄產生原生映像。

ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7".

如需這個格式的詳細資訊，請參閱本主題稍後的＜範例＞章節。

應用程式的解除安裝程序應該使用 /delete[組建名稱|assemblyPath] 選項可移除在安裝應用程式時所建立的原生映像。 您必須使用 assemblyName 或 assemblyPath 參數，指定要刪除的特定原生映像。 指定 /delete * 會移除原生映像快取中的所有原生映像﹔指定 /delete 選項而沒有參數則會產生錯誤。

範例

下列命令會產生 ClientApp.exe 的原生映像，位置則在目前的目錄中。 如果應用程式有組態檔，Ngen.exe 就會使用它。 這個工具不會對 ClientApp.exe 所參考的任何 DLL 產生原生映像。

ngen ClientApp.exe

如果 ClientApp.exe 直接參考 myLibOne.dll 和 myLibTwo.dll 這兩個 DLL，您必須提供 Ngen.exe 這些 DLL 的完整指定組件名稱，以產生它們的原生映像。 請在 ClientApp.exe 上執行 Ildasm.exe，決定所參考之 DLL 的完整指定組件名稱。 為了這個範例的方便，myLibOne.dll 和 myLibTwo.dll 的完整指定組件名稱為 "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5" 和 "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"。 使用這項資訊，下列命令會產生 ClientApp.exe、myLibOne.dll 和 myLibTwo.dll 的原生映像。 如果 ClientApp.exe 有組態檔，Ngen.exe 就會使用該組態檔。 如果 myLibOne.dll 或 myLibTwo.dll 有發行者原則檔，Ngen.exe 就會使用該檔。

ngen ClientApp.exe "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

在先前的範例中，myLibOne.dll 和 myLibTwo.dll 這兩個 DLL 可能參考其他組件。 若要決定參考組件的完整指定組件名稱，請在 myLibOne.dll 和 myLibTwo.dll. 上執行 Ildasm.exe。為了這個範例的方便，假設 myLibOne.dll 不參考任何其他組件，而 myLibTwo.dll 參考 "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7"。 使用這項資訊，下列命令會對組件參考之應用程式的整個樹狀結構產生原生映像。

ngen ClientApp.exe "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7", "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

下列命令會對指定路徑的 myAssembly.exe 產生原生映像。

ngen c:\myfiles\myAssembly.exe

下列命令會對指定路徑的 myLibrary.dll, 產生原生映像。

ngen c:\myfiles\myLibrary.dll

Ngen.exe 會在原生映像快取中尋找，刪除以部分組件名稱指定的組件。 下列命令會刪除名稱為 myAssembly 的所有原生映像。

ngen /delete myAssembly

下列命令會刪除具有完整指定組件名稱的原生映像 myAssembly 。

ngen /delete "myAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

下列命令會顯示原生映像快取中的所有原生映像。

ngen /show

下列命令會顯示原生映像快取中名稱為 myAssembly 的所有原生映像。

ngen /show myAssembly

下列命令會顯示原生映像快取中名稱為 myAssembly 且版本為 1.0 的所有原生映像。

ngen /show "myAssembly, version=1.0.0.0"

請參閱

參考

Visual Studio 和 Windows SDK 命令提示字元

概念

Managed 執行程序

執行階段如何找出組件

其他資源

.NET Framework 工具