Ngen.exe (Native Image Generator)

Artikel
04/08/2023

Native Image Generator (Ngen.exe) adalah alat yang meningkatkan performa aplikasi terkelola. Ngen.exe membuat gambar asli, yang merupakan file yang berisi kode mesin khusus prosesor yang dikompilasi, dan memasangnya ke dalam cache gambar asli di komputer lokal. Runtime dapat menggunakan gambar asli dari cache, bukan menggunakan kompiler just-in-time (JIT) untuk mengompilasi perakitan asli.

Catatan

Ngen.exe mengkompilasi gambar asli untuk rakitan yang menargetkan .NET Framework saja. Generator gambar asli yang setara untuk .NET Core adalah CrossGen.

Perubahan pada Ngen.exe di .NET Framework 4:

Ngen.exe sekarang mengompilasi assembly dengan kepercayaan penuh, dan kebijakan keamanan akses kode (CAS) tidak lagi dievaluasi.
Gambar asli yang dihasilkan dengan Ngen.exe tidak dapat lagi dimuat ke dalam aplikasi yang berjalan dalam kepercayaan parsial.

Perubahan pada Ngen.exe di .NET Framework versi 2.0:

Memasang assembly juga memasang dependensinya, menyederhanakan sintaks Ngen.exe.
Gambar asli sekarang dapat dibagikan di seluruh domain aplikasi.
Tindakan baru, update, membuat ulang gambar yang telah tidak valid.
Tindakan dapat ditangguhkan untuk eksekusi oleh layanan yang menggunakan waktu menganggur pada komputer untuk menghasilkan dan memasang gambar.
Beberapa penyebab pembatalan citra telah dihilangkan.

Di Windows 8, lihat Tugas Gambar Asli.

Untuk informasi tambahan tentang menggunakan Ngen.exe dan layanan gambar asli, lihat Native Image Service.

Catatan

Ngen.exe sintaks untuk sintaksis Waris .NET Framework an versi 1.0 dan 1.1 dapat ditemukan di Native Image Generator (Ngen.exe).

Alat ini otomatis terpasang dengan Visual Studio. Untuk menjalankan alat, gunakan Prompt Perintah Pengembang Visual Studio atau PowerShell Pengembang Visual Studio.

Pada perintah, masukkan berikut ini:

Sintaks

ngen action [options]

ngen /? | /help

Tindakan

Tabel berikut menunjukkan metode action. Untuk deskripsi bagian individual dari , actionlihat tabel Argumen, Tingkat Prioritas, Skenario, dan Konfigurasi . Tabel Opsi menjelaskan options dan bantuan beralih.

Tindakan	Deskripsi
`install`[`assemblyNameassemblyPath` \| ] [`scenarios`] [`config`] [`/queue:`{\|`1`\|`23`}]]	Hasilkan gambar asli untuk assembly dan dependensinya dan pasang gambar di cache gambar asli. Jika `/queue` ditentukan, tindakan diantrekan untuk layanan gambar asli. Prioritas default 3. Lihat tabel Tingkat Prioritas.
`uninstall` [`assemblyName` \| `assemblyPath`] [`scenarios`] [`config`]	Hapus gambar asli assembly dan dependensinya dari cache gambar asli. Untuk menghapus pemasangan satu gambar dan dependensinya, gunakan argumen baris perintah yang sama yang digunakan untuk memasang gambar. Catatan: Dimulai dengan .NET Framework 4, tindakan `uninstall` * tidak lagi didukung.
`update` [`/queue`]	Perbarui gambar asli yang menjadi tidak valid. Jika `/queue` ditentukan, pembaruan diantrekan untuk layanan gambar asli. Pembaruan selalu dijadwalkan pada prioritas 3, sehingga dijalankan saat komputer diam.
`display` [`assemblyName` \| `assemblyPath`]	Tampilkan status gambar asli untuk assembly dan dependensinya. Jika tidak ada argumen yang disediakan, semua yang ada di cache gambar asli ditampilkan.
`executeQueuedItems` [`1\|2\|3`] -atau- `eqi` [1\|2\|3]	Jalankan pekerjaan kompilasi yang diantrekan. Jika prioritas ditentukan, pekerjaan kompilasi dengan prioritas yang lebih besar atau sama akan dijalankan. Jika tidak ada prioritas yang ditentukan, semua pekerjaan kompilasi yang diantrekan akan dijalankan.
`queue`{`pause` \| \| `continuestatus`}	Jeda layanan gambar asli, izinkan layanan yang dijeda untuk melanjutkan, atau mengkueri status layanan.

Argumen

Argumen	Deskripsi
`assemblyName`	Nama tampilan lengkap assembly. Contohnya,`"myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"`. Catatan: Anda dapat memberikan nama assembly parsial, seperti `myAssembly`, untuk `display` tindakan dan `uninstall` . Hanya satu assembly yang dapat ditentukan per baris perintah Ngen.exe.
`assemblyPath`	Jalur eksplisit assembly. Anda dapat menentukan jalur lengkap atau relatif. Jika Anda menentukan nama file tanpa jalur, assembly harus terletak di direktori saat ini. Hanya satu assembly yang dapat ditentukan per baris perintah Ngen.exe.

Tingkat Prioritas

