API'leri önizleme

.NET platformu uyumluluğu ciddiye alır. Bu nedenle, kütüphane ekosistemi, özellikle API ile ilgili olarak bozucu değişiklikler yapmamaya çalışır.

Bununla birlikte, API'leri tasarlarken kullanıcılardan geri bildirim toplamak ve gerekirse bu geri bildirim temelinde API'de değişiklik yapabilmek önemlidir. Sürprizlerden kaçınmak için kullandığınız API'lerin kararlı olarak kabul edildiğini ve hangilerinin hala etkin geliştirme aşamasında olduğunu ve değişebileceğini anlamanız gerekir.

API'nin önizleme biçiminde olduğunu ifade etmenin birden çok yolu vardır:

• Bileşenin tamamı kullanıma sunulduğunda önizleme olarak kabul edilir:

  • .NET çalışma zamanının önizleme sürümünde.
  • NuGet paketinin yayın öncesi sürümünde.

• Aksi takdirde kararlı bir bileşen, belirli API'leri aşağıdaki özniteliklerle önizleme olarak işaretler:

  • RequiresPreviewFeaturesAttribute
  • ExperimentalAttribute

Bu makalede, her seçeneğin nasıl çalıştığı ve kitaplık geliştiricileri için bu seçenekler arasında nasıl seçim yapabileceğiniz açıklanmaktadır.

.NET çalışma zamanı önizlemeleri

Canlı yayın lisansına sahip sürüm adayları (CS) dışında, .NET çalışma zamanı ve SDK'nın önizleme sürümleri desteklenmez.

Bu nedenle, .NET önizlemesinin parçası olarak eklenen tüm API'ler, önizlemelerin aldığı geri bildirimlere bağlı olarak değiştirilebilir. .NET çalışma zamanı önizlemesini kullanmak için projenizde daha yeni bir çerçeve sürümünü açıkça hedeflemeniz gerekir. Bunu yaptığınızda, değişebilecek API'leri kullanma iznini örtük olarak ifade etmiş olursunuz.

Yayın öncesi NuGet paketleri

NuGet paketleri kararlı veya ön sürümolabilir. Yayın öncesi paketler, sürümlerinde ön sürüm eki ile bu şekilde işaretlenir. Örneğin, System.Text.Json 9.0.0-preview.2.24128.5, preview.2.24128.5ön sürüm soneki vardır.

Yayın öncesi paketler genellikle erken benimseyenlerden geri bildirim toplamak için bir araç olarak kullanılır. Bunlar genellikle yazarları tarafından desteklenmez.

CLI veya kullanıcı arabirimi aracılığıyla bir paket yüklediğinizde, yayın öncesi sürümü yüklemek isteyip istemediğinizi açıkça belirtmeniz gerekir. Bunu yaptığınızda, değişebilecek API'leri kullanma iznini örtük olarak ifade etmiş olursunuz.

RequiresPreviewFeaturesAttribute

RequiresPreviewFeaturesAttribute özniteliği, çalışma zamanı, C# derleyicisi ve kitaplıklar dahil olmak üzere yığın genelinde önizleme davranışları gerektiren API'ler için kullanılır. Bu öznitelikle işaretlenmiş API'leri kullandığınızda, proje dosyanız <EnablePreviewFeatures>true</EnablePreviewFeatures>özelliğini içermediği sürece bir derleme hatası alırsınız. Özelliğin true olarak ayarlanması, <LangVersion>Preview</LangVersion>'in de ayarlanmasına neden olur ve bu da önizleme dili özelliklerinin kullanılmasına izin verir.

Örnek olarak, .NET 6'da genel matematik kitaplığı, o sırada önizleme aşamasında olan statik arabirim üyeleri gerektirdiğinden RequiresPreviewFeaturesAttribute ile işaretlendi.

ExperimentalAttribute

.NET 8, çalıştırma zamanı veya dil önizleme özelliklerine ihtiyaç duymayan ve verilen bir API'nin henüz kararlı olmadığını belirten ExperimentalAttributeeklentisini ekledi.

Deneysel bir API'ye karşı derleme yaparken derleyici bir hata üretir. Deneysel olarak işaretlenmiş her özelliğin kendi ayrı tanılama kimliği vardır. Deneysel bir API'nin kullanımına onay vermek için belirli bir tanılamayı gizlemeniz gerekir. Bunu tanılamayı gizlemenin herhangi bir yolu aracılığıyla yapabilirsiniz, ancak önerilen yol tanılamayı projenin <NoWarn> özelliğine eklemektir.

Her deneysel özelliğin ayrı bir kimliği olduğundan, bir deneysel özelliğin kullanılmasına onay vermek başka bir özelliğin kullanılmasına izin vermez.

Daha fazla bilgi için deneysel özellikler ve genel özniteliklerC# kılavuzundaki makaleye bakın.

Kitaplık geliştiricileri için rehberlik

Kitaplık geliştiricileri genellikle bir API'nin önizleme aşamasında olduğunu iki yoldan biriyle ifade etmelidir:

• Paketinizin yayın öncesi sürümünde kullanıma sunulan yeni API'ler için hiçbir şey yapmanız gerekmez; paket zaten önizleme sürüm kalitesini ifade eder.
• Bazı önizleme kalitesi API'leri içeren kararlı bir paket göndermek istiyorsanız, bu API'leri [Experimental]kullanarak işaretlemeniz gerekir. Kendi tanılama kimliğinizi kullandığınızdan ve bu özelliklere özgü olduğundan emin olun. Birden çok bağımsız özelliğiniz varsa, birden çok kimlik kullanmayı göz önünde bulundurun.

[RequiresPreviewFeatures] özniteliği yalnızca .NET platformunun bileşenlerine yöneliktir. Burada bile yalnızca çalışma zamanı ve dil önizleme özellikleri gerektiren API'ler için kullanılır. Yalnızca önizleme aşamasında olan bir API ise .NET platformu [Experimental] özniteliğini kullanır.

Bu kuralın istisnası, kararlı bir kitaplık oluşturup çalışma zamanı veya dil önizleme davranışlarına bağlı olan belirli özellikleri kullanıma sunmanızdır. Bu durumda, bu özelliğin giriş noktaları için [RequiresPreviewFeatures] kullanmanız gerekir. Ancak, bu tür API'lerin kullanıcılarının da önizleme özelliklerini açması gerektiğini ve bu özelliklerin tüm çalışma zamanı, kitaplık ve dil önizleme davranışlarına açık olduğunu göz önünde bulundurmanız gerekir.