Preview-API's
Het .NET-platform neemt compatibiliteit serieus. Het bibliotheekecosysteem is er daarom op gericht om ingrijpende veranderingen, vooral met betrekking tot de API, te vermijden.
Bij het ontwerpen van API's is het echter belangrijk om feedback van gebruikers te verzamelen en zo nodig wijzigingen aan te brengen in de API op basis van die feedback. Om verrassingen te voorkomen, moet u begrijpen welke API's u gebruikt als stabiel en welke nog steeds actief zijn in ontwikkeling en kunnen veranderen.
Er zijn meerdere manieren waarop een API kan uitdrukken dat deze zich in preview-vorm bevindt:
Het hele onderdeel wordt beschouwd als preview als deze beschikbaar is:
- In een preview-versie van de .NET-runtime.
- In een prerelease NuGet-pakket.
Een ander stabiel onderdeel markeert specifieke API's als preview met de volgende kenmerken:
In dit artikel wordt uitgelegd hoe elke optie werkt en hoe u voor bibliotheekontwikkelaars kunt kiezen tussen deze opties.
.NET Runtime previews
Met uitzondering van releasekandidaten (RC's) met een go-live licentie, worden preview-versies van de .NET-runtime en SDK niet ondersteund.
Als zodanig worden alle API's die zijn toegevoegd als onderdeel van een .NET-preview beschouwd als onderhevig aan wijzigingen, op basis van feedback die de previews ontvangen. Als u een .NET Runtime-preview wilt gebruiken, moet u zich expliciet richten op een nieuwere frameworkversie in uw project. Als u dit doet, geeft u impliciet toestemming om API's te gebruiken die kunnen worden gewijzigd.
prerelease NuGet-pakketten
NuGet-pakketten kunnen stabiel zijn of prerelease-. Prereleasepakketten worden als zodanig gemarkeerd met een prereleaseachtervoegsel op hun versie.
System.Text.Json 9.0.0-preview.2.24128.5 heeft bijvoorbeeld een prerelease-achtervoegsel van preview.2.24128.5.
Prereleasepakketten worden vaak gebruikt als een middel om feedback van early adopters te verzamelen. Ze worden over het algemeen niet ondersteund door hun auteur.
Wanneer u een pakket installeert, via de CLI of de gebruikersinterface, moet u expliciet aangeven of u een voorlopige versie wilt installeren. Als u dit doet, geeft u impliciet toestemming om API's te gebruiken die kunnen worden gewijzigd.
RequiresPreviewFeaturesAttribute
Het kenmerk RequiresPreviewFeaturesAttribute wordt gebruikt voor API's waarvoor preview-gedrag in de stack is vereist, waaronder de runtime, de C#-compiler en bibliotheken. Wanneer u API's gebruikt die zijn gemarkeerd met dit kenmerk, ontvangt u een buildfout, tenzij uw projectbestand de eigenschap <EnablePreviewFeatures>true</EnablePreviewFeatures>bevat. Als u deze eigenschap instelt op true wordt ook <LangVersion>Preview</LangVersion>ingesteld, waardoor de preview-taalfuncties kunnen worden gebruikt.
Als voorbeeld werd in .NET 6 de algemene wiskundige-bibliotheek gemarkeerd met RequiresPreviewFeaturesAttribute omdat er statische interfaceleden vereist waren, die op dat moment in een previewfase verkeerden.
ExperimentalAttribute
.NET 8 heeft ExperimentalAttributetoegevoegd. Hiervoor zijn geen runtime- of taalvoorbeeldfuncties vereist en wordt gewoon aangegeven dat een bepaalde API nog niet stabiel is.
Bij het bouwen op basis van een experimentele API produceert de compiler een fout. Elke functie die als experimenteel is gemarkeerd, heeft een eigen afzonderlijke diagnostische id. Als u toestemming wilt geven voor het gebruik van een experimentele API, onderdrukt u de specifieke diagnose. U kunt dit doen via een van de middelen voor het onderdrukken van diagnostische gegevens, maar de aanbevolen manier is om de diagnose toe te voegen aan de eigenschap <NoWarn> van het project.
Omdat elke experimentele functie een afzonderlijke id heeft, geeft toestemming voor het gebruik van één experimentele functie geen toestemming voor het gebruik van een andere.
Zie Experimentele functies en het artikel in de C#-handleiding over algemene kenmerkenvoor meer informatie.
Richtlijnen voor bibliotheekontwikkelaars
Bibliotheekontwikkelaars moeten over het algemeen duidelijk maken dat een API op twee manieren in preview is:
- Voor nieuwe API's die zijn geïntroduceerd in een prerelease versie van uw pakket, hoeft u niets te doen; het pakket geeft al de preview-kwaliteit aan.
- Als u een stabiel pakket met enkele preview-kwaliteits-API's wilt verzenden, moet u deze API's markeren met behulp van
[Experimental]. Zorg ervoor dat u uw eigen diagnostische id gebruikt en deze specifiek maakt voor deze functies. Als u meerdere onafhankelijke functies hebt, kunt u overwegen om meerdere id's te gebruiken.
Het kenmerk [RequiresPreviewFeatures] is alleen bedoeld voor onderdelen van het .NET-platform zelf. Zelfs daar wordt het alleen gebruikt voor API's waarvoor runtime- en taalvoorbeeldfuncties zijn vereist. Als het alleen een API is die in preview is, gebruikt het .NET-platform het kenmerk [Experimental].
De uitzondering op deze regel is als u een stabiele bibliotheek bouwt en bepaalde functies wilt weergeven die op zijn beurt afhankelijk zijn van runtime- of taalvoorbeeldgedrag. In dat geval moet u [RequiresPreviewFeatures] gebruiken voor de toegangspunten van die functie. U moet er echter rekening mee houden dat gebruikers van dergelijke API's ook preview-functies moeten inschakelen, waardoor ze beschikbaar zijn voor alle runtime-, bibliotheek- en taalvoorbeeldgedrag.
