CA2252:加入宣告預覽功能,再使用這些功能

屬性
規則識別碼 CA2252
標題 加入宣告預覽功能,再使用這些功能
類別 使用方式
修正程式是中斷或非中斷 不中斷
預設在 .NET 8 中啟用 錯誤

原因

用戶端在其元件中使用預覽 API 或類型,而不需在本機或模組或元件層級明確選擇。

檔案描述

使用屬性 RequiresPreviewFeaturesAttribute 裝飾的 API 或元件時,此規則會檢查呼叫網站是否已選擇預覽功能。 如果適用下列其中一項,通話網站已選擇預覽功能:

  • 它位於批註的範圍內 RequiresPreviewFeaturesAttribute
  • 它是已加入宣告預覽功能的元件或模組的一部分。

下圖顯示 CA2252 診斷的範例。

Code editor with CA2252 warning.

Lib以下是在 方法中建構的 Main 預覽類型。 Main 本身不會標注為預覽方法,因此會在 內部 Main 的兩個建構函式呼叫上產生診斷。

如何修正違規

有兩種方式可以修正違規:

  • 使用 標注其父 RequiresPreviewFeaturesAttribute 代,將呼叫網站帶入批註範圍內。 在上一個範例中, APreviewMethod 會加上 RequiresPreviewFeatures 屬性的批註,因此分析器會忽略 內部的 APreviewMethod 預覽類型使用方式。 接著,的 APreviewMethod 呼叫者必須執行類似的練習。

  • 您也可以選擇在元件或模組層級預覽功能。 這向分析器指出,想要預覽元件中的類型使用方式,因此,此規則不會產生任何錯誤。 這是取用預覽相依性的慣用方式。 若要啟用整個元件內的預覽功能,請在檔案中 .csproj 設定 EnablePreviewFeatures 屬性:

  <PropertyGroup>
    <EnablePreviewFeatures>true</EnablePreviewFeatures>
  </PropertyGroup>

隱藏警告的時機

只有在需要明確停用 API 診斷的進階使用案例中,才建議隱藏此規則的警告。 在此情況下,您必須願意承擔適當地標記預覽 API 的責任。 例如,假設現有類型實作新的預覽介面。 由於整個類型無法標示為預覽版(為了回溯相容性),因此可以在本機停用類型定義周圍的診斷。 此外,您必須將預覽介面實作標示為預覽。 現在,現有的類型可以像以前一樣使用,但對新介面方法的呼叫會取得診斷。 System.Private.CoreLib.csproj 會使用這項技術,在 、 和 DecimalInt32Double 數數值型別上公開泛型數學特徵。

下列影像顯示如何在本機停用 CA2252 分析器。

CA2252 - Suppress Detect Preview Feature Diagnostic

CA2252 - Mark Interface Implementations Explicitly

注意

如果適用下列所有專案,您可能會看到來自此規則的誤判警告:

  • 您使用 Visual Studio 2022 17.5 版或更新版本搭配舊版 .NET SDK,也就是 .NET 6 或更早版本。
  • 您使用的是 .NET 6 SDK 或舊版分析器套件的分析器,例如 Microsoft.CodeAnalysis.FxCopAnalyzers。

在此情況下,可以放心地隱藏誤判警告。 誤判是由於 C# 編譯 程式中的重大變更所造成 。 請考慮使用包含誤判警告修正的較新分析器。 升級至 Microsoft.CodeAnalysis.NetAnalyzers 7.0.0-preview1.22464.1 版或更新版本,或使用 .NET 7 SDK 的分析器。

隱藏警告

如果您只想要隱藏單一違規,請將預處理器指示詞新增至原始程式檔以停用,然後重新啟用規則。

#pragma warning disable CA2252
// The code that's violating the rule is on this line.
#pragma warning restore CA2252

若要停用檔案、資料夾或專案的規則,請在組態檔 中將其嚴重性設定為 。 none

[*.{cs,vb}]
dotnet_diagnostic.CA2252.severity = none

若要停用此整個規則類別,請將組態檔中類別的嚴重性設定為 none

[*.{cs,vb}]
dotnet_analyzer_diagnostic.category-Usage.severity = none

如需詳細資訊,請參閱 如何隱藏程式碼分析警告

另請參閱