Bagikan melalui

Cara Runtime Menemukan Komponen

Nota

Artikel ini khusus untuk .NET Framework. Ini tidak berlaku untuk implementasi .NET yang lebih baru, termasuk .NET 6 dan versi yang lebih baru.

Agar berhasil menyebarkan aplikasi .NET Framework Anda, Anda harus memahami bagaimana common language runtime menemukan dan mengikat dengan rakitan yang membentuk aplikasi Anda. Secara default, runtime mencoba untuk mengaitkan dengan versi rakitan yang tepat yang digunakan saat aplikasi dibangun. Perilaku default ini dapat diubah oleh pengaturan dalam file konfigurasi.

Common Language Runtime (CLR) melakukan sejumlah langkah saat mencoba menemukan assembly dan menyelesaikan referensi assembly. Setiap langkah dijelaskan di bagian berikut. Istilah "probing" sering digunakan saat menjelaskan bagaimana runtime menemukan assembly; istilah ini merujuk pada sekumpulan heuristik yang digunakan untuk menemukan assembly berdasarkan nama dan kulturnya.

Nota

Anda dapat melihat informasi pengikatan dalam file log menggunakan Penampil Log Pengikatan Rakitan (Fuslogvw.exe), yang disertakan dalam Windows SDK.

Memulai Pengikatan

Proses pencari lokasi dan pengikatan ke rakitan dimulai ketika runtime mencoba menyelesaikan referensi ke rakitan lain. Referensi ini bisa statis atau dinamis. Pengkompilasi merekam referensi statis dalam metadata manifes perakitan pada waktu build. Referensi dinamis dibangun dengan cepat sebagai akibat dari memanggil berbagai metode, seperti Assembly.Load.

Cara yang disukai untuk mereferensikan assembly adalah dengan menggunakan referensi lengkap, termasuk nama assembly, versi, budaya, dan token kunci publik (jika ada). Runtime menggunakan informasi ini untuk menemukan assembly, mengikuti langkah-langkah yang dijelaskan nanti di bagian ini. Runtime menggunakan proses resolusi yang sama terlepas dari apakah referensi tersebut untuk rakitan statis atau dinamis.

Anda juga dapat membuat referensi dinamis ke assembly dengan memberikan metode pemanggilan hanya dengan informasi parsial tentang assembly tersebut, seperti hanya menentukan nama assembly. Dalam hal ini, hanya direktori aplikasi yang dicari untuk perakitan, dan tidak ada pemeriksaan lain yang terjadi. Anda membuat referensi parsial menggunakan salah satu dari berbagai metode untuk memuat rakitan seperti Assembly.Load atau AppDomain.Load.

Terakhir, Anda dapat membuat referensi dinamis menggunakan metode seperti Assembly.Load dan hanya memberikan informasi parsial; Anda kemudian memenuhi syarat referensi menggunakan <elemen qualifyAssembly> dalam file konfigurasi aplikasi. Elemen ini memungkinkan Anda untuk memberikan informasi referensi lengkap (nama, versi, budaya, dan, jika berlaku, token kunci publik) dalam file konfigurasi aplikasi Anda alih-alih dalam kode Anda. Teknik ini digunakan jika Anda ingin memenuhi syarat referensi ke assembly di luar direktori aplikasi atau jika Anda ingin mereferensikan assembly di cache assembly global, tetapi Anda menginginkan kemudahan untuk menentukan referensi lengkap dalam file konfigurasi alih-alih dalam kode Anda.

Nota

Jenis referensi parsial ini tidak boleh digunakan dengan rakitan yang dibagikan di antara beberapa aplikasi. Karena pengaturan konfigurasi diterapkan per aplikasi dan bukan perakitan, rakitan bersama yang menggunakan jenis referensi parsial ini akan mengharuskan setiap aplikasi menggunakan rakitan bersama untuk memiliki informasi yang memenuhi syarat dalam file konfigurasinya.