Prioritas	Deskripsi
`1`	Gambar asli dihasilkan dan segera dipasang, tanpa menunggu waktu menganggur.
`2`	Gambar asli dihasilkan dan dipasang tanpa menunggu waktu diam, tetapi setelah semua tindakan prioritas 1 (dan dependensinya) telah selesai.
`3`	Gambar asli dipasang saat layanan gambar asli mendeteksi bahwa komputer menganggur. Lihat Native Image Service.

Skenario

Skenario	Deskripsi
`/Debug`	Hasilkan gambar asli yang dapat digunakan di bawah debugger.
`/Profile`	Hasilkan gambar asli yang dapat digunakan di bawah debugger.
`/NoDependencies`	Hasilkan jumlah minimum gambar asli yang diperlukan oleh opsi skenario yang ditentukan.

Konfigurasi

Konfigurasi Deskripsi

/ExeConfig: exePath Gunakan konfigurasi assembly yang dapat dieksekusi yang ditentukan.

Ngen.exe perlu membuat keputusan yang sama dengan loader saat mengikat dependensi. Saat komponen bersama dimuat pada durasi, menggunakan Load metode , file konfigurasi aplikasi menentukan dependensi yang dimuat untuk komponen bersama — misalnya, versi dependensi yang dimuat. Sakelar /ExeConfig memberikan panduan Ngen.exe tentang dependensi mana yang akan dimuat pada durasi.

/AppBase: directoryPath Saat menemukan dependensi, gunakan direktori yang ditentukan sebagai basis aplikasi.

Konfigurasi	Deskripsi
`/ExeConfig:` `exePath`	Gunakan konfigurasi assembly yang dapat dieksekusi yang ditentukan. Ngen.exe perlu membuat keputusan yang sama dengan loader saat mengikat dependensi. Saat komponen bersama dimuat pada durasi, menggunakan Load metode , file konfigurasi aplikasi menentukan dependensi yang dimuat untuk komponen bersama — misalnya, versi dependensi yang dimuat. Sakelar `/ExeConfig` memberikan panduan Ngen.exe tentang dependensi mana yang akan dimuat pada durasi.
`/AppBase:` `directoryPath`	Saat menemukan dependensi, gunakan direktori yang ditentukan sebagai basis aplikasi.

Opsi

Opsi	Deskripsi
`/nologo`	Menekan tampilan spanduk startup Microsoft.
`/silent`	Menekan tampilan pesan sukses.
`/verbose`	Tampilkan informasi terperinci untuk penelusuran kesalahan.
`/help`, `/?`	Tampilkan sintaks perintah dan opsi untuk rilis saat ini.

Keterangan

Untuk menjalankan Ngen.exe, Anda harus memiliki hak administratif.

Perhatian

Jangan jalankan Ngen.exe pada assembly yang tidak sepenuhnya dipercaya. Mulai dengan .NET Framework 4, Ngen.exe sekarang mengompilasi assembly dengan kepercayaan penuh, dan kebijakan keamanan akses kode (CAS) tidak lagi dievaluasi.

Mulai dengan .NET Framework 4, gambar asli yang dihasilkan dengan Ngen.exe tidak dapat lagi dimuat ke dalam aplikasi yang berjalan dalam kepercayaan parsial. Sebaliknya, pengompilasi just-in-time (JIT) dipanggil.

Ngen.exe menghasilkan gambar asli untuk assembly yang ditentukan oleh assemblyname argumen untuk install tindakan dan semua dependensinya. Dependensi ditentukan dari referensi dalam manifes assembly. Satu-satunya skenario di mana Anda perlu memasang dependensi secara terpisah adalah saat aplikasi memuatnya menggunakan pantulan, misalnya dengan memanggil metode Assembly.Load.

Penting

Jangan gunakan Assembly.LoadFrom metode dengan gambar asli. Gambar yang dimuat dengan metode ini tidak dapat digunakan oleh assembly lain dalam konteks eksekusi.

Ngen.exe mempertahankan hitungan pada dependensi. Misalnya, misalkan MyAssembly.exe dan YourAssembly.exe keduanya dipasang dalam cache gambar asli, dan keduanya memiliki referensi ke OurDependency.dll. Jika MyAssembly.exe dihapus pemasangannya, OurDependency.dll tidak dihapus pemasangannya. Ini hanya dihapus saat YourAssembly.exe juga dihapus pemasangannya.

Jika Anda membuat gambar asli untuk assembly di cache assembly global, tentukan nama tampilannya. Lihat Assembly.FullName.

Gambar asli yang Ngen.exe hasilkan dapat dibagikan di seluruh domain aplikasi. Ini berarti Anda dapat menggunakan Ngen.exe dalam skenario aplikasi yang mengharuskan assembly dibagikan di seluruh domain aplikasi. Untuk menentukan netralitas domain:

Terapkan atribut ke LoaderOptimizationAttribute aplikasi Anda.
Atur AppDomainSetup.LoaderOptimization properti saat Anda membuat informasi penyiapan untuk domain aplikasi baru.

Selalu gunakan kode netral domain saat memuat assembly yang sama ke beberapa domain aplikasi. Jika gambar asli dimuat ke dalam domain aplikasi yang tidak dibagikan setelah dimuat ke domain bersama, gambar tersebut tidak dapat digunakan.

