Bagikan melalui

Komponen Referensi

Rakitan referensi adalah jenis rakitan khusus yang hanya berisi jumlah minimum metadata yang diperlukan untuk mewakili permukaan API publik pustaka. Ini termasuk deklarasi untuk semua anggota yang signifikan saat merujuk assembly dalam alat pengembangan, tetapi mengecualikan semua implementasi anggota dan deklarasi anggota privat yang tidak memiliki dampak yang dapat diamati pada kontrak API-nya. Sebaliknya, rakitan reguler disebut rakitan implementasi.

Rakitan referensi tidak dapat dimuat untuk eksekusi, tetapi dapat diteruskan sebagai input kompilator dengan cara yang sama seperti rakitan implementasi. Rakitan referensi biasanya didistribusikan dengan Software Development Kit (SDK) platform atau pustaka tertentu.

Menggunakan rakitan referensi memungkinkan pengembang untuk membangun program yang menargetkan versi pustaka tertentu tanpa memiliki rakitan implementasi penuh untuk versi tersebut. Misalkan, Anda hanya memiliki versi terbaru dari beberapa pustaka di komputer Anda, tetapi Anda ingin membangun program yang menargetkan versi pustaka yang lebih lama. Jika Anda mengkompilasi langsung terhadap rakitan implementasi, Anda mungkin secara tidak sengaja menggunakan anggota API yang tidak tersedia di versi sebelumnya. Anda hanya akan menemukan kesalahan ini saat menguji program pada komputer target. Jika Anda mengkompilasi menggunakan rakitan referensi untuk versi sebelumnya, Anda akan segera mendapatkan kesalahan saat kompilasi.

Rakitan referensi juga dapat mewakili kontrak, yaitu sekumpulan API yang tidak sesuai dengan rakitan implementasi konkret. Rakitan referensi seperti itu, yang disebut perakitan kontrak, dapat digunakan untuk menargetkan beberapa platform yang mendukung set API yang sama. Misalnya, .NET Standard menyediakan rakitan kontrak, netstandard.dll, yang mewakili set API umum yang dibagikan antara platform .NET yang berbeda. Implementasi API ini terkandung dalam rakitan yang berbeda pada platform yang berbeda, seperti mscorlib.dll pada .NET Framework atau System.Private.CoreLib.dll pada .NET Core. Pustaka yang menargetkan .NET Standard dapat berjalan di semua platform yang mendukung .NET Standard.

Menggunakan rakitan referensi

Untuk menggunakan API tertentu dari proyek Anda, Anda harus menambahkan referensi ke assembly mereka. Anda dapat menambahkan referensi ke rakitan implementasi atau ke rakitan referensi. Disarankan agar Anda menggunakan rakitan referensi setiap kali tersedia. Melakukannya memastikan bahwa Anda hanya menggunakan anggota API yang didukung dalam versi target, yang dimaksudkan untuk digunakan oleh desainer API. Menggunakan rakitan referensi memastikan Anda tidak mengambil ketergantungan terhadap detail implementasi.

Rakitan referensi untuk pustaka .NET Framework didistribusikan dengan paket penargetan. Anda dapat memperolehnya dengan mengunduh alat penginstal mandiri atau dengan memilih komponen di alat penginstal Visual Studio. Untuk informasi selengkapnya, lihat Menginstal .NET Framework untuk pengembang. Untuk .NET Core dan .NET Standard, rakitan referensi secara otomatis diunduh sesuai kebutuhan (melalui NuGet) dan direferensikan. Untuk .NET Core 3.0 dan yang lebih tinggi, rakitan referensi untuk kerangka kerja inti berada dalam paket Microsoft.NETCore.App.Ref (paket Microsoft.NETCore.App digunakan sebagai gantinya untuk versi sebelum 3.0).

