Förhandsversions-API:er
.NET-plattformen tar kompatibiliteten på allvar. Därför tenderar biblioteksekosystemet att undvika att göra icke-bakåtkompatibla ändringar, särskilt när det gäller API:et.
När du utformar API:er är det dock viktigt att kunna samla in feedback från användare och göra ändringar i API:et baserat på den feedbacken om det behövs. För att undvika överraskningar bör du förstå vilka API:er som du använder anses vara stabila och vilka som fortfarande är i aktiv utveckling och kan komma att ändras.
Det finns flera sätt som ett API kan uttrycka att det är i förhandsversionsformulär:
Hela komponenten betraktas som förhandsversion om den exponeras:
- I en förhandsversion av .NET-körmiljön.
- I en förhandsversion av NuGet-paketet.
En annars stabil komponent markerar specifika API:er som förhandsversion med följande attribut:
Den här artikeln förklarar hur varje alternativ fungerar och hur du väljer mellan de här alternativen för biblioteksutvecklare.
.NET runtime-förhandsgranskningar
Med undantag för versionskandidater (RCs) med en go-live-licens stöds inte förhandsversioner av .NET Runtime och SDK.
Därför anses eventuella API:er som läggs till som en del av en .NET-förhandsversion kunna ändras, baserat på feedback som förhandsversionerna får. Om du vill använda en .NET-körningsförhandsgranskning måste du uttryckligen rikta in dig på en nyare ramverksversion i projektet. På så sätt ger du implicit medgivande till att använda API:er som kan ändras.
Förhandsversion av NuGet-paket
NuGet-paket kan antingen vara stabila eller förhandsversion. Förhandsversionspaket markeras som sådana med ett förhandsversionssuffix på deras version.
System.Text.Json 9.0.0-preview.2.24128.5 har till exempel ett prerelease-suffix på preview.2.24128.5.
Förhandsversionspaket används ofta som ett sätt att samla in feedback från tidiga användare. De stöds vanligtvis inte av författaren.
När du installerar ett paket, antingen via CLI eller användargränssnittet, måste du uttryckligen ange om du vill installera en förhandsversion. På så sätt ger du implicit medgivande till att använda API:er som kan ändras.
RequiresPreviewFeaturesAttribute
Attributet RequiresPreviewFeaturesAttribute används för API:er som kräver förhandsgranskningsbeteenden i stacken, inklusive körningen, C#-kompilatorn och biblioteken. När du använder API:er som har markerats med det här attributet får du ett byggfel om inte projektfilen innehåller egenskapen <EnablePreviewFeatures>true</EnablePreviewFeatures>. Om du ställer in egenskapen på true anges även <LangVersion>Preview</LangVersion>, vilket gör att du kan använda förhandsgranskningsspråkfunktioner.
I .NET 6 markerades till exempel det allmänna matematiska-biblioteket med RequiresPreviewFeaturesAttribute eftersom det krävde statiska gränssnittsmedlemmar, som var i förhandsversion vid den tidpunkten.
ExperimentalAttribute
.NET 8 har lagts till ExperimentalAttribute, som inte kräver några funktioner för körning eller språkförhandsgranskning och helt enkelt anger att ett visst API inte är stabilt ännu.
När du skapar mot ett experimentellt API genererar kompilatorn ett fel. Varje funktion som är markerad som experimentell har ett eget separat diagnostik-ID. Om du vill uttrycka medgivande till att använda ett experimentellt API undertrycker du den specifika diagnostiken. Du kan göra det genom någon av metoderna för att förhindra diagnostik, men det rekommenderade sättet är att lägga till diagnostik i projektets <NoWarn>-egenskap.
Eftersom varje experimentell funktion har ett separat ID, innebär inte samtycke till att använda en experimentell funktion att man samtycker till att använda en annan.
Mer information finns i Experimentella funktioner och artikeln i C#-guiden om allmänna attribut.
Vägledning för biblioteksutvecklare
Biblioteksutvecklare bör vanligtvis uttrycka att ett API är i förhandsversion på något av två sätt:
- För nya API:er som introduceras i en -förhandsversion av ditt paket behöver du inte göra något; paketet har redan en betakvalitet.
- Om du vill skicka ett stabilt paket som innehåller vissa API:er för förhandsgranskningskvalitet bör du markera dessa API:er med hjälp av
[Experimental]. Se till att använda ditt eget diagnostik-ID och gör det specifikt för dessa funktioner. Om du har flera oberoende funktioner bör du överväga att använda flera ID:er.
Attributet [RequiresPreviewFeatures] är endast avsett för komponenter i själva .NET-plattformen. Även där används den bara för API:er som kräver funktioner för körning och språkförhandsgranskning. Om det bara är ett API som finns i förhandsversionen använder .NET-plattformen attributet [Experimental].
Undantaget till den här regeln är om du skapar ett stabilt bibliotek och vill exponera vissa funktioner som i sin tur är beroende av körnings- eller språkförhandsgranskningsbeteenden. I så fall bör du använda [RequiresPreviewFeatures] för startpunkterna för den funktionen. Du måste dock tänka på att användare av sådana API:er också måste aktivera förhandsgranskningsfunktioner, vilket gör dem tillgängliga för alla körnings-, biblioteks- och språkförhandsgranskningsbeteenden.