Catatan

Kode netral domain tidak dapat dibongkar, dan performa mungkin sedikit lebih lambat, terutama saat mengakses anggota statis.

Di bagian Keterangan ini:

Menghasilkan gambar untuk skenario yang berbeda
Menentukan kapan menggunakan gambar asli
Pentingnya alamat dasar assembly
Pengikatan keras
- Menentukan petunjuk pengikatan untuk dependensi
- Menentukan petunjuk pengikatan untuk dependensi
Pemrosesan yang ditangguhkan
Gambar asli dan kompilasi JIT
- Gambar tidak valid
Pemecahan Masalah

Menghasilkan gambar untuk skenario yang berbeda

Setelah Anda membuat gambar asli untuk assembly, runtime secara otomatis mencoba menemukan dan menggunakan gambar asli ini setiap kali menjalankan assembly. Beberapa gambar dapat dihasilkan, bergantung pada skenario penggunaan.

Misalnya, jika Anda menjalankan assembly dalam skenario penelusuran kesalahan atau pembuatan profil, runtime mencari gambar asli yang dihasilkan dengan /Debug opsi atau /Profile. Jika tidak dapat menemukan gambar asli yang cocok, runtime kembali ke kompilasi JIT standar. Satu-satunya cara untuk men-debug gambar asli adalah dengan membuat gambar asli dengan opsi /Debug.

Tindakan ini uninstall juga mengenali skenario, sehingga Anda dapat menghapus pemasangan semua skenario atau hanya skenario yang dipilih.

Menentukan kapan menggunakan gambar asli

Gambar asli dapat memberikan peningkatan performa di dua area: peningkatan penggunaan memori dan pengurangan waktu mulai.

Catatan

Performa gambar asli bergantung pada sejumlah faktor yang menyulitkan analisis, seperti pola kode dan akses data, berapa banyak panggilan yang dilakukan di seluruh batas modul, dan berapa banyak dependensi yang telah dimuat oleh aplikasi lain. Satu-satunya cara untuk menentukan apakah gambar asli menguntungkan aplikasi Anda adalah dengan pengukuran performa yang cermat dalam skenario penyebaran utama Anda.

Peningkatan penggunaan memori

Gambar asli dapat secara signifikan meningkatkan penggunaan memori saat kode dibagikan di antara proses. Gambar asli Windows file PE, sehingga satu salinan file .dll dapat dibagikan oleh beberapa proses; sebaliknya, kode asli yang dihasilkan oleh pengompilasi JIT disimpan dalam memori privat dan tidak dapat dibagikan.

Aplikasi yang dijalankan di bawah layanan terminal juga dapat memperoleh manfaat dari halaman kode bersama.

Selain itu, tidak memuat pengompilasi JIT menghemat jumlah memori tetap untuk setiap instans aplikasi.

Pengaktifan aplikasi yang lebih cepat

Assembly yang telah dikompilasi sebelumnya dengan Ngen.exe dapat meningkatkan waktu mulai untuk beberapa aplikasi. Secara umum, keuntungan dapat dilakukan saat aplikasi berbagi assembly komponen karena setelah aplikasi pertama dimulai, komponen bersama sudah dimuat untuk aplikasi berikutnya. Startup dingin, di mana semua assembly dalam aplikasi harus dimuat dari hard disk, tidak mendapat manfaat sebanyak dari gambar asli karena waktu akses hard disk mendominasi.

Pengikatan keras dapat memengaruhi waktu startup, karena semua gambar yang terikat keras ke assembly aplikasi utama harus dimuat pada saat yang sama.

Catatan

Sebelum .NET Framework 3.5 Paket Layanan 1, Anda harus menempatkan komponen bersama bernama kuat di cache assembly global, karena loader melakukan validasi tambahan pada assembly bernama kuat yang tidak berada di cache assembly global, secara efektif menghilangkan peningkatan dalam waktu startup yang diperoleh dengan menggunakan gambar asli. Pengoptimalan yang diperkenalkan dalam .NET Framework 3.5 SP1 menghapus validasi tambahan.

Ringkasan pertimbangan penggunaan

Pertimbangan umum dan pertimbangan aplikasi berikut dapat membantu Anda dalam memutuskan apakah akan melakukan upaya mengevaluasi gambar asli untuk aplikasi Anda:

Gambar asli dimuat lebih cepat daripada CIL karena menghilangkan kebutuhan akan banyak aktivitas startup, seperti kompilasi JIT dan verifikasi keamanan jenis.
Gambar asli memerlukan set kerja awal yang lebih kecil karena tidak perlu pengompilasi JIT.
Gambar asli memungkinkan berbagi kode antar-proses.
Gambar asli membutuhkan lebih banyak ruang hard disk daripada rakitan CIL dan mungkin memerlukan waktu yang cukup lama untuk dihasilkan.
Gambar asli harus dipertahankan.
- Gambar perlu diregenerasi saat assembly asli atau salah satu dependensinya dilayankan.
- Satu assembly mungkin memerlukan beberapa gambar asli untuk digunakan dalam aplikasi yang berbeda atau skenario yang berbeda. Misalnya, informasi konfigurasi dalam dua aplikasi dapat menghasilkan keputusan pengikatan yang berbeda untuk assembly dependen yang sama.
- Gambar asli harus dihasilkan oleh administrator; yaitu, dari akun Windows di grup Administrator.

