CA2252：选择预览功能后再使用它们

属性	值
规则 ID	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 使用此技术公开数字类型（例如 Int32、Double 和 Decimal）的通用数学功能。

下图显示了如何在本地禁用 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

有关详细信息，请参阅如何禁止显示代码分析警告。

另请参阅

• EnablePreviewFeatures 和 GenerateRequiresPreviewFeaturesAttribute
• 预览功能设计文档