Sdílet prostřednictvím

Rozhraní API ve verzi Preview

  • Článek

Platforma .NET je hrdá na to, že bere kompatibilita vážně. Ekosystém knihoven se proto snaží vyhnout se zásadním změnám, zejména pokud jde o rozhraní API.

Při navrhování rozhraní API je ale důležité shromáždit zpětnou vazbu od uživatelů a v případě potřeby rozhraní API změnit na základě této zpětné vazby. Aby nedocházelo k překvapením, je důležité, aby uživatelé pochopili, která rozhraní API jsou považována za stabilní a která rozhraní API jsou stále aktivní ve vývoji a můžou se měnit.

Existuje několik způsobů, jak se dá rozhraní API vyjádřit ve formátu Preview:

  • Celá komponenta se považuje za náhled:

    • Zveřejnění ve verzi Preview modulu runtime .NET
    • Zveřejnění v předběžném balíčku NuGet

  • Jinak stabilní komponenta konkrétně označuje určitá rozhraní API jako preview:

Tento článek vysvětluje, jak si vybrat mezi těmito možnostmi a jak jednotlivé možnosti fungují.

Verze Preview modulu runtime .NET

S výjimkou kandidátů na verze (RCS) s go-live licencí se verze Preview modulu runtime .NET a sady SDK nepodporují.

Proto se všechna rozhraní API přidaná jako součást verze .NET Preview považují za předmětem změny na základě zpětné vazby, kterou verze Preview obdrží. Pokud chcete použít modul runtime .NET Preview, musíte explicitně cílit na novější verzi architektury. Tím implicitně vyjadřujete souhlas s využíváním rozhraní API, která se můžou změnit.

Předběžné verze balíčků NuGet

Balíčky NuGet můžou být stabilní nebo označené jako předběžné verze, to znamená, že balíček má příponu předběžné verze. Například System.Text.Json 9.0.0-preview.2.24128.5 má předběžnou příponu preview.2.24128.5.

Autoři balíčků obecně nepodporují předběžné verze balíčků a používají je jako prostředek ke shromažďování zpětné vazby od dřívějších uživatelů.

Při instalaci balíčků prostřednictvím rozhraní příkazového řádku nebo uživatelského rozhraní obvykle musíte explicitně indikovat, jestli chcete předběžnou verzi nainstalovat, a implicitně vyjádřit souhlas s používáním rozhraní API, která se můžou změnit.

RequiresPreviewFeaturesAttribute

Vzhledem k tomu, že platforma .NET 6 obsahuje RequiresPreviewFeaturesAttribute atribut.

Tento atribut se používá pro rozhraní API, která vyžadují chování ve verzi Preview v zásobníku, včetně modulu runtime, kompilátoru jazyka C# a knihoven. Když používáte rozhraní API označená tímto atributem, zobrazí se chyba sestavení, pokud vaše sady projektů nenastaví <EnablePreviewFeatures>true</EnablePreviewFeatures>. Nastavení této vlastnosti tak, aby true se také nastavily <LangVersion>Preview</LangVersion>, což umožňuje používat jazykové funkce ve verzi Preview.

Tým .NET použil RequiresPreviewFeaturesAttribute atribut v .NET 6 k otestování obecné matematiky, protože vyžadoval členy statického rozhraní, které byly v době náhledu.

ExperimentalAttribute

Přidání ExperimentalAttributerozhraní .NET 8, které nevyžaduje žádné funkce runtime nebo jazyka Preview, a jednoduše značí, že dané rozhraní API ještě není stabilní.

Při sestavování na základě experimentálního rozhraní API kompilátor vyvolá chybu. Každá funkce označená jako experimentální má vlastní samostatné ID diagnostiky. Pokud chcete vyjádřit souhlas s jejich používáním, potlačíte konkrétní diagnostiku. Můžete to provést pomocí jakéhokoliv prostředku pro potlačení diagnostiky, ale doporučeným způsobem je přidat diagnostiku do vlastnosti projektu <NoWarn> .

Vzhledem k tomu, že každá experimentální funkce má samostatné ID, souhlas s použitím jedné experimentální funkce nesouhlasí s použitím jiné.

Další informace naleznete v tématu Experimentální funkce.

Volba mezi možnostmi

Vývojáři knihoven by měli používat pouze předběžné balíčky NuGet nebo označit rozhraní API pomocí [Experimental]:

  • U nových rozhraní API zavedených v předběžné verzi balíčku nemusíte nic dělat; balíček již vyjadřuje kvalitu verze Preview.

  • Pokud chcete odeslat stabilní balíček, který obsahuje některá rozhraní API pro zvýšení kvality ve verzi Preview, měli byste tato rozhraní API označit pomocí [Experimental]. Ujistěte se, že používáte vlastní ID diagnostiky a aby byly specifické pro tyto funkce. Pokud máte více nezávislých funkcí, zvažte použití více ID.

Atribut [RequiresPreviewFeatures] je určen pouze pro komponenty samotné platformy .NET. A dokonce se používá jenom pro rozhraní API, která vyžadují funkce runtime a jazyka Preview. Pokud je to jenom rozhraní API ve verzi Preview, platforma .NET tento atribut používá [Experimental] .

Výjimkou tohoto pravidla je, že pokud vytváříte stabilní knihovnu a chcete zveřejnit určité funkce, které jsou zase závislé na chování modulu runtime nebo náhledu jazyka. V takovém případě byste měli použít [RequiresPreviewFeatures] vstupní body této funkce. Je však potřeba vzít v úvahu, že uživatelé těchto rozhraní API musí také zapnout funkce preview, které je zpřístupní všem chováním modulu runtime, knihovny a náhledu jazyka.