Runtime menggunakan langkah-langkah berikut untuk menyelesaikan referensi assembly:

  1. Menentukan versi rakitan yang benar dengan memeriksa file konfigurasi yang berlaku, termasuk file konfigurasi aplikasi, file kebijakan penerbit, dan file konfigurasi komputer. Jika file konfigurasi terletak di komputer jarak jauh, runtime harus menemukan dan mengunduh file konfigurasi aplikasi terlebih dahulu.

  2. Memeriksa apakah nama rakitan telah terikat ke sebelumnya dan, jika demikian, menggunakan rakitan yang dimuat sebelumnya. Jika permintaan sebelumnya untuk memuat rakitan gagal, permintaan akan segera gagal tanpa mencoba memuat rakitan.

    Nota

    Penyimpanan dalam cache untuk kegagalan pengikatan rakitan adalah hal baru di .NET Framework versi 2.0.

  3. Memeriksa Global Assembly Cache. Jika rakitan ditemukan di sana, runtime menggunakan rakitan ini.

  4. Sonde untuk perakitan menggunakan langkah-langkah berikut:

    1. Jika konfigurasi dan kebijakan penerbit tidak memengaruhi referensi asli dan jika permintaan pengikatan dibuat menggunakan Assembly.LoadFrom metode , runtime memeriksa petunjuk lokasi.

    2. Jika basis kode ditemukan dalam file konfigurasi, runtime hanya memeriksa lokasi ini. Jika pemeriksaan ini gagal, runtime menentukan bahwa permintaan pengikatan gagal dan tidak ada pemeriksaan lain yang terjadi.

    3. Pemeriksaan untuk perakitan menggunakan heuristik yang dijelaskan di bagian pemeriksaan. Jika rakitan tidak ditemukan setelah pemeriksaan, runtime meminta Penginstal Windows untuk menyediakan rakitan. Ini bertindak sebagai fitur install-on-demand.

      Nota

      Tidak ada pemerisksaan versi untuk rakitan yang tidak memiliki nama kuat, dan runtime juga tidak memeriksa cache perakitan global untuk rakitan yang tidak memiliki nama kuat.

Langkah 1: Memeriksa File Konfigurasi

Perilaku pengikatan perakitan dapat dikonfigurasi pada tingkat yang berbeda berdasarkan tiga file XML:

  • File konfigurasi aplikasi.

  • File kebijakan penerbit.

  • File konfigurasi komputer.

File-file ini mengikuti sintaks yang sama dan memberikan informasi seperti pengalihan pengikatan, lokasi kode, dan mode pengikatan untuk rakitan tertentu. Setiap file konfigurasi dapat berisi <elemen assemblyBinding> yang mengalihkan proses pengikatan. Elemen turunan dari elemen <assemblyBinding> mencakup elemen <dependentAssembly>. Anak elemen < termasuk >, , dan <.

Nota

Informasi konfigurasi dapat ditemukan di tiga file konfigurasi; tidak semua elemen valid di semua file konfigurasi. Misalnya, mode pengikatan dan informasi jalur privat hanya dapat berada dalam file konfigurasi aplikasi. Untuk daftar lengkap informasi yang ada di setiap file, lihat Mengonfigurasi Aplikasi dengan Menggunakan File Konfigurasi.

File Konfigurasi Aplikasi

Pertama, runtime bahasa umum memeriksa file konfigurasi aplikasi untuk informasi yang mengambil alih informasi versi yang disimpan dalam manifes perakitan panggilan. File konfigurasi aplikasi dapat disebarkan dengan aplikasi, tetapi tidak diperlukan untuk eksekusi aplikasi. Biasanya pengambilan file ini hampir seketika, tetapi dalam situasi di mana basis aplikasi berada di komputer jarak jauh, seperti dalam skenario berbasis Web, file konfigurasi harus diunduh.

