Docs for CA2252 (#26149)

Author: Prashanth Govindarajan

docs/core/project-sdk/msbuild-props.md

@@ -375,6 +375,8 @@ When a project contains this property set to `True`, the following assembly-leve
 
 An analyzer warns if this attribute is present on dependencies for projects where `EnablePreviewFeatures` is not set to `True`.
 
+Library authors who intend to ship preview assemblies should set this property to `True`. If an assembly needs to ship with a mixture of preview and non-preview APIs, see the [GenerateRequiresPreviewFeaturesAttribute](#generaterequirespreviewfeaturesattribute) section below.
+
 ### GenerateRequiresPreviewFeaturesAttribute
 
 The `GenerateRequiresPreviewFeaturesAttribute` property is closely related to the [EnablePreviewFeatures](#enablepreviewfeatures) property. If your library uses preview features but you don't want the entire assembly to be marked with the <xref:System.Runtime.Versioning.RequiresPreviewFeaturesAttribute> attribute, which would require any consumers to [enable preview features](#enablepreviewfeatures), set this property to `False`.

docs/fundamentals/code-analysis/quality-rules/ca2252.md

@@ -0,0 +1,68 @@
+---
+title: "CA2252: Opt in to preview features"
+description: "Learn about the code analyzer that scans for preview API usage and produces a build error if an assembly has not opted in to preview features."
+ms.date: 09/14/2021
+ms.topic: reference
+f1_keywords:
+- CA2252
+- DetectPreviewFeaturesAnalyzer
+helpviewer_keywords:
+- DetectPreviewFeaturesAnalyzer
+- CA2252
+author: pgovind
+ms.author: prgovi
+dev_langs:
+- CSharp
+---
+# CA2252: Opt in to preview features before using them
+
+| | Value |
+|-|-|
+| **Rule ID** |CA2252|
+| **Category** |[Microsoft.Usage](usage-warnings.md)|
+| **Fix is breaking or non-breaking** |Non-breaking|
+
+## 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 <xref:System.Runtime.Versioning.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.
+
+> ![Code editor with CA2252 warning.](media/ca2252-basic.png)
+
+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](../../../core/project-sdk/msbuild-props.md#enablepreviewfeatures) property in a `.csproj` file:
+
+```csharp
+  <PropertyGroup>
+    <EnablePreviewFeatures>true</EnablePreviewFeatures>
+  </PropertyGroup>
+```
+
+## When to suppress errors
+
+Suppressing errors from this rule is only recommended for advanced use cases where diagnostics on APIs need to 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.  
+
+> ![CA2252 - Suppress Detect Preview Feature Diagnostic](media/ca2252-advanced-1.png)
+
+> ![CA2252 - Mark Interface Implementations Explicitly](media/ca2252-advanced-2.png)
+
+## See also
+
+- [EnablePreviewFeatures and GenerateRequiresPreviewFeaturesAttribute](../../../core/project-sdk/msbuild-props.md#enablepreviewfeatures)
+- [Preview feature design document](https://github.com/dotnet/designs/blob/main/accepted/2021/preview-features/preview-features.md)

docs/fundamentals/code-analysis/quality-rules/index.md

@@ -184,6 +184,7 @@ The following table lists code quality analysis rules.
 > | [CA2249: Consider using String.Contains instead of String.IndexOf](ca2249.md) | Calls to `string.IndexOf` where the result is used to check for the presence/absence of a substring can be replaced by `string.Contains`. |
 > | [CA2250: Use `ThrowIfCancellationRequested`](ca2250.md) | `ThrowIfCancellationRequested` automatically checks whether the token has been canceled, and throws an `OperationCanceledException` if it has. |
 > | [CA2251: Use `String.Equals` over `String.Compare`](ca2251.md) | It is both clearer and likely faster to use `String.Equals` instead of comparing the result of `String.Compare` to zero. |
+> | [CA2252: Opt in to preview features](ca2252.md) | Opt in to preview features before using preview APIs. |
 > | [CA2300: Do not use insecure deserializer BinaryFormatter](ca2300.md) | Insecure deserializers are vulnerable when deserializing untrusted data. An attacker could modify the serialized data to include unexpected types to inject objects with malicious side effects. |
 > | [CA2301: Do not call BinaryFormatter.Deserialize without first setting BinaryFormatter.Binder](ca2301.md) | Insecure deserializers are vulnerable when deserializing untrusted data. An attacker could modify the serialized data to include unexpected types to inject objects with malicious side effects. |
 > | [CA2302: Ensure BinaryFormatter.Binder is set before calling BinaryFormatter.Deserialize](ca2302.md) | Insecure deserializers are vulnerable when deserializing untrusted data. An attacker could modify the serialized data to include unexpected types to inject objects with malicious side effects. |

docs/fundamentals/code-analysis/quality-rules/media/ca2252-advanced-1.png

@@ -54,3 +54,4 @@ Usage rules support proper usage of .NET.
 |[CA2249: Consider using String.Contains instead of String.IndexOf](ca2249.md)|Calls to `string.IndexOf` where the result is used to check for the presence or absence of a substring can be replaced by `string.Contains`.|
 |[CA2250: Use `ThrowIfCancellationRequested`](ca2250.md) | `ThrowIfCancellationRequested` automatically checks whether the token has been canceled, and throws an `OperationCanceledException` if it has.|
 |[CA2251: Use `String.Equals` over `String.Compare`](ca2251.md)|It is both clearer and likely faster to use `String.Equals` instead of comparing the result of `String.Compare` to zero.|
+|[CA2252: Opt in to preview features](ca2252.md)|Opt in to preview features before using preview APIs.|

docs/fundamentals/code-analysis/quality-rules/media/ca2252-advanced-2.png

@@ -1285,6 +1285,8 @@ items:
             href: code-analysis/quality-rules/ca2250.md
           - name: CA2251
             href: code-analysis/quality-rules/ca2251.md
+          - name: CA2252
+            href: code-analysis/quality-rules/ca2252.md
       - name: Code style rules
         items:
         - name: Overview