Mengalihkan versi rakitan

2025-03-06

Nota

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

Anda dapat mengalihkan referensi pengikatan waktu kompilasi ke rakitan .NET Framework, rakitan pihak ketiga, atau rakitan aplikasi Anda sendiri. Anda dapat mengalihkan aplikasi untuk menggunakan versi perakitan yang berbeda dengan sejumlah cara: melalui kebijakan penerbit, melalui file konfigurasi aplikasi, atau melalui file konfigurasi komputer. Artikel ini membahas cara kerja binding assembly di .NET Framework dan bagaimana Anda dapat mengkonfigurasikannya.

Tips

Artikel ini khusus untuk aplikasi .NET Framework. Untuk informasi tentang pemuatan assembly di .NET 5+ (dan .NET Core), lihat Pemuatan Dependensi di .NET.

Unifikasi rakitan dan pengikatan default

Pengikatan ke rakitan .NET Framework terkadang dialihkan melalui proses yang disebut penyatuan rakitan . .NET Framework terdiri dari versi runtime bahasa umum dan sekitar dua lusin rakitan .NET Framework yang membentuk pustaka jenis. Rakitan .NET Framework ini diperlakukan oleh runtime sebagai satu unit. Secara bawaan, ketika sebuah aplikasi diluncurkan, semua referensi ke tipe dalam kode yang dijalankan oleh runtime diarahkan ke rakitan .NET Framework yang memiliki nomor versi yang sama dengan runtime yang sedang berjalan dalam sebuah proses. Pengalihan yang terjadi dengan model ini adalah perilaku default untuk runtime.

Misalnya, jika aplikasi Anda mereferensikan jenis di namespace System.XML dan dibangun dengan menggunakan .NET Framework 4.5, aplikasi tersebut berisi referensi statis ke rakitan System.XML yang dikirim dengan runtime versi 4.5. Jika Anda ingin mengalihkan referensi pengikatan untuk menunjuk ke rakitan System.XML yang dikirim dengan .NET Framework 4, Anda dapat meletakkan informasi pengalihan dalam file konfigurasi aplikasi. Pengalihan penautan dalam file konfigurasi untuk rakitan .NET Framework terpadu menghentikan unifikasi untuk rakitan tersebut.

Selain itu, Anda mungkin ingin mengalihkan pengikatan rakitan secara manual untuk rakitan pihak ketiga jika ada beberapa versi yang tersedia.

Tips

Jika Anda memperbarui paket NuGet yang direferensikan aplikasi Anda secara tidak langsung dan mulai melihat kesalahan baru seperti FileLoadException, MissingMethodException, TypeLoadException, atau FileNotFoundException, Anda mungkin perlu mengaktifkan pengalihan pengikatan otomatis atau menambahkan pengalihan pengikatan secara manual. Ini adalah hal yang normal saat memperbarui paket NuGet dan merupakan hasil dari beberapa paket yang dibangun menggunakan versi dependensi yang lebih lama. Kutipan file konfigurasi aplikasi berikut ini menambahkan pengalihan pengikatan untuk paket System.Memory :

<dependentAssembly>
   <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
   <bindingRedirect oldVersion="0.0.0.0-4.0.2.0" newVersion="4.0.2.0" />
</dependentAssembly>

Mengalihkan versi dengan menggunakan kebijakan penerbit

Penyedia rakitan dapat mengarahkan aplikasi ke versi terbaru dari sebuah rakitan dengan menyertakan file kebijakan penerbit bersama rakitan baru. File kebijakan penerbit, yang terletak di cache perakitan global, berisi pengaturan pengalihan perakitan.

Setiap utama.versi kecil dari rakitan memiliki file kebijakan penerbitnya sendiri. Misalnya, pengalihan dari versi 2.0.2.222 ke 2.0.3.000 dan dari versi 2.0.2.321 ke versi 2.0.3.000 keduanya masuk ke file yang sama, karena dikaitkan dengan versi 2.0. Namun, pengalihan dari versi 3.0.0.999 ke versi 4.0.0.000 masuk ke file untuk versi 3.0.999. Setiap versi utama .NET Framework memiliki file kebijakan penerbitnya sendiri.

Jika berkas kebijakan penerbit ada untuk perakitan, runtime memeriksa berkas ini setelah memeriksa manifes perakitan dan berkas konfigurasi aplikasi. Vendor harus menggunakan file kebijakan penerbit hanya ketika rakitan baru kompatibel dengan versi sebelumnya dari rakitan yang dialihkan.

Anda dapat melewati kebijakan penerbit untuk aplikasi Anda dengan menentukan pengaturan dalam file konfigurasi aplikasi, seperti yang dibahas dalam Bagian Melewati Kebijakan Penerbit.

Mengalihkan versi di tingkat aplikasi

Ada beberapa teknik berbeda untuk mengubah perilaku pengikatan untuk aplikasi Anda melalui file konfigurasi aplikasi: Anda dapat mengedit file secara manual, Anda dapat mengandalkan pengalihan pengikatan otomatis, atau Anda dapat menentukan perilaku pengikatan dengan melewati kebijakan penerbit.