Untuk program klien yang dapat dieksekusi, file konfigurasi aplikasi berada di direktori yang sama dengan program eksekusi aplikasi dan memiliki nama dasar yang sama dengan program tersebut dengan ekstensi .config. Misalnya, file konfigurasi untuk C:\Program Files\Myapp\Myapp.exe C:\Program Files\Myapp\Myapp.exe.config. Dalam skenario berbasis browser, file HTML harus menggunakan <elemen tautan> untuk secara eksplisit menunjuk ke file konfigurasi.

Kode berikut menyediakan contoh sederhana file konfigurasi aplikasi. Contoh ini menambahkan TextWriterTraceListener ke koleksi Listeners untuk mengaktifkan perekaman informasi debug ke dalam file.

<configuration>
   <system.diagnostics>
      <trace useGlobalLock="false" autoflush="true" indentsize="0">
         <listeners>
            <add name="myListener" type="System.Diagnostics.TextWriterTraceListener, system version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="c:\myListener.log" />
         </listeners>
      </trace>
   </system.diagnostics>
</configuration>

File Kebijakan Penerbit

Kedua, runtime memeriksa file kebijakan penerbit, jika ada. File kebijakan penerbit didistribusikan oleh penerbit komponen sebagai perbaikan atau pembaruan untuk komponen bersama. File-file ini berisi informasi kompatibilitas yang dikeluarkan oleh penerbit komponen bersama yang mengarahkan referensi perakitan ke versi baru. Tidak seperti file konfigurasi aplikasi dan pengaturan mesin, file kebijakan penerbit terkandung dalam assembly mereka sendiri yang harus diinstal di cache assembly global.

Berikut ini adalah contoh file konfigurasi Kebijakan Penerbit:

<configuration>
    <runtime>
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">

            <dependentAssembly>
                <assemblyIdentity name="asm6" publicKeyToken="c0305c36380ba429" />
                <bindingRedirect oldVersion="3.0.0.0" newVersion="2.0.0.0"/>
            </dependentAssembly>

        </assemblyBinding>
    </runtime>
</configuration>

Untuk membuat rakitan, Anda dapat menggunakan alat Al.exe (Assembly Linker) dengan perintah seperti berikut:

Al.exe /link:asm6.exe.config /out:policy.3.0.asm6.dll /keyfile: compatkey.dat /v:3.0.0.0

compatkey.dat adalah file kunci nama yang kuat. Perintah ini membuat assembly dengan nama kuat yang dapat ditempatkan di cache perakitan global.

Nota

Kebijakan penerbit memengaruhi semua aplikasi yang menggunakan komponen bersama.

File konfigurasi kebijakan penerbit mengambil alih informasi versi yang berasal dari aplikasi (yaitu, dari manifes perakitan atau dari file konfigurasi aplikasi). Jika tidak ada pernyataan dalam file konfigurasi aplikasi untuk mengalihkan versi yang ditentukan dalam manifes perakitan, kebijakan penerbit akan mengesampingkan versi yang ditentukan dalam manifes perakitan. Namun, jika ada pernyataan pengalihan dalam file konfigurasi aplikasi, kebijakan penerbit menggantikan versi tersebut daripada yang ditentukan dalam manifes.

File kebijakan penerbit digunakan saat komponen bersama diperbarui dan versi baru komponen bersama harus diambil oleh semua aplikasi menggunakan komponen tersebut. Pengaturan dalam file kebijakan penerbit diambil alih oleh pengaturan dalam file konfigurasi aplikasi, kecuali jika file konfigurasi aplikasi memaksakan mode aman.

Mode Aman

File kebijakan penerbit biasanya diinstal secara eksplisit sebagai bagian dari paket layanan atau pembaruan program. Jika ada masalah dengan komponen bersama yang telah di-upgrade, Anda dapat mengabaikan penggantian dalam file kebijakan penerbit menggunakan mode aman (safe mode). Mode aman ditentukan oleh <elemen publisherPolicy apply="yes|no"/> , yang hanya terletak di file konfigurasi aplikasi. Ini menentukan apakah informasi konfigurasi kebijakan penerbit harus dihapus dari proses pengikatan.

