CA2252：加入宣告預覽功能，再使用這些功能
| 屬性 | 值 |
|---|---|
| 規則識別碼 | CA2252 |
| 標題 | 加入宣告預覽功能，再使用這些功能 |
| 類別 | 使用方式 |
| 修正程式是中斷或非中斷 | 不中斷 |
| 預設在 .NET 8 中啟用 | 錯誤 |
原因
用戶端在其元件中使用預覽 API 或類型，而不需在本機或模組或元件層級明確選擇。
檔案描述
使用屬性 RequiresPreviewFeaturesAttribute 裝飾的 API 或元件時，此規則會檢查呼叫網站是否已選擇預覽功能。 如果適用下列其中一項，通話網站已選擇預覽功能：
- 它位於批註的範圍內
RequiresPreviewFeaturesAttribute。 - 它是已加入宣告預覽功能的元件或模組的一部分。
下圖顯示 CA2252 診斷的範例。
Lib以下是在 方法中建構的 Main 預覽類型。 Main 本身不會標注為預覽方法，因此會在 內部 Main 的兩個建構函式呼叫上產生診斷。
如何修正違規
有兩種方式可以修正違規：
使用 標注其父
RequiresPreviewFeaturesAttribute代，將呼叫網站帶入批註範圍內。 在上一個範例中，APreviewMethod會加上RequiresPreviewFeatures屬性的批註，因此分析器會忽略 內部的APreviewMethod預覽類型使用方式。 接著，的APreviewMethod呼叫者必須執行類似的練習。您也可以選擇在元件或模組層級預覽功能。 這向分析器指出，想要預覽元件中的類型使用方式，因此，此規則不會產生任何錯誤。 這是取用預覽相依性的慣用方式。 若要啟用整個元件內的預覽功能，請在檔案中
.csproj設定 EnablePreviewFeatures 屬性：
<PropertyGroup>
<EnablePreviewFeatures>true</EnablePreviewFeatures>
</PropertyGroup>
隱藏警告的時機
只有在需要明確停用 API 診斷的進階使用案例中，才建議隱藏此規則的警告。 在此情況下，您必須願意承擔適當地標記預覽 API 的責任。 例如，假設現有類型實作新的預覽介面。 由於整個類型無法標示為預覽版（為了回溯相容性），因此可以在本機停用類型定義周圍的診斷。 此外，您必須將預覽介面實作標示為預覽。 現在，現有的類型可以像以前一樣使用，但對新介面方法的呼叫會取得診斷。 System.Private.CoreLib.csproj 會使用這項技術，在 、 和 Decimal 等 Int32Double 數數值型別上公開泛型數學特徵。
下列影像顯示如何在本機停用 CA2252 分析器。
注意
如果適用下列所有專案，您可能會看到來自此規則的誤判警告：
- 您使用 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
如需詳細資訊，請參閱 如何隱藏程式碼分析警告 。
