Assembly referensi

  • Artikel

Assembly 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 rakitan dalam alat build, tetapi mengecualikan semua implementasi anggota dan deklarasi anggota swasta yang tidak memiliki dampak yang dapat diamati pada kontrak API-nya. Sebaliknya, rakitan biasa disebut rakitan implementasi.

Assembly referensi tidak dapat dimuat untuk eksekusi, tetapi dapat diteruskan sebagai input pengkompilasi dengan cara yang sama seperti rakitan implementasi. Assembly referensi biasanya didistribusikan dengan Kit Pengembangan Perangkat Lunak (SDK) dari platform atau pustaka tertentu.

Menggunakan assembly referensi memungkinkan pengembang untuk membangun program yang menargetkan versi pustaka tertentu tanpa memiliki rakitan implementasi penuh untuk versi tersebut. Misalkan, Anda hanya memiliki versi beberapa pustaka terbaru 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 terhadap assembly referensi untuk versi yang lebih lama, Anda akan segera mendapatkan kesalahan waktu kompilasi.

Rakitan referensi juga dapat mewakili kontrak, yaitu, sekumpulan API yang tidak sesuai dengan rakitan implementasi konkret. Assembly referensi yang seperti itu, yang disebut rakitan kontrak, dapat digunakan untuk menargetkan beberapa platform yang mendukung serangkaian API yang sama. Misalnya, .NET Standard menyediakan rakitan kontrak, netstandard.dll, yang mewakili serangkaian API umum yang dibagikan antara berbagai platform .NET. 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 assembly referensi

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

Assembly 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, assembly referensi otomatis diunduh seperlunya (melalui NuGet) dan direferensikan. Untuk .NET Core 3.0 dan yang lebih tinggi, assembly 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 menambahkan referensi ke .NET Framework rakitan di Visual Studio menggunakan dialog Tambahkan referensi, Anda memilih rakitan dari daftar, dan Visual Studio otomatis menemukan assembly 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 opsi pengkompilasi -reference (di C# dan di Visual Basic) atau dengan menggunakan metode Compilation.AddReferences di API Roslyn, Anda harus menentukan file assembly referensi secara manual untuk versi platform target yang benar. File assembly referensi .NET Framework terletak di direktori %ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework. Untuk .NET Core, Anda dapat memaksa operasi penerbitan untuk menyalin assembly referensi untuk platform target Anda ke subdirektori publikasi/refs direktori output Anda dengan mengatur properti proyek PreserveCompilationContext ke true. Kemudian Anda dapat meneruskan file assembly referensi ini ke pengkompilasi. Menggunakan DependencyContext dari paket Microsoft.Extensions.DependencyModel dapat membantu menemukan jalurnya.

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

Menggunakan assembly referensi

Membuat assembly 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. Assembly referensi berukuran lebih kecil, dan mendistribusikannya sebagai bagian dari SDK pustaka Anda mengurangi ukuran unduh dan menghemat ruang disk.

ID dan alat build juga dapat memanfaatkan assembly referensi untuk mengurangi waktu build jika ada solusi besar yang terdiri dari beberapa pustaka kelas. Biasanya, dalam skenario build inkremental proyek dibangun kembali ketika salah satu file inputnya diubah, termasuk rakitan yang bergantung padanya. Rakitan implementasi berubah setiap kali pemrogram mengubah implementasi anggota mana pun. Assembly referensi berubah hanya ketika API publiknya terpengaruh. Jadi, menggunakan assembly referensi sebagai file input, bukan rakitan implementasi, memungkinkan melewatkan pembangunan proyek dependen dalam beberapa kasus.

Anda dapat membuat assembly referensi:

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

Struktur assembly referensi

Assembly referensi adalah perluasan konsep terkait, rakitan khusus metadata. Rakitan khusus metadata memiliki badan metode yang diganti dengan satu throw null isi, tetapi menyertakan semua anggota kecuali jenis anonim. Alasan untuk menggunakan throw null isi (dibandingkan dengan tidak ada isi) adalah agar PEVerify dapat berjalan dan lulus (sehingga memvalidasi kelengkapan metadata).

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

  • Assembly referensi hanya memiliki referensi untuk apa yang dibutuhkannya di permukaan API. Rakitan yang sebenarnya mungkin memiliki referensi tambahan terkait dengan implementasi tertentu. Misalnya, assembly 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 tempat penghapusannya tidak dapat diamati berdampak pada kompilasi. Jika tidak ada atribut InternalsVisibleTo, anggota fungsi internal juga dihapus.

Metadata dalam assembly 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 pengaksesnya bersifat virtual.
  • Semua bidang struktur.

Assembly referensi mencakup atribut ReferenceAssembly tingkat rakitan. Sumber atribut ini mungkin ditentukan; maka pengkompilasi tidak perlu mensintesisnya. Karena atribut ini, runtime bahasa umum akan menolak memuat assembly referensi untuk eksekusi (tetapi dapat dimuat dalam mode khusus refleksi).

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

Catatan

Informasi di bagian ini hanya berlaku untuk assembly referensi yang dihasilkan oleh pengkompilasi Roslyn mulai dari C# versi 7.1 atau Visual Basic versi 15.3. Struktur assembly referensi untuk pustaka .NET Framework dan .NET Core dapat berbeda dalam beberapa detail, karena mereka menggunakan mekanisme mereka sendiri untuk menghasilkan assembly referensi. Misalnya, strukturnya mungkin memiliki isi metode yang benar-benar kosong, bukan throw null isi. Tetapi prinsip umumnya masih berlaku: struktur 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