預覽 API

發行項
01/29/2025

.NET 平台會認真對待相容性。因此，程式庫生態系統通常會避免進行破壞性更改，特別是在 API 方面。

不過，在設計 API 時，請務必能夠收集使用者的意見反應，並視需要根據該意見反應對 API 進行變更。為了避免意外，您應該瞭解您使用的 API 會被視為穩定，以及哪些 API 仍在使用中開發中，而且可能會變更。

API 有多種方式可以表示其為預覽格式：

如果元件公開，則整個元件會被視為預覽：
- 在 .NET 執行環境的預覽版本中。
- 在發行前版本 NuGet 套件中。
否則穩定的元件會使用下列屬性將特定 API 標示為預覽：
- RequiresPreviewFeaturesAttribute
- ExperimentalAttribute

本文說明每個選項的運作方式，以及針對連結庫開發人員，如何在這些選項之間進行選擇。

.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`

RequiresPreviewFeaturesAttribute 屬性用於需要跨各層預覽行為的 API，包括執行時間、C# 編譯器和程式庫。當您取用這個屬性標示的 API 時，除非專案檔包含屬性 <EnablePreviewFeatures>true</EnablePreviewFeatures>，否則會收到建置錯誤。將此屬性設定為 true 也會設定 <LangVersion>Preview</LangVersion>，以允許使用預覽語言功能。

例如，在 .NET 6 中，泛型數學 連結庫標示為 RequiresPreviewFeaturesAttribute，因為它需要當時處於預覽狀態的靜態介面成員。

`ExperimentalAttribute`

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

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

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

如需詳細資訊，請參閱實驗性功能和 C# 指南中的文章，一般屬性。

程式庫開發人員的指引

連結庫開發人員通常應該以下列兩種方式之一來表示 API 處於預覽狀態：

針對 發行前版本 套件中引進的新 API，您不需要執行任何動作;套件已經表示預覽品質。
如果您想要寄送包含某些預覽品質 API 的穩定套件，您應該使用 [Experimental]標記這些 API。請務必使用您自己的診斷標識碼，並使其專屬於這些功能。如果您有多個獨立功能，請考慮使用多個標識符。

[RequiresPreviewFeatures] 屬性僅適用於 .NET 平臺本身的元件。即便如此，它也只會用於需要運行時間和語言預覽功能的 API。如果這隻是處於預覽狀態的 API，.NET 平臺會使用 [Experimental] 屬性。

此規則的例外是，如果您正在建置穩定的程式庫，並希望暴露某些特定功能，而這些功能則依賴於運行時間或語言預覽行為。在這種情況下，您應該使用 [RequiresPreviewFeatures] 作為該功能的進入點。不過，您必須考慮這類 API 的使用者也必須啟用預覽功能，這樣會讓他們暴露在所有運行時、庫和語言的預覽行為中。

共用方式為