Mode aman dapat diatur untuk seluruh aplikasi atau untuk rakitan yang dipilih. Artinya, Anda dapat menonaktifkan kebijakan untuk semua rakitan yang membentuk aplikasi, atau mengaktifkannya untuk beberapa rakitan tetapi tidak yang lain. Untuk menerapkan kebijakan penerbit secara selektif ke rakitan yang membentuk aplikasi, atur <publisherPolicy apply=no/> dan tentukan rakitan mana yang ingin Anda terpengaruh menggunakan < elemen dependentAssembly>. Untuk menerapkan kebijakan penerbit ke semua rakitan yang membentuk aplikasi, atur <publisherPolicy apply=no/> tanpa elemen rakitan dependen. Untuk informasi selengkapnya tentang konfigurasi, lihat Mengonfigurasi Aplikasi dengan menggunakan File Konfigurasi.

File Konfigurasi Mesin

Ketiga, runtime memeriksa file konfigurasi komputer. File ini, yang disebut Machine.config, berada di komputer lokal di subdirektori Konfigurasi direktori akar tempat runtime diinstal. File ini dapat digunakan oleh administrator untuk menentukan batasan pengikatan rakitan yang bersifat lokal untuk komputer tersebut. Pengaturan dalam file konfigurasi komputer lebih diutamakan daripada semua pengaturan konfigurasi lainnya; namun, ini tidak berarti bahwa semua pengaturan konfigurasi harus dimasukkan ke dalam file ini. Versi yang ditentukan oleh file kebijakan pengelola bersifat final, dan tidak dapat diubah. Penggantian yang ditentukan dalam file Machine.config memengaruhi semua aplikasi. Untuk informasi selengkapnya tentang file konfigurasi, lihat Mengonfigurasi Aplikasi dengan menggunakan File Konfigurasi.

Langkah 2: Memeriksa Komponen yang Dirujuk Sebelumnya

Jika rakitan yang diminta juga telah diminta dalam pemanggilan sebelumnya, kompilasi bahasa umum menggunakan rakitan yang sudah dimuat. Ini dapat memiliki ramifikasi saat menamai rakitan yang membentuk aplikasi. Untuk informasi selengkapnya tentang penamaan rakitan, lihat Nama Rakitan.

Jika permintaan sebelumnya untuk rakitan gagal, permintaan berikutnya untuk rakitan akan segera gagal tanpa mencoba memuat rakitan. Mulai dari .NET Framework versi 2.0, kegagalan pengikatan rakitan di-cache, dan informasi yang di-cache digunakan untuk menentukan apakah akan mencoba memuat rakitan.

Nota

Untuk kembali ke perilaku .NET Framework versi 1.0 dan 1.1, yang tidak menyimpan kegagalan pengikatan dalam cache, sertakan elemen <disableCachingBindingFailures> dalam file konfigurasi Anda.

Langkah 3: Memeriksa Cache Rakitan Global

Untuk assembly dengan nama yang kuat, proses pengikatan berlanjut dengan memeriksa di global assembly cache. Cache rakitan global menyimpan rakitan yang dapat digunakan oleh beberapa aplikasi di komputer. Semua rakitan dalam cache rakitan global harus memiliki nama yang kuat.

Langkah 4: Menemukan Assembly melalui Codebases atau Probing

Setelah versi rakitan yang benar ditentukan dengan menggunakan informasi dalam referensi dari rakitan panggilan dan dalam file konfigurasi, dan setelah memeriksanya di cache rakitan global (hanya untuk rakitan yang dinamai kuat), runtime bahasa umum mencoba menemukan rakitan. Proses menemukan rakitan melibatkan langkah-langkah berikut:

  1. <Jika elemen codeBase> ditemukan dalam file konfigurasi aplikasi, runtime memeriksa lokasi yang ditentukan. Jika kecocokan ditemukan, rakitan tersebut digunakan dan tidak ada pemeriksaan yang terjadi. Jika rakitan tidak ditemukan di sana, permintaan pengikatan gagal.

  2. Sistem eksekusi kemudian memeriksa komponen yang dirujuk menggunakan aturan yang ditentukan nanti di bagian ini.

