CA2252: Opt in to preview features before using them

Artikkeli
09/05/2023

Property	Value
Rule ID	CA2252
Title	Opt in to preview features before using them
Category	Usage
Fix is breaking or non-breaking	Non-breaking
Enabled by default in .NET 9	As error

Cause

A client uses preview APIs or types in their assembly without explicitly opting in either locally or at the module or assembly level.

Rule description

When an API or assembly that's decorated with the RequiresPreviewFeaturesAttribute attribute is consumed, this rule checks if the call site has opted in to preview features. A call site has opted in to preview features if one of the following applies:

It is within the scope of a RequiresPreviewFeaturesAttribute annotation.
It is part of an assembly or module that has already opted in to preview features.

The following image shows an example of the CA2252 diagnostic.

Here, Lib is a preview type that's constructed in the Main method. Main itself is not annotated as a preview method, so diagnostics are produced on the two constructors calls inside Main.

How to fix violations

There are two ways to fix violations:

Bring a call site within the scope of an annotation by annotating its parent with RequiresPreviewFeaturesAttribute. In the previous example, APreviewMethod is annotated with the RequiresPreviewFeatures attribute, so the analyzer ignores preview type usage inside APreviewMethod. It follows that callers of APreviewMethod will have to perform a similar exercise.
You can also opt in to preview features at an assembly or module level. This indicates to the analyzer that preview type usage in the assembly is desired and, as a consequence, no errors will be produced by this rule. This is the preferred way to consume preview dependencies. To enable preview features inside the entire assembly, set the EnablePreviewFeatures property in a .csproj file:

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

When to suppress warnings

Suppressing warnings from this rule is only recommended for advanced use cases where diagnostics on APIs need to be explicitly disabled. In this case, you must be willing to take on the responsibility of marking preview APIs appropriately. For example, consider a case where an existing type implements a new preview interface. Since the entire type cannot be marked as preview (for backwards compatibility), the diagnostic around the type definition can be disabled locally. Further, you need to mark the preview interface implementations as preview. Now, the existing type can be used as before, but calls to the new interface methods will get diagnostics. System.Private.CoreLib.csproj uses this technique to expose generic math features on numeric types such as Int32, Double, and Decimal.

The following images show how to disable the CA2252 analyzer locally.

Note

You might see false positive warnings from this rule if all of the following apply:

You're using Visual Studio 2022 version 17.5 or later with an older version of the .NET SDK, that is, .NET 6 or earlier.
You're using the analyzers from the .NET 6 SDK or an older version of the analyzer packages, such as Microsoft.CodeAnalysis.FxCopAnalyzers.

In this case, it's safe to suppress a false positive warning. The false positives are due to a breaking change in the C# compiler. Consider using a newer analyzer that contains the fix for the false positive warnings. Upgrade to Microsoft.CodeAnalysis.NetAnalyzers version 7.0.0-preview1.22464.1 or newer or use the analyzers from the .NET 7 SDK.

Suppress a warning

If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.

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

To disable the rule for a file, folder, or project, set its severity to none in the configuration file.

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

To disable this entire category of rules, set the severity for the category to none in the configuration file.

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

For more information, see How to suppress code analysis warnings.

Jaa