Aracılığıyla paylaş

API'leri önizleme

  • Makale

.NET platformu, uyumluluğu ciddiye alarak gururludur. Bu nedenle, kitaplık ekosistemi özellikle API ile ilgili olarak hataya neden olan değişiklikler yapmaktan kaçınma eğilimindedir.

Bununla birlikte, API'leri tasarlarken kullanıcılardan geri bildirim toplamak ve gerekirse API'yi bu geri bildirime göre değiştirmek önemlidir. Sürprizlerden kaçınmak için, kullanıcıların hangi API'lerin kararlı olarak kabul edildiğini ve hangilerinin hala etkin geliştirme aşamasında olduğunu ve değişebileceğini anlaması önemlidir.

Bir API'nin önizleme biçiminde ifade edilebileceği birden çok yol vardır:

  • Bileşenin tamamı önizleme olarak kabul edilir:

    • .NET çalışma zamanının önizleme sürümünde kullanıma sunuldu
    • Yayın öncesi NuGet paketinde kullanıma sunuldu

  • Aksi takdirde kararlı bir bileşen özellikle belirli API'leri önizleme olarak işaretler:

Bu makalede, bu seçenekler arasında nasıl seçim yapabileceğiniz ve her birinin nasıl çalıştığı 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 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.

NuGet paketlerinin yayın öncesi

NuGet paketleri kararlı olabilir veya ön sürüm olarak işaretlenebilir, yani paketin yayın öncesi son eki vardır. Örneğin, System.Text.Json 9.0.0-preview.2.24128.5 ön soneki vardır preview.2.24128.5.

Paket yazarları genellikle yayın öncesi paketleri desteklemez ve bunları erken benimseyenlerden geri bildirim toplamak için bir araç olarak kullanır.

CLI veya kullanıcı arabirimi aracılığıyla paketleri yüklerken, genellikle ön sürümü yüklemek isteyip istemediğinizi açıkça belirtmeniz gerekir. Bu durum, değişebilecek API'leri kullanma iznini örtük olarak ifade eder.

RequiresPreviewFeaturesAttribute

.NET 6'dan bu yana platform özniteliğini RequiresPreviewFeaturesAttribute içerir.

Bu öznitelik, ç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, projeniz ayarlanmadığı <EnablePreviewFeatures>true</EnablePreviewFeatures>sürece bir derleme hatası alırsınız. Bu özelliği true de olarak ayarlayarak <LangVersion>Preview</LangVersion>, önizleme dili özelliklerinin kullanılmasına izin verir.

.NET ekibi RequiresPreviewFeaturesAttribute , .NET 6'daki özniteliğini kullanarak genel matematiği test etti çünkü o sırada önizleme aşamasında olan statik arabirim üyeleri gerekiyordu.

ExperimentalAttribute

.NET 8, herhangi bir çalışma zamanı veya dil önizleme özelliği gerektirmeyen ve yalnızca belirli bir API'nin henüz kararlı olmadığını gösteren öğesini ekledi ExperimentalAttribute.

Deneysel bir API'ye karşı derleme yaparken derleyici bir hata oluşturur. Deneysel olarak işaretlenen her özelliğin kendi ayrı tanılama kimliği vardır. Bunları kullanmaya açık bir şekilde onay vermek için belirli bir tanılamayı gizlemeniz gerekir. Tanılamayı gizlemenin herhangi bir yolu aracılığıyla bunu 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.

Seçenekler arasında seçim yapma

Kitaplık geliştiricileri yalnızca yayın öncesi NuGet paketlerini kullanmalı veya API'leri ile [Experimental]işaretlemelidir:

  • Paketinizin yayın öncesi sürümünde kullanıma sunulan yeni API'ler için hiçbir şey yapmanız gerekmez; paketi önizleme kalitesini zaten ifade eder.

  • Bazı önizleme kalitesi API'leri içeren kararlı bir paket göndermek istiyorsanız, bu API'leri kullanarak [Experimental]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. Ve orada 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 özniteliğini [Experimental] 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 kullanmanız [RequiresPreviewFeatures] 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.