Selain pertimbangan umum ini, sifat aplikasi Anda harus dipertimbangkan saat menentukan apakah gambar asli mungkin memberikan manfaat performa:

Jika aplikasi Anda berjalan di lingkungan yang menggunakan banyak komponen bersama, gambar asli memungkinkan komponen dibagikan oleh beberapa proses.
Jika aplikasi Anda menggunakan beberapa domain aplikasi, gambar asli memungkinkan halaman kode dibagikan di seluruh domain.

Catatan

Dalam .NET Framework versi 1.0 dan 1.1, gambar asli tidak dapat dibagikan di seluruh domain aplikasi. Ini tidak terjadi dalam versi 2.0 atau yang lebih baru.
Jika aplikasi Anda akan dijalankan di bawah Server Terminal, gambar asli memungkinkan berbagi halaman kode.
Aplikasi besar umumnya mendapat manfaat dari kompilasi hingga gambar asli. Aplikasi kecil umumnya tidak menguntungkan.
Untuk aplikasi jangka panjang, kompilasi JIT run-time berkinerja sedikit lebih baik daripada gambar asli. (Pengikatan keras dapat mengurangi perbedaan performa ini ke tingkat tertentu.)

Pentingnya alamat dasar assembly

Karena gambar asli Windows file PE, gambar tersebut tunduk pada masalah rebasing yang sama dengan file lain yang dapat dieksekusi. Biaya performa relokasi bahkan lebih jelas jika pengikatan keras digunakan.

Untuk mengatur alamat dasar untuk gambar asli, gunakan opsi pengompilasi yang sesuai untuk mengatur alamat dasar untuk assembly. Ngen.exe menggunakan alamat dasar ini untuk gambar asli.

Catatan

Gambar asli lebih besar dari assembly terkelola tempat mereka dibuat. Alamat dasar harus dihitung untuk memungkinkan ukuran yang lebih besar ini.

Anda dapat menggunakan alat seperti dumpbin.exe untuk melihat alamat dasar pilihan gambar asli.

Pengikatan keras

Pengikatan keras meningkatkan throughput dan mengurangi ukuran set kerja untuk gambar asli. Kerugian dari pengikatan keras adalah bahwa semua gambar yang terikat keras ke assembly harus dimuat saat assembly dimuat. Ini dapat secara signifikan meningkatkan waktu startup untuk aplikasi besar.

Pengikatan keras sesuai untuk dependensi yang dimuat dalam semua skenario kritis performa aplikasi Anda. Seperti halnya aspek penggunaan gambar asli, pengukuran performa yang cermat adalah satu-satunya cara untuk menentukan apakah pengikatan keras meningkatkan performa aplikasi Anda.

Atribut DependencyAttribute dan DefaultDependencyAttribute memungkinkan Anda untuk memberikan petunjuk pengikatan keras ke Ngen.exe.

Catatan

Atribut ini adalah petunjuk untuk Ngen.exe, bukan perintah. Menggunakannya tidak menjamin pengikatan keras. Arti atribut ini dapat berubah dalam rilis mendatang.

Menentukan petunjuk pengikatan untuk dependensi

Terapkan ke DependencyAttribute assembly untuk menunjukkan kemungkinan dependensi tertentu akan dimuat. LoadHint.Always menunjukkan bahwa pengikatan keras sesuai, Default menunjukkan bahwa default untuk dependensi harus digunakan, dan Sometimes menunjukkan bahwa pengikatan keras tidak sesuai.

Kode berikut menunjukkan atribut untuk assembly yang memiliki dua dependensi. Dependensi pertama (Assembly1) adalah kandidat yang sesuai untuk pengikatan keras, dan yang kedua (Assembly2) tidak.

Imports System.Runtime.CompilerServices
<Assembly:DependencyAttribute("Assembly1", LoadHint.Always)>
<Assembly:DependencyAttribute("Assembly2", LoadHint.Sometimes)>

using System.Runtime.CompilerServices;
[assembly:DependencyAttribute("Assembly1", LoadHint.Always)]
[assembly:DependencyAttribute("Assembly2", LoadHint.Sometimes)]

using namespace System::Runtime::CompilerServices;
[assembly:DependencyAttribute("Assembly1", LoadHint.Always)];
[assembly:DependencyAttribute("Assembly2", LoadHint.Sometimes)];

Nama assembly tidak menyertakan ekstensi nama file. Nama tampilan dapat digunakan.

Menentukan petunjuk pengikatan default untuk assembly

Petunjuk pengikatan default hanya diperlukan untuk assembly yang akan segera digunakan dan sering oleh aplikasi apa pun yang memiliki dependensi pada mereka. Terapkan DefaultDependencyAttribute dengan LoadHint.Always ke assembly tersebut untuk menentukan bahwa pengikatan keras harus digunakan.

Catatan

Tidak ada alasan untuk diterapkan DefaultDependencyAttribute ke assembly .dll yang tidak termasuk dalam kategori ini, karena menerapkan atribut dengan nilai apa pun selain memiliki efek yang sama dengan LoadHint.Always tidak menerapkan atribut sama sekali.

