Interfejsy API w wersji zapoznawczej

  • Artykuł

Platforma .NET jest dumna z poważnie biorąc pod uwagę zgodność. W związku z tym ekosystem biblioteki ma tendencję do unikania wprowadzania zmian powodujących niezgodność, zwłaszcza w odniesieniu do interfejsu API.

Niemniej jednak podczas projektowania interfejsów API ważne jest, aby w razie potrzeby zbierać opinie od użytkowników i zmieniać interfejs API na podstawie tej opinii. Aby uniknąć niespodzianek, ważne jest, aby użytkownicy zrozumieli, które interfejsy API są uważane za stabilne i które są nadal aktywne i mogą ulec zmianie.

Istnieje wiele sposobów wyrażania możliwości wyrażenia interfejsu API w postaci zapoznawczej:

  • Cały składnik jest traktowany jako wersja zapoznawcza:

    • Uwidocznione w wersji zapoznawczej środowiska uruchomieniowego platformy .NET
    • Uwidocznione w pakiecie NuGet w wersji wstępnej

  • W przeciwnym razie stabilny składnik oznacza określone interfejsy API jako podgląd:

W tym artykule wyjaśniono, jak wybrać między tymi opcjami i jak działają poszczególne z nich.

Wersje zapoznawcze środowiska uruchomieniowego platformy .NET

Z wyjątkiem kandydatów do wydania (RCs) z licencją go-live, wersje zapoznawcza środowiska uruchomieniowego platformy .NET i zestawu SDK nie są obsługiwane.

W związku z tym wszystkie interfejsy API dodane w ramach wersji zapoznawczej platformy .NET są uznawane za poddane zmianie, na podstawie opinii otrzymywanych wersji zapoznawczych. Aby użyć wersji zapoznawczej środowiska uruchomieniowego platformy .NET, należy jawnie kierować do nowszej wersji platformy. W ten sposób niejawnie wyrażasz zgodę na korzystanie z interfejsów API, które mogą ulec zmianie.

Pakiety NuGet w wersji wstępnej

Pakiety NuGet mogą być stabilne lub oznaczone jako wersja wstępna, czyli pakiet ma sufiks wersji wstępnej. Na przykład System.Text.Json 9.0.0-preview.2.24128.5 ma sufiks wersji wstępnej .preview.2.24128.5

Autorzy pakietów zazwyczaj nie obsługują pakietów wstępnych i używają ich jako środka do zbierania opinii od wczesnych użytkowników.

Podczas instalowania pakietów za pośrednictwem interfejsu wiersza polecenia lub interfejsu użytkownika zazwyczaj trzeba jawnie wskazać, czy chcesz zainstalować wersję wstępną, ponownie niejawnie wyrażając zgodę na korzystanie z interfejsów API, które mogą ulec zmianie.

RequiresPreviewFeaturesAttribute

Ponieważ platforma .NET 6 zawiera RequiresPreviewFeaturesAttribute atrybut .

Ten atrybut jest używany w przypadku interfejsów API, które wymagają zachowania podglądu w stosie, w tym środowiska uruchomieniowego, kompilatora języka C# i bibliotek. W przypadku korzystania z interfejsów API oznaczonych tym atrybutem zostanie wyświetlony błąd kompilacji, chyba że projekt ustawia element <EnablePreviewFeatures>true</EnablePreviewFeatures>. Ustawienie tej właściwości na true wartość ustawia <LangVersion>Preview</LangVersion>również opcję zezwalającą na korzystanie z funkcji języka w wersji zapoznawczej.

Zespół platformy .NET użył atrybutu RequiresPreviewFeaturesAttribute na platformie .NET 6, aby przetestować ogólną matematykę, ponieważ wymagał statycznych elementów członkowskich interfejsu, które były w tej chwili w wersji zapoznawczej.

ExperimentalAttribute

Platforma .NET 8 dodała ExperimentalAttributeelement , który nie wymaga żadnych funkcji środowiska uruchomieniowego ani języka w wersji zapoznawczej i po prostu wskazuje, że dany interfejs API nie jest jeszcze stabilny.

Podczas kompilowania przy użyciu eksperymentalnego interfejsu API kompilator generuje błąd. Każda funkcja oznaczona jako eksperymentalna ma własny oddzielny identyfikator diagnostyczny. Aby wyrazić zgodę na korzystanie z nich, należy pominąć określoną diagnostykę. Można to zrobić za pomocą dowolnego ze środków pomijania diagnostyki, ale zalecanym sposobem jest dodanie diagnostyki do właściwości projektu <NoWarn> .

Ponieważ każda funkcja eksperymentalna ma oddzielny identyfikator, zgoda na używanie jednej funkcji eksperymentalnej nie wyraża zgody na korzystanie z innej funkcji.

Wybieranie między opcjami

Deweloperzy bibliotek powinni używać tylko pakietów NuGet w wersji wstępnej lub oznaczać interfejsy API za pomocą polecenia [Experimental]:

  • W przypadku nowych interfejsów API wprowadzonych w wersji wstępnej pakietu nie trzeba wykonywać żadnych czynności; pakiet już wyraża jakość wersji zapoznawczej.

  • Jeśli chcesz dostarczyć stabilny pakiet zawierający niektóre interfejsy API jakości w wersji zapoznawczej, należy oznaczyć te interfejsy API przy użyciu polecenia [Experimental]. Upewnij się, że używasz własnego identyfikatora diagnostycznego i ustaw go jako specyficzne dla tych funkcji. Jeśli masz wiele niezależnych funkcji, rozważ użycie wielu identyfikatorów.

Atrybut [RequiresPreviewFeatures] jest przeznaczony tylko dla składników samej platformy .NET. A nawet w przypadku interfejsów API, które wymagają funkcji środowiska uruchomieniowego i języka w wersji zapoznawczej, są używane tylko w przypadku interfejsów API. Jeśli jest to tylko interfejs API, który jest w wersji zapoznawczej, platforma .NET używa atrybutu [Experimental] .

Wyjątkiem od tej reguły jest utworzenie stabilnej biblioteki i ujawnienie niektórych funkcji, które z kolei zależą od zachowania środowiska uruchomieniowego lub wersji zapoznawczej języka. W takim przypadku należy użyć [RequiresPreviewFeatures] dla punktów wejścia tej funkcji. Należy jednak wziąć pod uwagę, że użytkownicy takich interfejsów API muszą również włączyć funkcje w wersji zapoznawczej, co uwidacznia je we wszystkich zachowaniach środowiska uruchomieniowego, biblioteki i wersji zapoznawczej języka.