Náhledová rozhraní API
Platforma .NET 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é, abyste mohli shromažďovat zpětnou vazbu od uživatelů a provádět změny rozhraní API na základě této zpětné vazby v případě potřeby. Abyste se vyhnuli překvapením, měli byste pochopit, která rozhraní API používáte, považována za stabilní a která rozhraní API jsou stále aktivní ve vývoji a můžou se změnit.
Existuje několik způsobů, jak může rozhraní API vyjádřit, že je ve formátu Preview:
Celá komponenta se považuje za náhled, pokud je zveřejněná.
- Ve verzi Preview modulu runtime .NET.
- V předběžné verzi balíčku NuGet.
Jinak stabilní komponenta označuje specifická rozhraní API jako náhled s následujícími atributy:
Tento článek vysvětluje, jak jednotlivé možnosti fungují, a pro vývojáře knihoven, jak si vybrat mezi těmito možnostmi.
Náhledy modulu .NET runtime
S výjimkou kandidátů na uvedení verze (RC) s go-live licencí nejsou verze Preview běhového prostředí .NET a sady SDK podporovány.
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 ve svém projektu 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 mohou být stabilní nebo předběžné verze. Předběžné verze balíčků jsou označené jako takové s příponou předběžné verze. Například System.Text.Json 9.0.0-preview.2.24128.5 má předprodejní příponu preview.2.24128.5.
Předběžné verze balíčků se běžně používají jako prostředek ke shromažďování zpětné vazby od dřívějších uživatelů. Jejich autor je obecně nepodporuje.
Při instalaci balíčku prostřednictvím rozhraní příkazového řádku nebo uživatelského rozhraní musíte explicitně určit, jestli chcete nainstalovat předběžnou verzi. Tím implicitně vyjadřujete souhlas s využíváním rozhraní API, která se můžou změnit.
RequiresPreviewFeaturesAttribute
Atribut RequiresPreviewFeaturesAttribute se používá pro rozhraní API, která vyžadují předběžné chování v celé vrstvě, 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 soubor projektu neobsahuje vlastnost <EnablePreviewFeatures>true</EnablePreviewFeatures>. Nastavení této vlastnosti na true také nastaví <LangVersion>Preview</LangVersion>, což umožňuje používat funkce jazyka Preview.
Například v .NET 6 byla obecná matematická knihovna označena RequiresPreviewFeaturesAttribute, protože vyžadovala statické členy rozhraní, které byly v té době ve verzi pro náhled.
ExperimentalAttribute
V .NET 8 byla přidána funkce ExperimentalAttribute, která nevyžaduje žádné funkce runtime ani jazykové preview a jednoduše naznačuje, že dané API ještě není stabilní.
Při sestavování proti experimentálnímu rozhraní API dojde k chybě kompilátoru. Každá funkce označená jako experimentální má vlastní samostatné DIAGNOSTICKÉ ID. Pokud chcete vyjádřit souhlas s používáním experimentálního rozhraní API, 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 <NoWarn> projektu.
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 najdete v tématu Experimentální funkce a v příručce C# článek o obecných atributech.
Pokyny pro vývojáře knihoven
Vývojáři knihoven by obecně měli vyjádřit, že rozhraní API je ve verzi Preview jedním ze dvou způsobů:
- Pro nová rozhraní API zavedená v předběžné verze 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í diagnostické ID a že je 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. I tam se používá pouze pro rozhraní API, která vyžadují runtime a náhledové funkce jazyka. Pokud je to jenom rozhraní API ve verzi Preview, platforma .NET používá atribut [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 pro vstupní body této funkce měli použít [RequiresPreviewFeatures]. Je však potřeba vzít v úvahu, že uživatelé těchto API musí také zapnout funkce preview, což je vystavuje všem možnostem náhledu modulu runtime, knihovny a jazyka.