Microsoft menggunakan DefaultDependencyAttribute untuk menentukan bahwa pengikatan keras adalah default untuk sejumlah kecil assembly dalam .NET Framework, seperti mscorlib.dll.

Pemrosesan yang ditangguhkan

Pembuatan gambar asli untuk aplikasi yang sangat besar dapat memakan waktu yang cukup lama. Demikian pula, perubahan pada komponen bersama atau perubahan pada pengaturan komputer mungkin memerlukan banyak gambar asli untuk diperbarui. Tindakan install dan update memiliki /queue opsi yang mengantrekan operasi untuk eksekusi yang ditangguhkan oleh layanan gambar asli. Selain itu, Ngen.exe memiliki queue tindakan dan executeQueuedItems yang memberikan beberapa kontrol atas layanan. Untuk informasi selengkapnya, lihat Native Image Service.

Gambar asli dan kompilasi JIT

Jika Ngen.exe menemukan metode apa pun dalam assembly yang tidak dapat dihasilkan, metode tersebut akan mengecualikannya dari gambar asli. Saat runtime menjalankan assembly ini, runtime kembali ke kompilasi JIT untuk metode yang tidak disertakan dalam gambar asli.

Selain itu, gambar asli tidak digunakan jika assembly telah ditingkatkan, atau jika gambar telah dibatalkan karena alasan apa pun.

Gambar tidak valid

Saat Anda menggunakan Ngen.exe untuk membuat gambar asli assembly, output bergantung pada opsi baris perintah yang Anda tentukan dan pengaturan tertentu di komputer Anda. Pengaturan ini mencakup hal-hal berikut:

Versi .NET Framework.
Identitas yang tepat dari assembly (identitas perubahan kompilasi ulang).
Identitas yang tepat dari semua assembly yang direferensikan assembly (kompilasi ulang mengubah identitas).
Faktor keamanan.

Ngen.exe merekam informasi ini saat menghasilkan gambar asli. Saat Anda menjalankan assembly, runtime mencari gambar asli yang dihasilkan dengan opsi dan pengaturan yang cocok dengan lingkungan komputer saat ini. Runtime kembali ke kompilasi JIT dari assembly jika tidak dapat menemukan gambar asli yang cocok. Perubahan berikut pada pengaturan dan lingkungan komputer menyebabkan gambar asli menjadi tidak valid:

Versi .NET Framework.

Jika Anda menerapkan pembaruan ke .NET Framework, semua gambar asli yang telah Anda buat menggunakan Ngen.exe menjadi tidak valid. Untuk alasan ini, semua pembaruan .NET Framework menjalankan Ngen Update perintah, untuk memastikan bahwa semua gambar asli diregenerasi. .NET Framework secara otomatis membuat gambar asli baru untuk pustaka .NET Framework yang dipasangnya.
Identitas yang tepat dari assembly.

Jika Anda mengompilasi ulang assembly, gambar asli assembly yang sesuai menjadi tidak valid.
Identitas yang tepat dari setiap assembly referensi assembly.

Jika Anda memperbarui assembly terkelola, semua gambar asli yang secara langsung atau tidak langsung bergantung pada assembly tersebut menjadi tidak valid dan perlu diregenerasi. Ini termasuk referensi biasa dan dependensi yang terikat secara permanen. Setiap kali pembaruan perangkat lunak diterapkan, program pengpasangan harus menjalankan Ngen Update perintah untuk memastikan bahwa semua gambar asli dependen diregenerasi.
Faktor keamanan.

Mengubah kebijakan keamanan mesin untuk membatasi izin yang sebelumnya diberikan ke assembly dapat menyebabkan gambar asli yang dikompilasi sebelumnya agar assembly tersebut menjadi tidak valid.

Untuk informasi terperinci tentang bagaimana runtime bahasa umum mengelola keamanan akses kode dan cara menggunakan izin, lihat Keamanan Akses Kode.

Pemecahan Masalah

Topik pemecahan masalah berikut memungkinkan Anda untuk melihat gambar asli mana yang digunakan dan yang tidak dapat digunakan oleh aplikasi Anda, untuk menentukan kapan kompilator JIT mulai mengompilasi metode, dan menunjukkan cara menolak kompilasi gambar asli dari metode yang ditentukan.

Penampil Log Pengikatan Assembly

Untuk mengonfirmasi bahwa gambar asli sedang digunakan oleh aplikasi Anda, Anda dapat menggunakan Fuslogvw.exe (Penampil Log Pengikatan Assembly). Pilih Gambar Asli dalam kotak Kategori Log di jendela penampil log pengikatan. Fuslogvw.exe memberikan informasi tentang mengapa gambar asli ditolak.

Asisten penelusuran kesalahan terkelola jitCompilationStart

Anda dapat menggunakan asisten penelusuran kesalahan terkelola (MDA) jitCompilationStart untuk menentukan kapan pengompilasi JIT mulai mengompilasi fungsi.

Menolak pembuatan gambar asli

