Pratinjau API

Platform .NET menganggap serius kompatibilitas. Oleh karena itu, ekosistem pustaka cenderung menghindari membuat perubahan yang memecah kompatibilitas, terutama sehubungan dengan API.

Namun, saat merancang API, penting untuk dapat mengumpulkan umpan balik dari pengguna dan membuat perubahan pada API berdasarkan umpan balik tersebut jika perlu. Untuk menghindari kejutan, Anda harus memahami API mana yang Anda gunakan dianggap stabil dan mana yang masih dalam pengembangan aktif dan mungkin berubah.

Ada beberapa cara API dapat menyatakan bahwa API itu dalam tahap pratinjau:

Artikel ini menjelaskan cara kerja setiap opsi, dan, untuk pengembang pustaka, cara memilih di antara opsi ini.

Pratinjau runtime .NET

Dengan pengecualian kandidat rilis (RC) dengan lisensi langsung, versi pratinjau runtime .NET dan SDK tidak didukung.

Dengan demikian, API apa pun yang ditambahkan sebagai bagian dari pratinjau .NET dianggap dapat berubah, berdasarkan umpan balik yang diterima pratinjau. Untuk menggunakan pratinjau runtime .NET, Anda perlu secara eksplisit menargetkan versi kerangka kerja yang lebih baru dalam proyek Anda. Dengan demikian, Anda secara implisit menyatakan persetujuan untuk menggunakan API yang mungkin berubah.

Paket NuGet prarilis

Paket NuGet dapat berupa baik stabil maupun prarilis. Paket prarilis ditandai dengan akhiran prarilis pada versi mereka. Misalnya, System.Text.Json 9.0.0-preview.2.24128.5 memiliki akhiran prarilis preview.2.24128.5.

Paket prarilis umumnya digunakan sebagai sarana untuk mengumpulkan umpan balik dari pengadopsi awal. Mereka umumnya tidak didukung oleh penulis mereka.

Saat menginstal paket, baik melalui CLI atau UI, Anda harus secara eksplisit menunjukkan apakah Anda ingin menginstal versi prarilis. Dengan demikian, Anda secara implisit menyatakan persetujuan untuk menggunakan API yang mungkin berubah.

RequiresPreviewFeaturesAttribute

Atribut RequiresPreviewFeaturesAttribute digunakan untuk API yang memerlukan perilaku pratinjau di seluruh tumpukan, termasuk runtime, pengkompilasi C#, dan pustaka. Saat Anda menggunakan API yang ditandai dengan atribut ini, Anda akan menerima kesalahan build kecuali file proyek Anda menyertakan properti <EnablePreviewFeatures>true</EnablePreviewFeatures>. Mengatur properti tersebut ke true juga mengatur <LangVersion>Preview</LangVersion>, yang memungkinkan penggunaan fitur bahasa pratinjau.

Sebagai contoh, di .NET 6 pustaka matematika generik ditandai dengan RequiresPreviewFeaturesAttribute karena memerlukan anggota antarmuka statis, yang berada dalam pratinjau pada saat itu.

ExperimentalAttribute

.NET 8 menambahkan ExperimentalAttribute, yang tidak memerlukan fitur pratinjau runtime atau bahasa dan hanya menunjukkan bahwa API yang diberikan belum stabil.

Saat membangun terhadap API eksperimental, pengkompilasi menghasilkan kesalahan. Setiap fitur yang ditandai sebagai eksperimental memiliki ID diagnostik terpisah sendiri. Untuk menyatakan persetujuan untuk menggunakan API eksperimental, Anda menonaktifkan diagnostik tertentu. Anda dapat melakukannya melalui salah satu cara untuk menekan diagnostik, tetapi cara yang disarankan adalah menambahkan diagnostik ke properti <NoWarn> proyek.

Karena setiap fitur eksperimental memiliki ID terpisah, menyetujui untuk menggunakan satu fitur eksperimental tidak menyetujui untuk menggunakan yang lain.

Untuk informasi selengkapnya, lihat fitur Eksperimental dan artikel dalam panduan C# tentang atribut umum .

Panduan untuk pengembang pustaka

Pengembang pustaka umumnya harus mengekspresikan bahwa API sedang dalam pratinjau dengan salah satu dari dua cara:

  • Untuk API baru yang diperkenalkan dalam prarilis versi dari paket Anda, Anda tidak perlu melakukan apa pun; paket sudah menunjukkan kualitas pratinjau.
  • Jika Anda ingin mengirim paket stabil yang berisi beberapa API kualitas pratinjau, Anda harus menandai API tersebut menggunakan [Experimental]. Pastikan untuk menggunakan ID diagnostik Anda sendiri dan membuatnya khusus untuk fitur-fitur tersebut. Jika Anda memiliki beberapa fitur independen, pertimbangkan untuk menggunakan beberapa ID.

Atribut [RequiresPreviewFeatures] hanya dimaksudkan untuk komponen platform .NET itu sendiri. Bahkan di sana, ini hanya digunakan untuk API yang memerlukan fitur pratinjau waktu proses dan bahasa. Jika sesuatu hanya merupakan sebuah API yang dalam pratinjau, platform .NET menggunakan atribut [Experimental].

Pengecualian untuk aturan ini adalah jika Anda membangun pustaka yang stabil dan ingin mengekspos fitur tertentu yang pada gilirannya bergantung pada perilaku pratinjau runtime atau bahasa. Dalam hal ini, Anda harus menggunakan [RequiresPreviewFeatures] untuk titik masuk fitur tersebut. Namun, Anda perlu mempertimbangkan bahwa pengguna API tersebut juga harus mengaktifkan fitur pratinjau, yang membuat mereka terpapar pada semua perilaku pratinjau runtime, pustaka, dan bahasa.

  • Last updated on