diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index a3200c8563957..aaac9cd07b40c 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -453,6 +453,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 attribute, which would require any consumers to [enable preview features](#enablepreviewfeatures), set this property to `False`. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2252.md b/docs/fundamentals/code-analysis/quality-rules/ca2252.md new file mode 100644 index 0000000000000..5386ef6768a61 --- /dev/null +++ b/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 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 + + true + +``` + +## 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) diff --git a/docs/fundamentals/code-analysis/quality-rules/index.md b/docs/fundamentals/code-analysis/quality-rules/index.md index 5a1142641450d..769f205b2b9f5 100644 --- a/docs/fundamentals/code-analysis/quality-rules/index.md +++ b/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. | diff --git a/docs/fundamentals/code-analysis/quality-rules/media/ca2252-advanced-1.png b/docs/fundamentals/code-analysis/quality-rules/media/ca2252-advanced-1.png new file mode 100644 index 0000000000000..e1865795ed6be Binary files /dev/null and b/docs/fundamentals/code-analysis/quality-rules/media/ca2252-advanced-1.png differ diff --git a/docs/fundamentals/code-analysis/quality-rules/media/ca2252-advanced-2.png b/docs/fundamentals/code-analysis/quality-rules/media/ca2252-advanced-2.png new file mode 100644 index 0000000000000..5c1046b7929a8 Binary files /dev/null and b/docs/fundamentals/code-analysis/quality-rules/media/ca2252-advanced-2.png differ diff --git a/docs/fundamentals/code-analysis/quality-rules/media/ca2252-basic.png b/docs/fundamentals/code-analysis/quality-rules/media/ca2252-basic.png new file mode 100644 index 0000000000000..e7543a164a575 Binary files /dev/null and b/docs/fundamentals/code-analysis/quality-rules/media/ca2252-basic.png differ diff --git a/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md b/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md index 694bfc598b07d..3d65ed08ce7dd 100644 --- a/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md @@ -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.| diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index abc19c3336304..ac9b6fc98e202 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -1282,6 +1282,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