Saat Anda menambahkan referensi ke rakitan .NET Framework di Visual Studio menggunakan dialog Tambahkan referensi , Anda memilih rakitan dari daftar, dan Visual Studio secara otomatis menemukan rakitan referensi yang sesuai dengan versi kerangka kerja target yang dipilih dalam proyek Anda. Hal yang sama berlaku untuk menambahkan referensi langsung ke proyek MSBuild menggunakan item proyek Referensi : Anda hanya perlu menentukan nama rakitan, bukan jalur file lengkap. Saat Anda menambahkan referensi ke rakitan ini di baris perintah dengan menggunakan -reference opsi pengkompilasi (di C# dan di Visual Basic) atau dengan menggunakan Compilation.AddReferences metode di API Roslyn, Anda harus menentukan file rakitan referensi secara manual untuk versi platform target yang benar. File referensi rakitan .NET Framework terletak di %ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework direktori. Untuk .NET Core, Anda dapat memaksa operasi penerbitan untuk menyalin rakitan referensi untuk platform target Anda ke subdirektori publikasi/refs direktori output Anda dengan mengatur PreserveCompilationContext properti proyek ke true. Kemudian Anda dapat meneruskan file rakitan referensi ini ke pengkompilasi. Menggunakan DependencyContext dari paket Microsoft.Extensions.DependencyModel dapat membantu menemukan jalurnya.

Karena tidak berisi implementasi, rakitan referensi tidak dapat dimuat untuk eksekusi. Mencoba melakukannya menghasilkan System.BadImageFormatException. Jika Anda ingin memeriksa konten rakitan referensi, Anda dapat memuatnya ke dalam konteks hanya pantulan di .NET Framework (menggunakan metode Assembly.ReflectionOnlyLoad) atau ke dalam MetadataLoadContext di .NET dan .NET Framework.

Menghasilkan rakitan referensi

Membuat rakitan referensi untuk pustaka Anda dapat berguna ketika konsumen pustaka Anda perlu membangun program mereka terhadap berbagai versi pustaka. Mendistribusikan rakitan implementasi untuk semua versi ini mungkin tidak praktis karena ukurannya yang besar. Rakitan referensi berukuran lebih kecil, dan mendistribusikannya sebagai bagian dari SDK pustaka Anda mengurangi ukuran unduhan dan menghemat ruang disk.

ID dan alat build juga dapat memanfaatkan rakitan referensi untuk mengurangi waktu build jika ada solusi besar yang terdiri dari beberapa pustaka kelas. Biasanya, dalam skenario pembangunan bertahap, proyek dibangun ulang ketika salah satu file inputnya diubah, termasuk assembly yang menjadi dependensinya. Perakitan implementasi berubah setiap kali programmer mengubah implementasi anggota mana pun. Rakitan referensi hanya berubah ketika API publiknya terpengaruh. Jadi, menggunakan rakitan referensi sebagai file input alih-alih rakitan implementasi memungkinkan melompati build proyek dependen dalam beberapa kasus.

Anda dapat membuat rakitan referensi:

Jika Anda ingin mendistribusikan rakitan referensi dengan paket NuGet, Anda harus menyertakannya dalam subdirektori ref\ di bawah direktori paket alih-alih di subdirektori lib\ yang digunakan untuk rakitan implementasi.

Struktur kumpulan referensi

Rakitan referensi adalah perluasan konsep terkait, rakitan khusus metadata. Rakitan hanya-metadata memiliki badan metodenya yang digantikan dengan satu badan throw null, tetapi menyertakan semua anggota kecuali tipe anonim. Alasan untuk menggunakan throw null blok kode (dibandingkan dengan tanpa blok kode) adalah agar PEVerify dapat beroperasi dan lolos (sehingga memvalidasi kelengkapan metadata).

Rakitan referensi selanjutnya menghapus metadata (anggota privat) dari rakitan khusus metadata:

  • Rakitan referensi hanya memiliki referensi untuk apa yang dibutuhkan di permukaan API. Perakitan nyata mungkin memiliki referensi tambahan yang terkait dengan implementasi tertentu. Misalnya, rakitan referensi untuk class C { private void M() { dynamic d = 1; ... } } tidak mereferensikan jenis apa pun yang diperlukan untuk dynamic.
  • Anggota fungsi privat (metode, properti, dan peristiwa) dihapus dalam kasus di mana penghapusan mereka tidak dapat diamati berdampak pada kompilasi. Jika tidak ada atribut InternalsVisibleTo , anggota fungsi internal juga dihapus.

Metadata dalam rakitan referensi terus menyimpan informasi berikut:

  • Semua jenis, termasuk jenis privat dan berlapis.
  • Semua atribut, bahkan yang internal.
  • Semua metode virtual.
  • Implementasi antarmuka eksplisit.
  • Properti dan peristiwa yang diimplementasikan secara eksplisit, karena metode pengaksesnya bersifat virtual.
  • Semua bidang struktur.

Rakitan referensi menyertakan atribut ReferenceAssembly pada tingkat rakitan. Atribut ini dapat ditentukan dalam sumber; maka pengkompilasi tidak perlu mensintesisnya. Karena atribut ini, runtime akan menolak untuk memuat rakitan referensi untuk eksekusi (tetapi dapat dimuat dalam mode refleksi saja).

Detail struktur perakitan referensi yang tepat tergantung pada versi pengkompilasi. Versi yang lebih baru dapat memilih untuk mengecualikan lebih banyak metadata jika ditentukan sebagai tidak memengaruhi permukaan API publik.

Nota

Informasi di bagian ini hanya berlaku untuk rakitan referensi yang dihasilkan oleh pengkompilasi Roslyn mulai dari C# versi 7.1 atau Visual Basic versi 15.3. Struktur rakitan referensi untuk pustaka .NET Framework dan .NET Core dapat berbeda dalam beberapa detail, karena mereka menggunakan mekanisme mereka sendiri untuk menghasilkan rakitan referensi. Misalnya, mereka mungkin memiliki bagian metode yang benar-benar kosong daripada throw null bagian. Tetapi prinsip umum masih berlaku: mereka tidak memiliki implementasi metode yang dapat digunakan dan hanya berisi metadata untuk anggota yang memiliki dampak yang dapat diamati dari perspektif API publik.

Lihat juga

  • Last updated on