Dalam beberapa kasus, NGen.exe mungkin mengalami kesulitan menghasilkan gambar asli untuk metode tertentu, atau Anda mungkin lebih suka bahwa metode tersebut dikompilasi JIT daripada dikompilasi ke gambar asli. Dalam hal ini, Anda dapat menggunakan System.Runtime.BypassNGenAttribute atribut untuk mencegah NGen.exe menghasilkan gambar asli untuk metode tertentu. Atribut harus diterapkan satu per satu ke setiap metode yang kodenya tidak ingin Anda sertakan dalam gambar asli. NGen.exe mengenali atribut dan tidak menghasilkan kode dalam gambar asli untuk metode yang sesuai.

Namun, perhatikan bahwa itu BypassNGenAttribute tidak didefinisikan sebagai jenis di Pustaka Kelas .NET Framework. Untuk menggunakan atribut dalam kode Anda, Anda harus terlebih dahulu mendefinisikannya sebagai berikut:

namespace System.Runtime
{
   [AttributeUsage(AttributeTargets.Method |
                   AttributeTargets.Constructor |
                   AttributeTargets.Property)]
   public class BypassNGenAttribute : Attribute
   {
   }
}

Namespace System.Runtime
    <AttributeUsage(AttributeTargets.Method Or
                    AttributeTargets.Constructor Or
                    AttributeTargets.Property)>
    Public Class BypassNGenAttribute : Inherits Attribute
    End Class
End Namespace

Anda kemudian dapat menerapkan atribut berdasarkan per metode. Contoh berikut menginstruksikan Generator Gambar Asli bahwa itu tidak boleh menghasilkan gambar asli untuk metode .ExampleClass.ToJITCompile

using System;
using System.Runtime;

public class ExampleClass
{
   [BypassNGen]
   public void ToJITCompile()
   {
   }
}

Imports System.Runtime

Public Class ExampleClass
    <BypassNGen>
    Public Sub ToJITCompile()
    End Sub
End Class

Contoh

Perintah berikut menghasilkan gambar asli untuk ClientApp.exe, yang terletak di direktori saat ini, dan memasang gambar di cache gambar asli. Jika ada file konfigurasi untuk assembly, Ngen.exe menggunakannya. Selain itu, gambar asli dihasilkan untuk file .dll apa pun yang ClientApp.exe mereferensikan.

ngen install ClientApp.exe

Gambar yang dipasang dengan Ngen.exe juga disebut root. Root dapat berupa aplikasi atau komponen bersama.

Perintah berikut menghasilkan gambar asli untuk MyAssembly.exe dengan jalur yang ditentukan.

ngen install c:\myfiles\MyAssembly.exe

Saat menemukan assembly dan dependensinya, Ngen.exe menggunakan logika pemeriksaan yang sama yang digunakan oleh runtime bahasa umum. Secara default, direktori yang berisi ClientApp.exe digunakan sebagai direktori dasar aplikasi, dan semua pemeriksaan assembly dimulai dalam direktori ini. Anda dapat mengambil alih perilaku ini dengan menggunakan opsi /AppBase ini.

Catatan

Ini adalah perubahan dari perilaku Ngen.exe dalam .NET Framework versi 1.0 dan 1.1, di mana basis aplikasi diatur ke direktori saat ini.

Assembly dapat memiliki dependensi tanpa referensi, misalnya jika memuat file .dll dengan menggunakan metode Assembly.Load. Anda dapat membuat gambar asli untuk file .dll tersebut dengan menggunakan informasi konfigurasi untuk assembly aplikasi, dengan opsi /ExeConfig. Perintah berikut menghasilkan gambar asli untuk MyLib.dll menggunakan informasi konfigurasi dari MyApp.exe.

ngen install c:\myfiles\MyLib.dll /ExeConfig:c:\myapps\MyApp.exe

Assembly yang dipasang dengan cara ini tidak dihapus saat aplikasi dihapus.

Untuk menghapus dependensi, gunakan opsi baris perintah yang sama yang digunakan untuk memasangnya. Perintah berikut menghapus pasangan MyLib.dll dari contoh sebelumnya.

ngen uninstall c:\myfiles\MyLib.dll /ExeConfig:c:\myapps\MyApp.exe

Untuk membuat gambar asli untuk assembly di cache assembly global, gunakan nama tampilan assembly. Contohnya:

ngen install "ClientApp, Version=1.0.0.0, Culture=neutral,
  PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL"

NGen.exe menghasilkan sekumpulan gambar terpisah untuk setiap skenario yang Anda pasang. Misalnya, perintah berikut memasang sekumpulan gambar asli lengkap untuk operasi normal, set lengkap lain untuk penelusuran kesalahan, dan yang ketiga untuk pembuatan profil:

ngen install MyApp.exe
ngen install MyApp.exe /debug
ngen install MyApp.exe /profile

Menampilkan Cache Gambar Asli

Setelah gambar asli dipasang di cache, gambar tersebut dapat ditampilkan menggunakan Ngen.exe. Perintah berikut menampilkan semua gambar asli dalam cache gambar asli.

ngen display

Tindakan ini display mencantumkan semua assembly root terlebih dahulu, diikuti oleh daftar semua gambar asli di komputer.

Gunakan nama sederhana assembly untuk menampilkan informasi hanya untuk assembly tersebut. Perintah berikut menampilkan semua gambar asli dalam cache gambar asli yang cocok dengan nama MyAssemblyparsial , dependensinya, dan semua root yang memiliki dependensi pada MyAssembly:

ngen display MyAssembly

