Vorschau-APIs

Die .NET-Plattform ist stolz darauf, Kompatibilität ernst zu nehmen. Daher werden im Bibliotheksökosystem vor allem im Hinblick auf die API Breaking Changes möglichts vermieden.

Dennoch ist es beim Entwerfen von APIs wichtig, Feedback von Benutzern zu sammeln und die API basierend auf diesem Feedback bei Bedarf zu ändern. Um Überraschungen zu vermeiden, ist es wichtig, dass Benutzer verstehen, welche APIs als stabil betrachtet werden und welche noch in der aktiven Entwicklung sind und sich ändern können.

Es gibt mehrere Möglichkeiten, wie für eine API angegeben werden kann, dass sie sich in der Vorschauphase befindet:

• Die gesamte Komponente wird als Vorschau betrachtet:

  • In einer Vorschauversion von .NET Runtime verfügbar gemacht
  • In einer Vorabversion eines NuGet-Pakets verfügbar gemacht

• Eine andernfalls stabile Komponente kennzeichnet bestimmte APIs als Vorschau:

  • Gekennzeichnet mit RequiresPreviewFeaturesAttribute
  • Gekennzeichnet mit ExperimentalAttribute

In diesem Artikel wird erläutert, wie Sie zwischen diesen Optionen wählen, und Sie erhalten weitere Informationen zur Funktionsweise.

Vorschauversionen von .NET Runtime

Mit Ausnahme von Release Candidates (RCs) mit einer Aktivierungslizenz werden Vorschauversionen von .NET Runtime und des SDK nicht unterstützt.

Daher werden alle APIs, die als Teil einer .NET-Vorschau hinzugefügt werden, basierend auf dem Feedback für die Vorschau als veränderbar betrachtet. Um eine .NET Runtime-Vorschau zu verwenden, müssen Sie explizit auf eine neuere Framework-Version abzielen. Auf diese Weise erklären Sie sich implizit mit der Nutzung von APIs einverstanden, die sich noch ändern können.

Vorabversion von NuGet-Paketen

NuGet-Pakete können entweder als stabil oder als Vorabversion gekennzeichnet sein, d. h. das Paket hat ein Suffix für eine Vorabversion. System.Text.Json 9.0.0-preview.2.24128.5 hat beispielsweise das Vorabversionssuffix preview.2.24128.5.

Paketautoren unterstützen im Allgemeinen keine Vorabversionspakete und verwenden sie dafür, Feedback von Early Adoptern zu sammeln.

Bei der Installation von Paketen über die CLI oder die Benutzeroberfläche müssen Sie im Allgemeinen explizit angeben, ob Sie Vorabversionen installieren möchten, womit Sie wiederum implizit Ihr Einverständnis zur Verwendung von APIs ausdrücken, die sich möglicherweise ändern.

RequiresPreviewFeaturesAttribute

Seit .NET 6 enthält die Plattform das Attribut RequiresPreviewFeaturesAttribute.

Dieses Attribut wird für APIs verwendet, die Vorschauverhalten für den gesamten Stapel erfordern, einschließlich Laufzeit, C#-Compiler und Bibliotheken. Wenn Sie APIs verwenden, die mit diesem Attribut gekennzeichnet sind, erhalten Sie einen Buildfehler, es sei denn, Ihr Projekt legt <EnablePreviewFeatures>true</EnablePreviewFeatures> fest. Wenn Sie diese Eigenschaft auf true festlegen, wird auch <LangVersion>Preview</LangVersion> festgelegt, sodass Vorschausprachfeatures verwendet werden können.

Das .NET-Team hat das Attribut RequiresPreviewFeaturesAttribute in .NET 6 verwendet, um generische Mathematik zu testen, da es statische Schnittstellenmember erforderte, die sich zu der Zeit in der Vorschau befanden.

ExperimentalAttribute

In .NET 8 wurde ExperimentalAttribute hinzugefügt. Dafür sind keine Laufzeit- oder Sprachvorschaufeatures erforderlich, und es wird einfach angegeben, dass eine bestimmte API noch nicht stabil ist.

Beim Erstellen mit einer experimentellen API generiert der Compiler einen Fehler. Jedes Feature, das als experimentell gekennzeichnet ist, verfügt über eine eigene separate Diagnose-ID. Um Ihre Zustimmung zur Verwendung zu geben, unterdrücken Sie die spezifische Diagnose. Dazu können Sie eine der Methoden zum Unterdrücken der Diagnose verwenden. Es wird jedoch empfohlen, die Diagnose zur <NoWarn>-Eigenschaft des Projekts hinzuzufügen.

Da jedes experimentelle Feature über eine separate ID verfügt, bedeutet die Zustimmung zur Nutzung einer experimentellen Funktion nicht die Zustimmung zur Nutzung einer anderen.

Weitere Informationen finden Sie unter Experimentelle Features.

Wählen zwischen den Optionen

Bibliotheksentwickler sollten nur Vorabversionen von NuGet-Paketen verwenden oder APIs mit [Experimental] markieren:

• 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 zur Verfügung stellen möchten, das einige APIs mit Vorschauqualität enthält, sollten Sie diese APIs mit [Experimental] kennzeichnen. Verwenden Sie unbedingt Ihre eigene Diagnose-ID, und legen Sie sie als spezifisch für diese Features fest. Wenn Sie über mehrere unabhängige Features verfügen, sollten Sie ggf. mehrere IDs verwenden.

Das Attribut [RequiresPreviewFeatures] ist nur für Komponenten der .NET-Plattform selbst gedacht. Und 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 vom 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 Vorschaufeatures aktivieren müssen. Dadurch werden sie für das gesamte Laufzeit-, Bibliotheks- und Sprachvorschauverhalten verfügbar gemacht.