Előzetes verziójú API-k

A .NET platform komolyan veszi a kompatibilitást. Így a kódtár ökoszisztémája általában elkerüli a kompatibilitástörő módosításokat, különösen az API-t illetően.

Az API-k tervezésekor azonban fontos, hogy képes legyen visszajelzést gyűjteni a felhasználóktól, és szükség esetén módosítani az API-t ezen visszajelzés alapján. A meglepetések elkerülése érdekében tisztában kell lennie azzal, hogy mely API-kat tartja stabilnak, és mely API-k még mindig aktív fejlesztés alatt állnak, és változhatnak.

Az API többféleképpen is kifejezheti, hogy előzetes verzióban van:

• A teljes összetevő előzetes verziónak minősül, ha az elérhető:

  • A .NET-futtatókörnyezet előzetes kiadásában.
  • Egy előzetes NuGet-csomagban.

• Egy egyébként stabil összetevő előzetes verzióként jelöli meg az adott API-kat a következő attribútumokkal:

  • RequiresPreviewFeaturesAttribute
  • ExperimentalAttribute

Ez a cikk bemutatja, hogyan működnek az egyes lehetőségek, és a könyvtárfejlesztők számára hogyan választhat ezek közül.

.NET-futtatókörnyezeti előzetesek

A go-live licenccel rendelkező kiadási jelöltek (RCs-k) kivételével a .NET-futtatókörnyezet és az SDK előzetes verziói nem támogatottak.

Ezért a .NET-előzetes verzió részeként hozzáadott API-k változhatnak az előnézetek által kapott visszajelzések alapján. A .NET-futtatókörnyezet előzetes verziójának használatához explicit módon meg kell céloznia egy újabb keretrendszerverziót a projektben. Ezzel implicit módon kifejezett hozzájárulást ad ahhoz, hogy olyan API-kat használjon, amelyek változhatnak.

Előzetes verziójú NuGet-csomagok

A NuGet-csomagok lehetnek stabilak; vagy előzetes. Az előzetes kiadási csomagok a verziójukban előzetes utótaggal vannak megjelölve. Például a System.Text.Json 9.0.0-preview.2.24128.5 előzetes kiadás utótagja a preview.2.24128.5.

A prerelease csomagokat gyakran használják a korai alkalmazók visszajelzésének gyűjtésére. A szerző általában nem támogatja őket.

Ha egy csomagot a parancssori felületen vagy a felhasználói felületen keresztül telepít, explicit módon meg kell adnia, hogy telepíteni szeretné-e az előzetes verziót. Ezzel implicit módon kifejezett hozzájárulást ad ahhoz, hogy olyan API-kat használjon, amelyek változhatnak.

RequiresPreviewFeaturesAttribute

A RequiresPreviewFeaturesAttribute attribútum olyan API-khoz használatos, amelyek előzetes funkciókat igényelnek a teljes veremben, beleértve a futtatókörnyezetet, a C#-fordítót és a könyvtárakat. Ha ezzel az attribútummal megjelölt API-kat használ, buildelési hibát fog kapni, kivéve, ha a projektfájl tartalmazza a <EnablePreviewFeatures>true</EnablePreviewFeatures>tulajdonságot. A tulajdonság true-re való beállítása, beállítja a <LangVersion>Preview</LangVersion>-et is, amely lehetővé teszi az előzetes verziójú nyelvi funkciók használatát.

A .NET 6-ban például az általános matematikai-kódtárat RequiresPreviewFeaturesAttribute jelöltük meg, mert statikus illesztőtagokat igényelt, amelyek akkoriban előzetes verzióban voltak.

ExperimentalAttribute

A .NET 8 hozzáadott ExperimentalAttribute, amely nem igényel futtatókörnyezeti vagy nyelvi előzetes verziójú funkciókat, és egyszerűen azt jelzi, hogy egy adott API még nem stabil.

A kísérleti API-k létrehozásakor a fordító hibát okoz. Minden kísérletiként megjelölt funkció saját külön diagnosztikai azonosítóval rendelkezik. Ha kifejezett hozzájárulást szeretne adni egy kísérleti API használatához, letiltja az adott diagnosztikát. Ezt a diagnosztikák letiltásának bármely eszközével megteheti, de ajánlott a diagnosztikát hozzáadni a projekt <NoWarn> tulajdonságához.

Mivel minden kísérleti funkció külön azonosítóval rendelkezik, az egyik kísérleti funkció használatához való hozzájárulás nem járul hozzá a másik használatához.

További információ: Kísérleti funkciók és a C#-útmutató általános attribútumokról.

Útmutató könyvtárfejlesztőknek

A kódtár-fejlesztőknek általában kétféleképpen kell kifejeznie, hogy az API előzetes verzióban van:

• A csomag előzetes verziójában bevezetett új API-k esetében nem kell semmit tennie; a csomag már rendelkezik előzetes minőséggel.
• Ha olyan stabil csomagot szeretne szállítani, amely néhány előzetes verziójú, minőségi API-t tartalmaz, jelölje meg ezeket az API-kat a [Experimental]használatával. Mindenképpen használja saját diagnosztikai azonosítóját, és tegye az adott funkciókra jellemzővé. Ha több független funkcióval rendelkezik, fontolja meg több azonosító használatát.

A [RequiresPreviewFeatures] attribútum csak magának a .NET-platformnak az összetevőire vonatkozik. Még ott is csak olyan API-khoz használják, amelyek futtatókörnyezeti és nyelvi előzetes verziójú funkciókat igényelnek. Ha ez csak egy előzetes verziójú API, a .NET-platform a [Experimental] attribútumot használja.

A szabály alól kivételt képez az, ha stabil kódtárat hoz létre, és olyan funkciókat szeretne elérhetővé tenni, amelyek a futtatókörnyezettől vagy a nyelvi előnézet viselkedésétől függenek. Ebben az esetben a funkció belépési pontjaihoz [RequiresPreviewFeatures] kell használnia. Azonban figyelembe kell vennie, hogy az ilyen API-k felhasználóinak is be kell kapcsolniuk az előzetes verziójú funkciókat, ami minden futtatókörnyezeti, tár- és nyelvi előnézeti viselkedésnek elérhetővé teszi őket.