Mengetahui root apa yang bergantung pada assembly komponen bersama berguna dalam mengukur dampak update tindakan setelah komponen bersama ditingkatkan.

Jika Anda menentukan ekstensi file assembly, Anda harus menentukan jalur atau menjalankan Ngen.exe dari direktori yang berisi assembly:

ngen display c:\myApps\MyAssembly.exe

Perintah berikut menampilkan semua gambar asli dalam cache gambar asli dengan nama MyAssembly dan versi 1.0.0.0.

ngen display "myAssembly, version=1.0.0.0"

Memperbarui Gambar

Gambar biasanya diperbarui setelah komponen bersama ditingkatkan. Untuk memperbarui semua gambar asli yang telah berubah, atau yang dependensinya telah berubah, gunakan tindakan update tanpa argumen.

ngen update

Memperbarui semua gambar bisa menjadi proses yang panjang. Anda dapat mengantrekan pembaruan untuk eksekusi oleh layanan gambar asli dengan menggunakan opsi /queue. Untuk informasi selengkapnya tentang /queue opsi dan prioritas pemasangan, lihat Layanan Gambar Asli.

ngen update /queue

Mencopot Pemasangan Gambar

Ngen.exe mempertahankan daftar dependensi, sehingga komponen bersama hanya dihapus saat semua assembly yang bergantung pada mereka telah dihapus. Selain itu, komponen bersama tidak dihapus jika telah dipasang sebagai root.

Perintah berikut menghapus semua skenario untuk root ClientApp.exe:

ngen uninstall ClientApp

Tindakan uninstall dapat digunakan untuk menghapus skenario tertentu. Perintah berikut menghapus semua skenario untuk root ClientApp.exe:

ngen uninstall ClientApp /debug

Catatan

Mencopot pemasangan skenario /debug tidak menghapus pemasangan skenario yang mencakup /profile dan /debug.

Perintah berikut mencopot pemasangan semua skenario untuk versi tertentu dari ClientApp.exe:

ngen uninstall "ClientApp, Version=1.0.0.0"

Perintah berikut menghapus instalan semua skenario untuk "ClientApp, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL", atau hanya skenario debug untuk rakitan tersebut:

ngen uninstall "ClientApp, Version=1.0.0.0, Culture=neutral,
  PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL"
ngen uninstall "ClientApp, Version=1.0.0.0, Culture=neutral,
  PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL" /debug

Seperti halnya install tindakan, menyediakan ekstensi memerlukan eksekusi Ngen.exe dari direktori yang berisi assembly atau menentukan jalur lengkap.

Untuk contoh yang berkaitan dengan layanan gambar asli, lihat Layanan Gambar Asli.

Tugas Gambar Asli

Tugas gambar asli adalah tugas Windows yang menghasilkan dan memelihara gambar asli. Tugas gambar asli menghasilkan dan mengklaim kembali gambar asli secara otomatis untuk skenario yang didukung. Ini juga memungkinkan alat penginstal untuk menggunakan Ngen.exe (Native Image Generator) untuk membuat dan memperbarui gambar asli pada waktu yang ditangguhkan.

Tugas gambar asli didaftarkan sekali untuk setiap arsitektur CPU yang didukung di komputer, untuk memungkinkan kompilasi untuk aplikasi yang menargetkan setiap arsitektur:

Nama tugas	Komputer 32-bit	Komputer 64-bit
NET Framework NGEN v4.0.30319	Ya	Ya
NET Framework NGEN v4.0.30319 64	Tidak	Ya

Tugas gambar asli tersedia di .NET Framework 4.5 dan versi yang lebih baru, saat berjalan di Windows 8 atau yang lebih baru. Pada versi Windows sebelumnya, .NET Framework menggunakan Layanan Gambar Asli.

Masa Pakai Tugas

Secara umum, penjadwal Tugas Windows memulai tugas gambar asli setiap malam saat komputer menganggur. Tugas memeriksa pekerjaan yang ditangguhkan yang diantrekan oleh penginstal aplikasi, permintaan pembaruan gambar asli yang ditangguhkan, dan pembuatan gambar otomatis apa pun. Tugas menyelesaikan item kerja yang tertunda lalu dimatikan. Jika komputer berhenti menganggur saat tugas sedang berjalan, tugas akan berhenti.

Anda juga dapat memulai tugas gambar asli secara manual melalui antarmuka pengguna Penjadwal Tugas atau melalui panggilan manual ke NGen.exe. Jika tugas dimulai melalui salah satu metode ini, tugas akan terus berjalan saat komputer tidak lagi menganggur. Gambar yang dibuat secara manual dengan menggunakan NGen.exe diprioritaskan untuk mengaktifkan perilaku yang dapat diprediksi untuk alat penginstal aplikasi.

Lihat Layanan Gambar Asli.

Tugas gambar asli adalah tugas Windows yang menghasilkan dan memelihara gambar asli. Layanan gambar asli memungkinkan pengembang untuk menangguhkan pemasangan dan pembaruan gambar asli ke periode saat komputer menganggur.

Biasanya, layanan gambar asli dimulai oleh program pemasangan (alat penginstal) untuk aplikasi atau pembaruan. Untuk tindakan prioritas 3, layanan dijalankan selama waktu diam di komputer. Layanan ini menyimpan statusnya dan mampu melanjutkan melalui beberapa reboot jika perlu. Beberapa kompilasi gambar dapat diantrekan.

