Pratinjau API

  • Artikel

Platform .NET membanggakan diri dengan mengambil kompatibilitas dengan serius. Dengan demikian, ekosistem pustaka cenderung menghindari membuat perubahan yang melanggar, terutama sehubungan dengan API.

Namun, saat merancang API, penting untuk mengumpulkan umpan balik dari pengguna dan mengubah API berdasarkan umpan balik tersebut jika perlu. Untuk menghindari kejutan, penting bagi pengguna untuk memahami API mana yang dianggap stabil dan mana yang masih dalam pengembangan aktif dan mungkin berubah.

Ada beberapa cara api dapat diekspresikan dalam bentuk pratinjau:

  • Seluruh komponen dianggap sebagai pratinjau:

    • Diekspos dalam rilis pratinjau runtime .NET
    • Diekspos dalam paket NuGet prarilis

  • Komponen yang stabil secara khusus menandai API tertentu sebagai pratinjau:

Artikel ini menjelaskan cara memilih antara opsi ini dan cara kerja masing-masing opsi tersebut.

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 harus secara eksplisit menargetkan versi kerangka kerja yang lebih baru. Dengan demikian, Anda secara implisit menyatakan persetujuan untuk menggunakan API yang mungkin berubah.

Paket NuGet prarilis

Paket NuGet dapat stabil atau ditandai sebagai prarilis, yaitu paket memiliki akhiran prarilis. Misalnya, System.Text.Json 9.0.0-preview.2.24128.5 memiliki akhiran prarilis dari preview.2.24128.5.

Penulis paket umumnya tidak mendukung paket prarilis dan menggunakannya sebagai sarana untuk mengumpulkan umpan balik dari pengadopsi awal.

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

RequiresPreviewFeaturesAttribute

Sejak .NET 6, platform menyertakan RequiresPreviewFeaturesAttribute atribut .

Atribut ini 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 proyek Anda menetapkan <EnablePreviewFeatures>true</EnablePreviewFeatures>. Mengatur properti tersebut ke true juga mengatur <LangVersion>Preview</LangVersion>, memungkinkan penggunaan fitur bahasa pratinjau.

Tim .NET menggunakan RequiresPreviewFeaturesAttribute atribut di .NET 6 untuk menguji matematika generik, karena diperlukan anggota antarmuka statis, yang berada dalam pratinjau pada saat itu.

ExperimentalAttribute

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

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

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

Pilih di antara opsi

Pengembang pustaka hanya boleh menggunakan paket NuGet prarilis atau menandai API dengan [Experimental]:

  • Untuk API baru yang diperkenalkan dalam versi prarilis paket Anda, Anda tidak perlu melakukan apa pun; paket sudah mengekspresikan 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] ini hanya dimaksudkan untuk komponen platform .NET itu sendiri. Dan bahkan di sana hanya digunakan untuk API yang memerlukan fitur pratinjau runtime dan bahasa. Jika hanya API yang dalam pratinjau, platform .NET menggunakan [Experimental] atribut .

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 mengeksposnya ke semua perilaku pratinjau runtime, pustaka, dan bahasa.