通过

预览 API

  • 项目

.NET 平台认真对待兼容性。 因此，库生态系统倾向于避免进行重大更改，尤其是在 API 方面。

尽管如此，在设计 API 时，必须能够收集用户的反馈，并在必要时根据该反馈对 API 进行更改。 为了避免意外，应了解你使用的 API 被视为稳定，哪些 API 仍在积极开发中，可能会更改。

API 可以通过多种方式来表示它采用预览形式：

本文介绍每个选项的工作原理，以及库开发人员如何在这些选项之间进行选择。

.NET 运行时预览版

除了具有实时许可证的候选版本（RCs），不支持 .NET 运行时和 SDK 的预览版本。

因此，根据预览版收到的反馈，作为 .NET 预览版的一部分添加的任何 API 都被视为可能会更改。 若要使用 .NET 运行时预览版，需要在项目中显式定位较新的框架版本。 这样做后，你隐式表示同意使用可能会更改的 API。

预发行版 NuGet 软件包

NuGet 包可以是稳定版本，也可以是预发行版。 预发行版包在其版本上使用预发行版后缀进行标记。 例如，System.Text.Json 9.0.0-preview.2.24128.5 具有预发行版后缀 preview.2.24128.5。

预发布包通常用于收集早期采用者的反馈。 作者通常不支持它们。

通过 CLI 或 UI 安装包时，必须显式指示是否要安装预发行版版本。 这样做后，你隐式表示同意使用可能会更改的 API。

RequiresPreviewFeaturesAttribute

RequiresPreviewFeaturesAttribute 属性用于需要跨堆栈的预览行为的 API，包括运行时、C# 编译器和库。 使用标有此属性的 API 时，除非项目文件包含属性 <EnablePreviewFeatures>true</EnablePreviewFeatures>，否则会收到生成错误。 将该属性设置为 true 还会设置 <LangVersion>Preview</LangVersion>，从而允许使用预览语言功能。

例如，在 .NET 6 中，泛型数学 库被标记为 RequiresPreviewFeaturesAttribute，因为它需要当时处于预览状态的静态接口成员。

ExperimentalAttribute

.NET 8 添加了 ExperimentalAttribute，它不需要任何运行时或语言预览功能，并且只是指示给定 API 尚不稳定。

在使用实验性 API 进行构建时，编译器会报错。 标记为实验的每个功能都有自己的单独的诊断 ID。 若要表示同意使用实验 API，请取消特定诊断。 可以通过任何抑制诊断的方法执行此操作，但建议的方法是将诊断添加到项目的 <NoWarn> 属性。

由于每个实验功能都有单独的 ID，因此同意使用一个实验性功能并不同意使用另一个功能。

有关详细信息，请参阅 实验功能，以及有关 常规属性的 C# 指南中的文章。

库开发人员指南

库开发人员通常应以以下两种方式之一表示 API 处于预览状态：

  • 对于在包的预发行版中引入的新 API，无需执行任何操作；包已经表示了预览质量。
  • 如果要交付包含某些预览质量 API 的稳定包，则应使用 [Experimental]标记这些 API。 请确保使用自己的诊断 ID，并使其专用于这些功能。 如果你有多个独立功能，请考虑使用多个 ID。

[RequiresPreviewFeatures] 属性仅适用于 .NET 平台本身的组件。 即便如此，它也仅用于需要运行时和语言预览功能的 API。 如果这只是预览版 API，则 .NET 平台使用 [Experimental] 属性。

此规则的例外情况是，如果要构建稳定的库，并且想要公开某些功能，而这些功能又依赖于运行时或语言预览行为。 在这种情况下，应为该功能的入口点使用 [RequiresPreviewFeatures]。 但是，需要考虑到此类 API 的用户也必须启用预览功能，这些功能会向所有运行时、库和语言预览行为公开。