Nota

Jika Anda memiliki beberapa versi assembly di direktori dan ingin mereferensikan versi tertentu dari assembly tersebut <, Anda harus menggunakan elemen codeBase> alih-alih atribut privatePath dari elemen <probing>. Jika Anda menggunakan <elemen pemeriksaan> , runtime berhenti menyelidiki pertama kali menemukan rakitan yang cocok dengan nama rakitan sederhana yang direferensikan, apakah itu kecocokan yang benar atau tidak. Jika kecocokannya benar, maka rakitan tersebut digunakan. Jika bukan kecocokan yang benar, pemeriksaan akan berhenti dan pengikatan gagal.

Menemukan Assembly melalui Codebases

Informasi basis kode dapat disediakan dengan menggunakan <elemen codeBase> dalam file konfigurasi. Basis kode ini selalu diperiksa sebelum runtime mencoba menyelidiki assembly yang direferensikan. Jika file kebijakan penerbit yang berisi pengalihan versi akhir juga berisi <elemen codeBase> , <elemen codeBase> tersebut adalah yang digunakan. Misalnya, jika file konfigurasi aplikasi Anda menentukan <elemen codeBase> , dan file kebijakan penerbit yang mengambil alih informasi aplikasi juga menentukan <elemen codeBase> , <elemen codeBase> dalam file kebijakan penerbit digunakan.

Jika tidak ada kecocokan yang ditemukan di lokasi yang ditentukan oleh <elemen codeBase> , permintaan ikatan gagal dan tidak ada langkah lebih lanjut yang diambil. Jika runtime menentukan bahwa sebuah assembly cocok dengan kriteria assembly yang memanggil, maka runtime menggunakan assembly tersebut. Ketika file yang ditentukan oleh elemen codeBase< yang diberikan> dimuat, runtime memeriksa untuk memastikan bahwa nama, versi, kultur, dan kunci publik cocok dengan referensi dari assembly pemanggil.

Nota

Komponen yang direferensikan di luar direktori akar aplikasi harus memiliki nama yang kuat dan harus dipasang di cache komponen global atau didefinisikan menggunakan elemen <codeBase>.

Menemukan Rakitan melalui Penelusuran

Jika tidak ada elemen <codeBase> dalam file konfigurasi aplikasi, runtime melakukan pemeriksaan terhadap perakitan menggunakan empat kriteria:

  • Basis aplikasi, yang merupakan lokasi akar tempat aplikasi dijalankan.

  • Budaya, yang merupakan atribut budaya dari assembly yang dirujuk.

  • Nama, yang merupakan nama rakitan yang dirujuk.

  • Atribut privatePath dari <elemen pemeriksaan>, yang merupakan daftar subdirektori yang ditentukan pengguna di bawah lokasi akar. Lokasi ini dapat ditentukan dalam file konfigurasi aplikasi dan dalam kode terkelola AppDomainSetup.PrivateBinPath menggunakan properti untuk domain aplikasi. Ketika ditentukan dalam kode terkelola, kode privatePath terkelola diperiksa terlebih dahulu, diikuti oleh jalur yang ditentukan dalam file konfigurasi aplikasi.

Menyelidiki Basis Aplikasi dan Direktori Budaya

Runtime selalu mulai memeriksa di basis aplikasi, yang dapat berupa URL atau direktori akar aplikasi di komputer. Jika rakitan yang dirujuk tidak ditemukan di basis aplikasi dan tidak ada informasi budaya yang disediakan, runtime mencari subdirektori apa pun dengan nama rakitan. Direktori yang dipindai meliputi:

  • [application base] / [assembly name].dll

  • [basis aplikasi] / [nama majelis] / [nama majelis].dll

Jika informasi budaya ditentukan untuk rakitan yang direferensikan, hanya direktori berikut yang diselidiki:

  • id-ID: [application base] / [culture] / [assembly name].dll

  • [application base] / [culture] / [assembly name] / [assembly name].dll