Mengedit file konfigurasi aplikasi secara manual

Anda dapat mengedit file konfigurasi aplikasi secara manual untuk mengatasi masalah perakitan. Misalnya, jika vendor merilis versi rakitan yang lebih baru yang digunakan aplikasi Anda tanpa menyediakan kebijakan penerbit (karena tidak menjamin kompatibilitas mundur), Anda dapat mengarahkan aplikasi Anda untuk menggunakan versi perakitan yang lebih baru dengan menempatkan informasi pengikatan perakitan di file konfigurasi aplikasi Anda sebagai berikut.

<dependentAssembly>
  <assemblyIdentity name="someAssembly"
    publicKeyToken="32ab4ba45e0a69a1"
    culture="en-us" />
  <bindingRedirect oldVersion="7.0.0.0" newVersion="8.0.0.0" />
</dependentAssembly>

Memanfaatkan pengalihan pengikatan otomatis

Saat Anda membuat aplikasi desktop di Visual Studio yang menargetkan .NET Framework 4.5.1 atau versi yang lebih baru, aplikasi menggunakan pengalihan pengikatan otomatis. Ini berarti bahwa jika dua komponen mereferensikan versi yang berbeda dari rakitan bernama kuat yang sama, runtime secara otomatis menambahkan pengalihan pengikatan ke versi rakitan yang lebih baru dalam file konfigurasi aplikasi output (app.config). Pengalihan ini menggantikan penyatuan rakitan yang mungkin terjadi. File app.config sumber tidak dimodifikasi. Misalnya, aplikasi Anda secara langsung mereferensikan komponen .NET Framework di luar band tetapi menggunakan pustaka pihak ketiga yang menargetkan versi lama dari komponen yang sama. Saat Anda mengkompilasi aplikasi, file konfigurasi aplikasi output dimodifikasi untuk berisi pengalihan pengikatan ke versi komponen yang lebih baru.

Jika Anda membuat aplikasi web, Anda menerima peringatan build mengenai konflik pengikatan, yang pada gilirannya, memberi Anda opsi untuk menambahkan pengalihan pengikatan yang diperlukan ke file konfigurasi web sumber.

Jika Anda menambahkan pengalihan pengikatan secara manual ke file app.config sumber, pada waktu kompilasi, Visual Studio mencoba menyatukan rakitan berdasarkan pengalihan pengikatan yang Anda tambahkan. Misalnya, Anda menyisipkan pengalihan pengikatan berikut untuk assembly:

<bindingRedirect oldVersion="3.0.0.0" newVersion="2.0.0.0" />

Jika proyek lain dalam aplikasi Anda mereferensikan versi 1.0.0.0 dari rakitan yang sama, pengalihan pengikatan otomatis menambahkan entri berikut ke file app.config output sehingga aplikasi disatukan pada versi 2.0.0.0 dari rakitan ini:

<bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0" />

Anda dapat mengaktifkan pengalihan pengikatan otomatis jika aplikasi Anda menargetkan versi .NET Framework yang lebih lama. Anda dapat mengambil alih perilaku default ini dengan memberikan informasi pengalihan pengikatan dalam file app.config untuk perakitan apa pun, atau dengan menonaktifkan fitur pengalihan pengikatan. Untuk informasi tentang cara mengaktifkan atau menonaktifkan fitur ini, lihat Cara: Mengaktifkan dan Menonaktifkan Pengalihan Pengikatan Otomatis.

Mengabaikan kebijakan penerbit

Anda dapat mengambil alih kebijakan penerbit dalam file konfigurasi aplikasi jika perlu. Misalnya, versi baru dari rakitan yang mengklaim memiliki kompatibilitas mundur masih dapat merusak aplikasi. Jika Anda ingin melewati kebijakan penerbit, tambahkan elemen <publisherPolicy> ke elemen <dependentAssembly> dalam file konfigurasi aplikasi, dan atur atribut apply ke no, yang menggantikan pengaturan yes sebelumnya.

<publisherPolicy apply="no" />

Lewati kebijakan penerbit untuk menjaga aplikasi Anda tetap berjalan untuk pengguna Anda, tetapi pastikan Anda melaporkan masalah ke vendor perakitan. Jika rakitan memiliki file kebijakan penerbit, vendor harus memastikan bahwa rakitan kompatibel dengan versi sebelumnya dan klien dapat menggunakan versi baru dengan semaksimal mungkin.

Mengalihkan versi untuk pengujian, plugin, atau pustaka yang digunakan oleh komponen lain

Untuk pengujian, Anda harus membuat file .dll.config. Sebagian besar kerangka kerja pengujian unit yang ada menghormati file-file ini saat memuat pengujian.

Plugin mungkin menghormati file .dll.config, namun, plugin mungkin juga tidak. Satu-satunya mekanisme yang terjamin untuk pengalihan adalah dengan menyediakan bindingRedirects saat AppDomain dibuat.

