Perubahan mendasar

Penting bagi pustaka .NET untuk menemukan keseimbangan antara stabilitas bagi pengguna yang ada dan inovasi untuk masa depan. Penulis pustaka cenderung untuk mengubah struktur dan meninjau ulang kode sampai sempurna, tetapi mengganggu pengguna saat ini berdampak negatif, terutama untuk library tingkat rendah.

Jenis proyek dan perubahan signifikan

Bagaimana pustaka digunakan oleh komunitas .NET mempengaruhi dampak perubahan yang merusak pada pengembang akhir.

  • Pustaka berlevel rendah dan menengah seperti serialisasi, pengurai HTML, pemeta objek-relasional basis data, atau kerangka kerja web adalah yang paling terpengaruh oleh perubahan yang merusak kompatibilitas.

    Paket modul dasar digunakan oleh pengembang pengguna akhir untuk membangun aplikasi, dan oleh pustaka lain sebagai dependensi pada NuGet. Misalnya, Anda membangun aplikasi dan menggunakan klien sumber terbuka untuk memanggil layanan web. Pembaruan yang merusak pada ketergantungan yang digunakan klien bukanlah sesuatu yang dapat Anda perbaiki. Ini adalah klien sumber terbuka yang perlu diubah dan Anda tidak memiliki kontrol atasnya. Anda harus menemukan versi pustaka yang kompatibel atau mengirimkan perbaikan ke pustaka klien dan menunggu versi baru. Situasi terburuk adalah jika Anda ingin menggunakan dua pustaka yang bergantung pada versi pustaka ketiga yang saling tidak kompatibel.

  • Pustaka tingkat tinggi seperti contoh rangkaian kontrol UI lebih tidak sensitif terhadap perubahan yang dapat merusak.

    Pustaka tingkat tinggi secara langsung direferensikan dalam aplikasi pengguna akhir. Jika perubahan yang menyebabkan ketidakcocokan terjadi, pengembang dapat memilih untuk memperbarui ke versi terbaru, atau dapat memodifikasi aplikasi mereka agar dapat bekerja dengan perubahan tersebut.

✔️ DO pikirkan bagaimana pustaka Anda akan digunakan. Apakah dampak dari perubahan yang mengganggu kompatibilitas terhadap aplikasi dan pustaka yang menggunakannya?

✔️ DO meminimalkan perubahan yang mengganggu kompatibilitas saat mengembangkan pustaka .NET tingkat rendah.

✔️ PERTIMBANGKAN untuk menerbitkan penulisan ulang utama pustaka sebagai paket NuGet baru.

Jenis perubahan yang merusak

Perubahan besar masuk ke dalam kategori yang berbeda dan dampaknya tidak sama.

Perubahan pemutusan sumber

Perubahan pemecahan sumber tidak memengaruhi eksekusi program tetapi akan menyebabkan kesalahan kompilasi saat aplikasi dikompilasi ulang. Misalnya, overload baru dapat menciptakan ambiguitas dalam pemanggilan metode yang sebelumnya tidak ambigu, atau parameter yang diganti namanya akan menimbulkan kesalahan bagi pemanggil yang menggunakan parameter bernama.

public class Task
{
    // Adding a type called Task could conflict with System.Threading.Tasks.Task at compilation
}

Karena perubahan yang memecahkan kompatibilitas sumber hanya berbahaya ketika pengembang mengkompilasi ulang aplikasi mereka, itu adalah perubahan yang memecahkan kompatibilitas yang paling tidak mengganggu. Pengembang dapat memperbaiki kode sumber mereka sendiri yang rusak dengan mudah.

Perubahan yang mengubah perilaku

Perubahan perilaku adalah jenis perubahan yang paling umum: hampir semua perubahan perilaku dapat menyebabkan kesalahan logika bagi konsumen. Perubahan pada pustaka Anda, seperti tanda tangan metode, pengecualian yang dilemparkan, atau format data input atau output, semuanya dapat berdampak negatif pada pengguna pustaka Anda. Bahkan perbaikan bug dapat memenuhi syarat sebagai perubahan besar jika pengguna mengandalkan perilaku yang tadinya salah.

