Vorschau-APIs
Die .NET-Plattform nimmt Kompatibilität ernst. Dementsprechend vermeidet das Bibliotheksökosystem im Hinblick auf die API vor allem einschneidende Änderungen.
Dennoch ist es wichtig, beim Entwerfen von APIs Feedback von Benutzern zu sammeln und änderungen an der API vorzunehmen, je nachdem, ob das Feedback erforderlich ist. Um Überraschungen zu vermeiden, sollten Sie verstehen, welche APIs Sie verwenden, als stabil betrachtet werden und welche noch in der aktiven Entwicklung sind und sich ändern können.
Es gibt mehrere Möglichkeiten, wie eine API ausdrücken kann, dass sie sich im Vorschauformular befindet:
Die gesamte Komponente wird als Vorschau betrachtet, wenn sie verfügbar gemacht wird:
- In einer Vorschauversion der .NET-Runtime.
- In einem Vorversions-NuGet-Paket.
Eine andernfalls stabile Komponente kennzeichnet bestimmte APIs als Vorschau mit den folgenden Attributen:
In diesem Artikel wird erläutert, wie jede Option funktioniert, und wie Sie für Bibliotheksentwickler zwischen diesen Optionen wählen können.
.NET-Laufzeitvorschauen
Mit Ausnahme von Releasekandidaten (RCs) mit einer Go-Live-Lizenz werden Vorschauversionen der .NET-Runtime und des SDK nicht unterstützt.
Daher werden alle APIs, die als Teil einer .NET-Vorschau hinzugefügt wurden, als Änderungen unterworfen betrachtet, basierend auf dem Feedback, das die Vorschauen erhalten. Um eine .NET-Laufzeitvorschau zu verwenden, müssen Sie explizit auf eine neuere Framework-Version in Ihrem Projekt abzielen. Auf diese Weise erklären Sie sich implizit damit einverstanden, APIs zu nutzen, die sich ändern können.
Vorabversion von NuGet-Paketen
NuGet-Pakete können entweder stabil oder eine Vorabversion sein. Vorabversionen von Paketen werden als solche mit einem Vorabversionssuffix an ihrer Version gekennzeichnet. System.Text.Json 9.0.0-preview.2.24128.5 hat beispielsweise das Vorabversionssuffix preview.2.24128.5.
Vorabversionen von Paketen werden häufig als Mittel verwendet, um Feedback von Early Adoptern zu sammeln. Sie werden in der Regel nicht von ihrem Autor unterstützt.
Wenn Sie ein Paket entweder über die CLI oder die Benutzeroberfläche installieren, müssen Sie explizit angeben, ob Sie eine Vorabversion installieren möchten. Auf diese Weise erklären Sie sich implizit damit einverstanden, APIs zu nutzen, die sich ändern können.
RequiresPreviewFeaturesAttribute
Das RequiresPreviewFeaturesAttribute-Attribut wird für APIs verwendet, die Vorschauverhalten für den gesamten Stapel erfordern, einschließlich der Laufzeit, des C#-Compilers und der Bibliotheken. Wenn Sie APIs verwenden, die mit diesem Attribut gekennzeichnet sind, erhalten Sie einen Buildfehler, es sei denn, Ihre Projektdatei enthält die Eigenschaft <EnablePreviewFeatures>true</EnablePreviewFeatures>. Wenn Sie diese Eigenschaft auf true festlegen, wird auch <LangVersion>Preview</LangVersion>festgelegt, was die Verwendung von Vorschausprachfeatures ermöglicht.
Beispielsweise wurde die Bibliothek der generischen Mathematik in .NET 6 mit RequiresPreviewFeaturesAttribute markiert, weil sie statische Schnittstellenmember benötigte, die sich zu der Zeit in der Vorschau befanden.
ExperimentalAttribute
.NET 8 hat ExperimentalAttributehinzugefügt, was keine Laufzeit- oder Sprachvorschaufeatures erfordert und einfach angibt, dass eine bestimmte API noch nicht stabil ist.
Beim Erstellen einer experimentellen API erzeugt der Compiler einen Fehler. Jedes Feature, das als experimentell gekennzeichnet ist, verfügt über eine eigene separate Diagnose-ID. Um die Verwendung einer experimentellen API zum Ausdruck zu bringen, unterdrücken Sie die spezifische Diagnose. Sie können dies über eine der Methoden zum Unterdrücken der Diagnose tun, aber die empfohlene Methode besteht darin, die Diagnose zur <NoWarn> Eigenschaft des Projekts hinzuzufügen.
Da jedes experimentelle Feature eine eigene ID hat, bedeutet die Zustimmung zur Nutzung eines experimentellen Features nicht automatisch die Zustimmung zur Nutzung eines anderen.
Weitere Informationen finden Sie unter Experimentelle Features und den Artikel im C#-Leitfaden zu allgemeinen Attributen.
Leitfaden für Bibliotheksentwickler
Bibliotheksentwickler sollten in der Regel ausdrücken, dass eine API auf eine von zwei Arten in der Vorschau ist:
- Für neue APIs, die in einer Vorabversion Ihres Pakets eingeführt wurden, müssen Sie nichts tun. Das Paket drückt bereits die Vorschauqualität aus.
- Wenn Sie ein stabiles Paket versenden möchten, das einige Vorschauqualitäts-APIs enthält, sollten Sie diese APIs mit
[Experimental]kennzeichnen. Stellen Sie sicher, dass Sie Ihre eigene Diagnose-ID verwenden, und geben Sie sie speziell für diese Features an. Wenn Sie über mehrere unabhängige Features verfügen, sollten Sie mehrere IDs verwenden.
Das attribut [RequiresPreviewFeatures] ist nur für Komponenten der .NET-Plattform selbst gedacht. Auch dort wird es nur für APIs verwendet, die Laufzeit- und Sprachvorschaufeatures erfordern. Wenn es sich nur um eine API handelt, die sich in der Vorschau befindet, verwendet die .NET-Plattform das attribut [Experimental].
Die Ausnahme dieser Regel ist, wenn Sie eine stabile Bibliothek erstellen und bestimmte Features verfügbar machen möchten, die wiederum von Laufzeit- oder Sprachvorschauverhalten abhängig sind. In diesem Fall sollten Sie [RequiresPreviewFeatures] für die Einstiegspunkte dieses Features verwenden. Sie müssen jedoch berücksichtigen, dass Benutzer solcher APIs auch Vorschaufunktionen aktivieren müssen, was sie allen Laufzeit-, Bibliotheks- und Sprachvorschauverhaltensweisen aussetzt.
