Interfejsy API w wersji zapoznawczej
Platforma .NET poważnie traktuje zgodność. W związku z tym ekosystem biblioteki unika wprowadzania zmian prowadzących do niekompatybilności, zwłaszcza w odniesieniu do API.
Niemniej jednak podczas projektowania interfejsów API ważne jest, aby w razie potrzeby móc zbierać opinie od użytkowników i wprowadzać zmiany w interfejsie API na podstawie tej opinii. Aby uniknąć niespodzianek, należy zrozumieć, które interfejsy API są uznawane za stabilne i które są nadal aktywne i mogą ulec zmianie.
Istnieje wiele sposobów, w jaki interfejs API może wyrazić, że jest w wersji zapoznawczej:
Cały składnik jest uznawany za podgląd, jeśli jest uwidoczniony:
- W wersji zapoznawczej środowiska uruchomieniowego platformy .NET.
- W pakiecie NuGet w wersji wstępnej.
Zwykle stabilny składnik oznacza określone interfejsy API jako wersję zapoznawczą z następującymi atrybutami:
W tym artykule wyjaśniono, jak działa każda opcja, oraz dla deweloperów biblioteki, jak wybrać między tymi opcjami.
Wersje zapoznawcze środowiska uruchomieniowego platformy .NET
Z wyjątkiem kandydatów do wydania (RCs) z licencją go-live, wersje zapoznawcze środowiska uruchomieniowego .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 wybrać nowszą wersję platformy w projekcie. 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 wersji wstępnej. Pakiety wersji wstępnej są oznaczone jako takie z sufiksem wersji wstępnej w ich wersji. Na przykład System.Text.Json 9.0.0-preview.2.24128.5 ma sufiks wersji wstępnej preview.2.24128.5.
Pakiety wersji wstępnej są często używane jako środek do zbierania opinii od wczesnych użytkowników. Zazwyczaj nie są one wspierane przez ich autora.
Podczas instalowania pakietu za pośrednictwem interfejsu wiersza polecenia lub interfejsu użytkownika należy jawnie wskazać, czy chcesz zainstalować wersję wstępną. W ten sposób niejawnie wyrażasz zgodę na korzystanie z interfejsów API, które mogą ulec zmianie.
RequiresPreviewFeaturesAttribute
Atrybut RequiresPreviewFeaturesAttribute jest używany dla interfejsów API, które wymagają zachowań podglądu w całym stacku, łącznie z środowiskiem wykonawczym, kompilatorem języka C# i bibliotekami. W przypadku korzystania z interfejsów API oznaczonych tym atrybutem zostanie wyświetlony błąd kompilacji, chyba że plik projektu zawiera właściwość <EnablePreviewFeatures>true</EnablePreviewFeatures>. Ustawienie tej właściwości na true ustawia również <LangVersion>Preview</LangVersion>, co umożliwia korzystanie z funkcji języka w wersji zapoznawczej.
Na przykład na platformie .NET 6 ogólna biblioteka matematyczna została oznaczona RequiresPreviewFeaturesAttribute, ponieważ wymagała elementów członkowskich interfejsu statycznego, które były w tej chwili w wersji zapoznawczej.
ExperimentalAttribute
Platforma .NET 8 dodała ExperimentalAttribute, która 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 eksperymentalnego interfejsu API, wyłączasz określoną diagnostykę. Można to zrobić za pomocą dowolnego ze środków tłumienia diagnostyki, ale zalecanym sposobem jest dodanie diagnostyki do właściwości <NoWarn> projektu.
Ponieważ każda funkcja eksperymentalna ma oddzielny identyfikator, zgoda na używanie jednej funkcji eksperymentalnej nie wyraża zgody na korzystanie z innej funkcji.
Aby uzyskać więcej informacji, zobacz Funkcje eksperymentalne i artykuł w przewodniku języka C# dotyczącym ogólnych atrybutów.
Wskazówki dla deweloperów bibliotek
Deweloperzy bibliotek powinni ogólnie wyrazić, że interfejs API jest w wersji zapoznawczej na jeden z dwóch sposobów:
- W przypadku nowych interfejsów API wprowadzonych w wersji wstępnej wersji pakietu nie trzeba wykonywać żadnych czynności; pakiet już wyraża jakość wersji zapoznawczej.
- Jeśli chcesz dostarczyć stabilny pakiet zawierający interfejsy API w wersji zapoznawczej, należy oznaczyć te interfejsy API przy użyciu
[Experimental]. Upewnij się, że używasz własnego identyfikatora diagnostycznego i ustaw go jako specyficzny 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. Nawet tam jest używana tylko w przypadku interfejsów API, które wymagają funkcji wersji zapoznawczej środowiska uruchomieniowego i języka. 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 naraża ich na wszystkie zapoznawcze zachowania środowiska uruchomieniowego, biblioteki i języka.