Anda mungkin mencoba menyelesaikan masalah ini dengan penangan kejadian AssemblyResolve, tetapi hal ini tidak berfungsi karena penangan tersebut hanya dipanggil saat pemuatan gagal. Jika pemanggilan rakitan berhasil, baik karena dimuat oleh rakitan lain atau oleh host, atau sudah ada di GAC, maka handler AssemblyResolve tidak akan dipanggil.

Mengalihkan versi di tingkat komputer

Mungkin ada kasus yang jarang terjadi ketika administrator komputer ingin semua aplikasi di komputer menggunakan versi rakitan tertentu. Misalnya, versi tertentu mungkin memperbaiki lubang keamanan. Jika rakitan dialihkan dalam file konfigurasi komputer, yang disebut machine.config, semua aplikasi pada komputer yang menggunakan versi lama diarahkan untuk menggunakan versi baru. File konfigurasi komputer mengambil alih file konfigurasi aplikasi dan file kebijakan penerbit. File machine.config ini terletak di %windir%\Microsoft.NET\Framework[version]\config\machine.config untuk komputer 32-bit, atau %windir%\Microsoft.NET\Framework64[version]\config\machine.config untuk komputer 64-bit.

Tentukan pengikatan rakitan dalam file konfigurasi

Anda menggunakan format XML yang sama untuk menentukan pengalihan pengikatan baik itu dalam file konfigurasi aplikasi, file konfigurasi komputer, atau file kebijakan penerbit. Untuk mengalihkan satu versi rakitan ke versi rakitan lainnya, gunakan elemen <bindingRedirect>. Atribut oldVersion dapat menentukan satu versi rakitan atau rentang versi. Atribut newVersion harus menentukan satu versi. Misalnya, <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> menentukan bahwa runtime harus menggunakan versi 2.0.0.0 alih-alih versi rakitan antara 1.1.0.0 dan 1.2.0.0.

Contoh kode berikut menunjukkan berbagai skenario pengalihan pengikatan. Contoh ini menentukan pengalihan untuk serangkaian versi dari myAssembly, dan satu pengalihan pengikatan untuk mySecondAssembly. Contoh ini juga menentukan bahwa file kebijakan penerbit tidak dapat mengesampingkan pengalihan pengikatan untuk myThirdAssembly.

Untuk mengikat rakitan, Anda harus menentukan string "urn:schemas-microsoft-com:asm.v1" dengan atribut xmlns di tag <assemblyBinding>.

<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="myAssembly"
          publicKeyToken="32ab4ba45e0a69a1"
          culture="en-us" />
        <!-- Assembly versions can be redirected in app,
          publisher policy, or machine configuration files. -->
        <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" newVersion="3.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="mySecondAssembly"
          publicKeyToken="32ab4ba45e0a69a1"
          culture="en-us" />
             <bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
      <assemblyIdentity name="myThirdAssembly"
        publicKeyToken="32ab4ba45e0a69a1"
        culture="en-us" />
        <!-- Publisher policy can be set only in the app
          configuration file. -->
        <publisherPolicy apply="no" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Membatasi ikatan assembly ke versi tertentu

Anda dapat menggunakan atribut appliesTo pada elemen <assemblyBinding> dalam file konfigurasi aplikasi untuk mengalihkan referensi pengikatan rakitan ke versi .NET Framework tertentu. Atribut opsional ini menggunakan nomor versi .NET Framework untuk menunjukkan versi apa yang berlaku untuknya. Jika tidak ada atribut appliesTo yang ditentukan, elemen<>berlaku untuk semua versi .NET Framework.

Misalnya, untuk mengarahkan ulang pengikatan assembly untuk assembly .NET Framework 3.5, Anda akan menyertakan kode XML berikut dalam file konfigurasi aplikasi Anda.

<runtime>
  <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"
    appliesTo="v3.5">
    <dependentAssembly>
      <!-- assembly information goes here -->
    </dependentAssembly>
  </assemblyBinding>
</runtime>

Anda harus memasukkan informasi pengalihan dalam urutan versi. Misalnya, masukkan informasi pengalihan pengikatan perakitan untuk rakitan .NET Framework 3.5 diikuti oleh rakitan .NET Framework 4.5. Terakhir, masukkan informasi pengalihan pengikatan assembly untuk pengalihan assembly .NET Framework apa pun yang tidak menggunakan atribut appliesTo sehingga berlaku untuk semua versi .NET Framework. Jika ada konflik dalam pengalihan, pernyataan pengalihan yang pertama cocok dalam file konfigurasi digunakan.

Misalnya, untuk mengalihkan satu referensi ke rakitan .NET Framework 3.5 dan referensi lain ke rakitan .NET Framework 4, gunakan pola yang ditunjukkan dalam pseudocode berikut.

<assemblyBinding xmlns="..." appliesTo="v3.5 ">
  <!--.NET Framework version 3.5 redirects here -->
</assemblyBinding>

<assemblyBinding xmlns="..." appliesTo="v4.0.30319">
  <!--.NET Framework version 4.0 redirects here -->
</assemblyBinding>

<assemblyBinding xmlns="...">
  <!-- redirects meant for all versions of the runtime -->
</assemblyBinding>