Memeriksa dengan Atribut privatePath

Selain subdirektori budaya dan subdirektori yang dinamai untuk perakitan yang direferensikan, runtime juga memeriksa direktori yang ditentukan menggunakan atribut privatePath dari elemen <pemeriksaan>. Direktori yang ditentukan menggunakan privatePath atribut harus subdirektori direktori akar aplikasi. Direktori yang diselidiki bervariasi tergantung pada apakah informasi budaya disertakan dalam permintaan perakitan yang direferensikan.

Waktu proses berhenti menyelidiki saat pertama kali menemukan rakitan yang cocok dengan nama rakitan sederhana yang direferensikan, baik itu cocok secara benar atau tidak. Jika kecocokannya benar, maka rakitan tersebut digunakan. Jika bukan kecocokan yang benar, pemeriksaan akan berhenti dan pengikatan gagal.

Jika budaya disertakan, direktori berikut diselidiki:

  • [application base] / [binpath] / [culture] / [assembly name].dll

  • [application base] / [binpath] / [culture] / [assembly name] / [assembly name].dll

Jika informasi budaya tidak disertakan, direktori berikut diselidiki:

  • [application base] / [binpath] / [assembly name].dll

  • [application base] / [binpath] / [assembly name] / [assembly name].dll

Contoh Pemeriksaan

Mengingat informasi berikut:

  • Nama rakitan yang dirujuk: myAssembly

  • Direktori akar aplikasi: http://www.code.microsoft.com

  • <elemen pemindaian> dalam file konfigurasi menetapkan: bin

  • Budaya: de

Runtime memeriksa URL berikut:

  • http://www.code.microsoft.com/de/myAssembly.dll

  • http://www.code.microsoft.com/de/myAssembly/myAssembly.dll

  • http://www.code.microsoft.com/bin/de/myAssembly.dll

  • http://www.code.microsoft.com/bin/de/myAssembly/myAssembly.dll

Beberapa Rakitan dengan Nama yang Sama

Contoh berikut menunjukkan cara mengonfigurasi beberapa rakitan dengan nama yang sama.

<dependentAssembly>
   <assemblyIdentity name="Server" publicKeyToken="c0305c36380ba429" />
   <codeBase version="1.0.0.0" href="v1/Server.dll" />
   <codeBase version="2.0.0.0" href="v2/Server.dll" />
</dependentAssembly>

Lokasi Lain yang Diselidiki

Lokasi rakitan juga dapat ditentukan menggunakan konteks pengikatan saat ini. Ini paling sering terjadi ketika metode Assembly.LoadFrom digunakan dalam skenario interop COM. Jika sebuah assembly menggunakan metode LoadFrom untuk mereferensikan assembly lain, lokasi assembly pemanggil dianggap sebagai petunjuk tentang di mana menemukan assembly yang dirujuk. Jika kecocokan ditemukan, komponen tersebut akan dimuat. Jika tidak ada kecocokan yang ditemukan, runtime melanjutkan pencarian berdasarkan semantiknya lalu meminta Penginstal Windows untuk menyediakan assembly. Jika tidak ada assembly yang cocok dengan permintaan pengikatan, pengecualian akan dikeluarkan. Pengecualian ini adalah TypeLoadException dalam kode terkelola jika tipe direferensikan, atau FileNotFoundException jika rakitan yang sedang dimuat tidak ditemukan.

Misalnya, jika Assembly1 mereferensikan Assembly2 dan Assembly1 diunduh dari http://www.code.microsoft.com/utils, lokasi tersebut dianggap sebagai petunjuk tentang tempat menemukan Assembly2.dll. Runtime kemudian menyelidiki perakitan di http://www.code.microsoft.com/utils/Assembly2.dll dan http://www.code.microsoft.com/utils/Assembly2/Assembly2.dll. Jika Assembly2 tidak ditemukan di salah satu lokasi tersebut, runtime memeriksa Penginstal Windows.

Lihat juga