Layanan ini juga berinteraksi dengan perintah Ngen.exe manual. Perintah manual lebih diutamakan daripada aktivitas latar belakang.

Catatan

Pada Windows Vista, nama yang ditampilkan untuk layanan gambar asli adalah "Microsoft.NET Framework NGEN v2.0.50727_X86" atau "Microsoft.NET Framework NGEN v2.0.50727_X64". Pada semua versi Microsoft Windows sebelumnya, namanya adalah ".NET Runtime Optimization Service v2.0.50727_X86" atau ".NET Runtime Optimization Service v2.0.50727_X64".

Meluncurkan Operasi yang Ditangguhkan

Sebelum memulai pemasangan atau peningkatan, disarankan untuk menjeda layanan. Ini memastikan bahwa layanan tidak dijalankan saat alat penginstal menyalin file atau menempatkan assembly di cache assembly global. Baris perintah Ngen.exe berikut menjeda layanan:

ngen queue pause

Saat semua operasi yang ditangguhkan telah diantrekan, perintah berikut memungkinkan layanan untuk melanjutkan:

ngen queue continue

Untuk menugaskan pembuatan gambar asli saat memasang aplikasi baru atau saat memperbarui komponen bersama, gunakan opsi /queue dengan tindakan install atau update. Baris perintah Ngen.exe berikut memasang gambar asli untuk komponen bersama dan melakukan pembaruan semua root yang mungkin telah terpengaruh:

ngen install MyComponent /queue
ngen update /queue

Tindakan meregenerasi update semua gambar asli yang telah dibatalkan, bukan hanya yang menggunakan MyComponent.

Jika aplikasi Anda terdiri dari banyak root, Anda dapat mengontrol prioritas tindakan yang ditangguhkan. Perintah berikut mengantre pemasangan tiga root. Assembly1 dipasang terlebih dahulu, tanpa menunggu waktu menganggur. Assembly2 juga dipasang tanpa menunggu waktu menganggur, tetapi setelah semua prioritas 1 tindakan selesai. Assembly3 dipasang saat layanan mendeteksi bahwa komputer menganggur.

ngen install Assembly1 /queue:1
ngen install Assembly2 /queue:2
ngen install Assembly3 /queue:3

Anda dapat memaksa tindakan antrean terjadi secara sinkron dengan menggunakan tindakan executeQueuedItems. Jika Anda memberikan prioritas opsional, tindakan ini hanya memengaruhi tindakan antrean yang memiliki prioritas yang sama atau lebih rendah. Prioritas default adalah 3, sehingga perintah Ngen.exe berikut segera memproses semua tindakan yang diantrekan, dan tidak kembali hingga selesai:

ngen executeQueuedItems

Perintah sinkron dijalankan oleh Ngen.exe dan tidak menggunakan layanan gambar asli. Anda dapat menjalankan tindakan menggunakan Ngen.exe saat layanan gambar asli sedang berjalan.

Pematian Layanan

Setelah dimulai oleh eksekusi perintah Ngen.exe yang menyertakan opsi /queue, layanan berjalan di latar belakang hingga semua tindakan selesai. Layanan menyimpan statusnya sehingga dapat dilanjutkan melalui beberapa reboot jika perlu. Saat layanan mendeteksi bahwa tidak ada lagi tindakan yang diantrekan, layanan mengatur ulang statusnya sehingga tidak akan dimulai ulang saat komputer di-boot, kemudian mematikan dirinya sendiri.

Interaksi Layanan dengan Klien

Di .NET Framework versi 2.0, satu-satunya interaksi dengan layanan gambar asli adalah melalui alat baris perintah Ngen.exe. Gunakan alat baris perintah dalam skrip pemasangan untuk mengantre tindakan untuk layanan gambar asli dan berinteraksi dengan layanan.

Bagikan melalui

Ngen.exe (Native Image Generator)

Sintaks

Tindakan

Argumen

Tingkat Prioritas

Skenario

Konfigurasi

Opsi

Keterangan

Menghasilkan gambar untuk skenario yang berbeda

Menentukan kapan menggunakan gambar asli

Peningkatan penggunaan memori

Pengaktifan aplikasi yang lebih cepat

Ringkasan pertimbangan penggunaan

Pentingnya alamat dasar assembly

Pengikatan keras

Menentukan petunjuk pengikatan untuk dependensi

Menentukan petunjuk pengikatan default untuk assembly

Pemrosesan yang ditangguhkan

Gambar asli dan kompilasi JIT

Gambar tidak valid

Pemecahan Masalah

Penampil Log Pengikatan Assembly

Asisten penelusuran kesalahan terkelola jitCompilationStart

Menolak pembuatan gambar asli

Contoh

Menampilkan Cache Gambar Asli

Memperbarui Gambar

Mencopot Pemasangan Gambar

Tugas Gambar Asli

Masa Pakai Tugas

Lihat Layanan Gambar Asli.

Meluncurkan Operasi yang Ditangguhkan

Pematian Layanan

Interaksi Layanan dengan Klien

Lihat juga

Sumber Daya Tambahan: