ネイティブ イメージ ジェネレータ (Ngen.exe) のレガシ構文
更新 : 2007 年 11 月
このトピックの情報は、.NET Framework Version 1.0 および 1.1 のユーザーに対して提供されています。バージョン 2.0 の構文については、「ネイティブ イメージ ジェネレータ (Ngen.exe)」を参照してください。
ネイティブ イメージ ジェネレータは、マネージ アセンブリからネイティブ イメージを作成し、そのイメージをローカル コンピュータ上のネイティブ イメージ キャッシュにインストールします。ネイティブ イメージ キャッシュはグローバル アセンブリ キャッシュの予約済み領域です。アセンブリのネイティブ イメージを作成すると、ランタイムはそのアセンブリを実行するたびに、自動的にこのネイティブ イメージを使用します。ランタイムがネイティブ イメージを使用するように追加手順を実行する必要はありません。アセンブリに対して 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 拡張子を持つアセンブリを指定する必要があります。 コマンド ラインで複数のアセンブリを指定する場合、実行可能ファイルとして指定できるアセンブリは 1 つだけです。このツールは、実行可能ファイルのバインディング プロパティ (アプリケーション ベースおよびすべての構成ファイル) を指定された他のアセンブリに適用します。 |
オプション |
説明 |
|---|---|
/debug |
デバッガが通常のデバッグ モードで使用するネイティブ イメージを生成します。 |
/debugopt |
デバッガが共通言語ランタイムの最適化デバッグ モードで使用するネイティブ イメージを生成します。このモードをアクティブにする方法の詳細については、使用するデバッガのドキュメントを参照してください。 |
/delete [assemblyName | assemblyPath | *] |
ネイティブ イメージ キャッシュから、指定した assemblyName または assemblyPath のネイティブ イメージを削除します。"*" パラメータを指定した場合は、ネイティブ イメージ キャッシュ内のすべてのネイティブ イメージが削除されます。/delete オプションでパラメータを指定しない場合は、エラー メッセージが表示されます。 あるバージョンの .NET Framework をアンインストールする場合、アンインストール プロセスは /delete オプションを使用して、アンインストールする .NET Framework Version に対するすべてのネイティブ イメージを削除します。これには、インストール時に .NET Framework アセンブリ用に作成されたネイティブ イメージと、ユーザーがカスタム アセンブリ用に作成したネイティブ イメージが含まれます。/delete * オプションを /show オプションと共に指定すると、ツールは削除するネイティブ イメージの一覧を表示します。 .NET Framework の複数のバージョンが同時に同じコンピュータにインストールされている場合、ネイティブ イメージを削除するには、そのネイティブ イメージを作成するのに使用したのと同じバージョンの Ngen.exe を使用する必要があります。 .gif "メモ") メモ :
このオプションは、Ngen.exe を使用して生成したネイティブ イメージにだけ影響します。実際のアセンブリには影響しません。
|
/help |
このツールのコマンド構文とオプションを表示します。 |
/nologo |
Microsoft 著作権情報を表示しません。 |
/prof |
実装されたコードを使用するプロファイラが使うネイティブ イメージを生成します。使用するプロファイラに実装されるコードが必要かどうかについては、プロファイラのドキュメントを参照してください。 |
/show |
ネイティブ イメージ キャッシュ内の、指定した assemblyName または assemblyPath の既存のファイルを表示します。引数を指定しない場合は、ネイティブ イメージ キャッシュの内容がすべて表示されます。このオプションでは、各ネイティブ イメージのソース アセンブリのアセンブリ定義情報およびすべての特殊コード構成オプションが表示されます。 このオプションを /delete * オプションと共に指定すると、ツールは削除するネイティブ イメージの一覧を表示します。 |
/showversion |
指定したアセンブリのネイティブ イメージの生成に Ngen.exe が使用するランタイムのバージョンを表示します。.NET Framework の複数のバージョンが同時に同じコンピュータにインストールされている場合は、このオプションを使用して、ツールが使用するバージョンを決定します。ランタイムの複数バージョンの同時実行については、「side-by-side 実行」を参照してください。 メモ :
このオプションはネイティブ イメージを生成しません。
|
/silent |
成功メッセージを表示しません。 |
/? |
このツールのコマンド構文とオプションを表示します。 |
解説
Ngen.exe は、コマンド ラインで指定したアセンブリの検索に標準アセンブリ プローブ規則を使用しません。Ngen.exe は、指定したアセンブリを現在のディレクトリでだけ検索します。そのため、Ngen.exe がアセンブリを検索できるようにするには、作業ディレクトリを、ネイティブ イメージを作成するアセンブリが含まれているディレクトリに設定するか、アセンブリへの正確なパスを指定する必要があります。
ネイティブ イメージは、コンパイルされたプロセッサ固有のマシン語コードを格納するファイルです。Ngen.exe が生成するネイティブ イメージは、アプリケーション ドメイン間では共有できません。したがって、アプリケーション ドメイン間でアセンブリを共有する必要のあるアプリケーション シナリオでは Ngen.exe を使用できません。
Ngen.exe を使用してアセンブリをプリコンパイルすると、コードの実行に必要な作業の多くを事前に処理できるため、アプリケーションの起動時間を短縮できます。したがって、JIT コンパイルで多くの CPU サイクルが消費されるためにパフォーマンスが低下していると判断した場合に、クライアント側のアプリケーションで Ngen.exe を使用するとより効果的です。
| メモ : |
|---|
Ngen.exe を実行するには、管理者特権が必要です。 |
アプリケーションの起動時間には多くの要因が影響を及ぼすため、Ngen.exe を使用することでパフォーマンスが向上するアプリケーションはどれかを注意深く検討する必要があります。検討対象のアセンブリの JIT コンパイル バージョンとプリコンパイル バージョンの両方を、そのアセンブリが実行される環境で実行して実験します。この方法で、同じアセンブリを異なるコンパイル方法で実行した場合の起動時間を比較できます。
アセンブリのネイティブ イメージが生成された後でそのアセンブリを実行する場合、ランタイムは、常にこのネイティブ イメージを自動的に検索して使用しようとします。たとえば、デバッグまたはプロファイルの目的でアセンブリを実行する場合、ランタイムは、/debug、/debugopt、または /prof の各オプションを指定して生成されたネイティブ イメージを検索します。一致するネイティブ イメージが見つからない場合、ランタイムは標準の JIT コンパイルに戻ります。
デバッグ可能なコード属性を持つアセンブリに対して Ngen.exe を実行する場合は、属性のフラグに応じて、/debug オプションまたは /debugopt オプションを指定した場合と同様に自動的にコードが生成されます。
生成できないメソッドがアセンブリ内にある場合、Ngen.exe が生成するネイティブ イメージにそのメソッドは含まれません。ランタイムは、このアセンブリの実行中に JIT コンパイルに戻し、ネイティブ イメージから除外されたこれらのメソッドを処理します。
Ngen.exe を使用してアセンブリのネイティブ イメージを作成する場合、出力は指定したコマンド ライン オプションおよび使用するコンピュータ上の設定に依存します。影響のある設定は次のとおりです。
.NET Framework Version。
CPU の種類。
オペレーティング システムのバージョン。
アセンブリの正確な ID (ID は再コンパイル時に変更されます)。
アセンブリが参照するすべてのアセンブリの正確な ID (ID は再コンパイル時に変更されます)。
セキュリティ関連の要因。
Ngen.exe は、ネイティブ イメージを生成するときに上記の情報を記録します。アセンブリが実行されると、ランタイムは、コンピュータの現在の環境と一致するオプションおよび設定を指定して生成されたネイティブ イメージを検索します。一致するネイティブ イメージが見つからない場合、ランタイムはアセンブリを JIT コンパイルに戻します。コンピュータの設定および環境が次のように変更されると、ネイティブ イメージは無効になります。
.NET Framework Version。
更新を .NET Framework に適用すると、Ngen.exe を使用して手動で作成したすべてのネイティブ イメージは、無効になります。それでもこれらのアセンブリは動作しますが、アセンブリの対応するネイティブ イメージを読み込みません。これらのアセンブリの新しいネイティブ イメージを手動で作成する必要があります。
.NET Framework は、インストールする .NET Framework ライブラリの新しいネイティブ イメージを自動的に作成します。
CPU の種類。
コンピュータのプロセッサを新しいプロセッサ ファミリにアップグレードすると、ネイティブ イメージ キャッシュに格納されたすべてのネイティブ イメージは無効になります。
オペレーティング システムのバージョン。
コンピュータで稼動しているオペレーティング システムのバージョンが変更されると、ネイティブ イメージ キャッシュに格納されたすべてのネイティブ イメージは無効になります。
アセンブリの正確な ID。
アセンブリを再コンパイルすると、アセンブリの対応するネイティブ イメージは無効になります。
アセンブリが参照するすべてのアセンブリの正確な ID。
アセンブリが参照する任意のアセンブリを再コンパイルすると、アセンブリの対応するネイティブ イメージは無効になります。
セキュリティ関連の要因。
アセンブリに事前に与えられていたアクセス許可を制限するマシン セキュリティ ポリシーを変更すると、そのアセンブリのコンパイル済みのネイティブ イメージが無効になることがあります。特に、次のアクセス許可を取り消すと、アセンブリの現在のネイティブ イメージは無効になります。
アセンブリの派生元のクラスで要求された宣言継承アクセス許可。
アセンブリが呼び出すメソッドで要求された宣言リンク時アクセス許可。
SkipVerification アクセス許可 (アセンブリに検査できないメソッドが含まれている場合)。このアクセス許可の詳細については、「SecurityPermissionAttribute.SkipVerification プロパティ」を参照してください。
UnmanagedCode アクセス許可 (アセンブリが PInvoke 呼び出しを行う場合)。このアクセス許可の詳細については、「SecurityPermissionAttribute.UnmanagedCode プロパティ」を参照してください。
コード アクセス セキュリティがオフになっているアセンブリに対して Ngen.exe を実行した場合、コード アクセス セキュリティをオンにすると、生成されるネイティブ イメージは無効になります。既定では、コード アクセス セキュリティはオンです。
共通言語ランタイムがコード アクセス セキュリティを管理する方法とアクセス許可を使用する方法の詳細については、「コード アクセス セキュリティ」を参照してください。
メモ :共通言語ランタイムのバージョン 1.0 では、無効になったネイティブ イメージを自動的に作成または削除できません。Ngen.exe を使用して、すべてのネイティブ イメージを手動で作成および削除する必要があります。
Ngen.exe を使用して、インストール時にアプリケーションのネイティブ イメージを生成する場合は、アプリケーション ファイル名と、コンパイル時にアプリケーションが参照した .dll ファイルの完全に指定したアセンブリ名を指定する必要があります。アプリケーションが参照する DLL の完全に指定したアセンブリ名を使用することにより、Ngen.exe は、参照先アセンブリの発行者ポリシー ファイルにアクセスできます。将来、DLL が更新され、発行者ポリシーがバージョンのリダイレクトに使用される場合、Ngen.exe は発行者ポリシーを適用します。
アプリケーションに対して Ildasm.exe を実行し、アセンブリ マニフェストを表示することによって、完全に指定したアセンブリ名を取得できます。マニフェストには、コンパイル時にアプリケーションが参照した DLL のアセンブリ名、バージョン、カルチャ、および公開キー トークンが表示されます。たとえば、myLibrary.dll、version 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、version 1.0.0.0、culture=neutral、および 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 [assemblyName | assemblyPath] オプションを使用して、アプリケーションのインストール時に作成されたネイティブ イメージを削除する必要があります。assemblyName パラメータまたは assemblyPath パラメータを使用して、削除するネイティブ イメージを指定する必要があります。/delete * を指定すると、ネイティブ イメージ キャッシュ内のすべてのネイティブ イメージが削除されます。パラメータを付けずに /delete オプションを指定すると、エラーが発生します。
例
現在のディレクトリにある ClientApp.exe のネイティブ イメージを生成するコマンドを次に示します。アプリケーションの構成ファイルが存在する場合、Ngen.exe はその構成ファイルを使用します。ClientApp.exe が参照する DLL のネイティブ イメージは生成されません。
ngen ClientApp.exe
ClientApp.exe が 2 つの DLL、myLibOne.dll および myLibTwo.dll を直接参照している場合は、これらの DLL に対する完全に指定したアセンブリ名を Ngen.exe に入力して、これらのネイティブ イメージを生成する必要があります。参照された DLL の完全に指定したアセンブリ名を判定するには、ClientApp.exe に対して Ildasm.exe を実行します。この例の場合、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"
前の例で、DLL の myLibOne.dll および myLibTwo.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"