預覽 API

  • 發行項

.NET 平台以認真對待相容性而自豪。 因此，程式庫生態系統通常會避免進行中斷性變更，尤其是 API 方面。

儘管如此，在設計 API 時，收集使用者的意見反應並在必要時根據該意見反應變更 API 非常重要。 為了避免意外，使用者必須了解哪些 API 被認為是穩定的，哪些 API 仍在積極開發中並且可能會變更。

API 可以透過多種方式以預覽形式表示：

  • 整個元件會被視為預覽：

    • 在 .NET 執行階段的預覽版本中公開
    • 在發行前版本的 NuGet 套件中公開

  • 在其他方面穩定的元件會專門將某些 API 標示為預覽：

本文說明如何在這些選項之間進行選擇，以及每個選項的運作方式。

.NET 執行階段預覽

除了具有上線授權的候選版 (RC) 之外，不支援 .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

從 .NET 6 開始，該平台包含 RequiresPreviewFeaturesAttribute 屬性。

此屬性會用於需要跨堆疊預覽行為的 API，包括執行階段、C# 編譯器和程式庫。 當您使用以此屬性標示的 API 時，您將收到建置錯誤，除非您的專案設定了 <EnablePreviewFeatures>true</EnablePreviewFeatures>。 將該屬性設為 true 也會設定 <LangVersion>Preview</LangVersion>，以允許使用預覽語言功能。

.NET 小組使用 .NET 6 中的 RequiresPreviewFeaturesAttribute 屬性來測試通用數學，因為它需要靜態介面成員，而這些成員當時處於預覽狀態。

ExperimentalAttribute

.NET 8 已新增 ExperimentalAttribute，它不需要任何執行階段或語言預覽功能，而且只會指出指定的 API 尚未穩定。

針對實驗 API 進行建置時，編譯器會產生錯誤。 標示為實驗性的每個功能都有自己的個別診斷識別碼。 若要表示同意使用它們，您可以隱藏特定的診斷。 您可以透過任何隱藏診斷的方法來執行此動作，但建議的方法是將診斷新增至專案的 <NoWarn> 屬性。

由於每個實驗性功能都有個別的識別碼，因此同意使用一個實驗性功能並不表示同意使用另一個實驗性功能。

在選項之間進行選擇

程式庫開發人員應該只使用發行前版本的 NuGet 套件，或使用 [Experimental] 標記 API：

  • 對於套件的發行前版本中引入的新 API，您不需要執行任何動作；該套件已經表示預覽品質。

  • 如果您想要發佈包含一些預覽品質 API 的穩定套件，您應該使用 [Experimental] 標記這些 API。 確保使用您自己的診斷識別碼並使其專屬於這些功能。 如果您有多個獨立功能，請考慮使用多個識別碼。

[RequiresPreviewFeatures] 屬性僅適用於 .NET 平台本身的元件。 甚至它只用於需要執行階段和語言預覽功能的 API。 如果它只是預覽版的 API，則 .NET 平台會使用 [Experimental] 屬性。

此規則的例外情況是，如果您正在建立穩定的程式庫且想要公開某些功能，而這些功能又相依於執行階段或語言預覽行為的情況。 在此情況下，您應該使用 [RequiresPreviewFeatures] 作為該功能的入口點。 不過，您需要考慮到此類 API 的使用者也必須開啟預覽功能，這會將其公開給所有執行階段、程式庫和語言預覽行為。