Menambahkan fitur dan meningkatkan perilaku buruk adalah hal yang baik, tetapi tanpa peduli itu dapat membuatnya sangat sulit bagi pengguna yang ada untuk meningkatkan. Salah satu pendekatan untuk membantu pengembang menangani perubahan yang melanggar perilaku adalah menyembunyikannya di balik pengaturan. Pengaturan memungkinkan pengembang memperbarui ke versi terbaru pustaka Anda serta memilih untuk ikut serta atau menolak perubahan yang merusak. Strategi ini memungkinkan pengembang tetap mendapatkan informasi terbaru sambil membiarkan kode konsumsi mereka beradaptasi dari waktu ke waktu.

Misalnya, ASP.NET Core MVC memiliki konsep versi kompatibilitas yang memodifikasi fitur yang diaktifkan dan dinonaktifkan pada MvcOptions.

✔️ PERTIMBANGKAN untuk membiarkan fitur baru nonaktif secara default, jika memengaruhi pengguna yang ada, dan memungkinkan pengembang ikut serta dalam fitur dengan pengaturan.

Untuk informasi selengkapnya tentang perubahan pemecahan perilaku di API .NET, lihat kompatibilitas perubahan perilaku .NET.

Perubahan pemecahan biner

Perubahan pemecahan biner terjadi saat Anda mengubah API publik pustaka Anda, sehingga rakitan yang dikompilasi terhadap versi lama pustaka Anda tidak lagi dapat memanggil API. Misalnya, mengubah signatur metode dengan menambahkan parameter baru akan menyebabkan rakitan yang dikompilasi dengan versi pustaka yang lebih lama akan menimbulkan MissingMethodException.

Perubahan pemecahan biner juga dapat merusak seluruh perakitan. Mengganti nama assembly dengan AssemblyName akan mengubah identitas assembly, demikian juga dengan menambahkan, menghapus, atau mengubah kunci penamaan kuat assembly. Perubahan identitas assembly dapat merusak semua kode terkompilasi yang menggunakannya.

❌ JANGAN ubah nama rakitan.

❌ JANGAN tambahkan, hapus, atau ubah kunci penamaan yang kuat.

✔️ PERTIMBANGKAN untuk menggunakan kelas dasar abstrak alih-alih antarmuka.

Menambahkan apa pun ke antarmuka akan menyebabkan jenis yang ada yang mengimplementasikannya gagal. Kelas dasar abstrak memungkinkan Anda menambahkan implementasi virtual default.

✔️ PERTIMBANGKAN untuk menempatkan ObsoleteAttribute pada jenis dan anggota yang ingin Anda hapus. Atribut harus memiliki instruksi untuk memperbarui kode agar tidak lagi menggunakan API usang.

Kode yang memanggil jenis dan metode dengan ObsoleteAttribute akan menghasilkan peringatan kompilasi dengan pesan yang diberikan pada atribut. Peringatan ini memberi waktu kepada orang-orang yang menggunakan API usang untuk bermigrasi, sehingga ketika API usang itu dihapus, sebagian besar sudah tidak lagi menggunakannya.

public class Document
{
    [Obsolete("LoadDocument(string) is obsolete. Use LoadDocument(Uri) instead.")]
    public static Document LoadDocument(string uri)
    {
        return LoadDocument(new Uri(uri));
    }

    public static Document LoadDocument(Uri uri)
    {
        // Load the document
    }
}

✔️ PERTIMBANGKAN untuk menyimpan jenis dan metode dengan ObsoleteAttribute pustaka tingkat rendah dan menengah tanpa batas waktu.

Menghapus API adalah perubahan yang memutus kompatibilitas biner. Pertimbangkan untuk menyimpan jenis dan metode usang jika pemeliharaannya berbiaya rendah dan tidak menambah utang teknis yang banyak ke library Anda. Tidak menghapus jenis dan metode dapat membantu menghindari skenario terburuk yang disebutkan di atas.

Untuk informasi selengkapnya tentang perubahan .NET API yang merusak kompatibilitas biner, lihat kompatibilitas kontrak publik .NET.

Lihat juga

Sebelumnya

  • Last updated on