diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2250.md b/docs/fundamentals/code-analysis/quality-rules/ca2250.md new file mode 100644 index 0000000000000..dbceed3e8a9c3 --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/ca2250.md @@ -0,0 +1,95 @@ +--- +title: "CA2250: Use `ThrowIfCancellationRequested`" +description: "Learn about code analysis rule CA2250: Use `ThrowIfCancellationRequested`" +ms.date: 05/21/2021 +ms.topic: reference +f1_keywords: +- CA2250 +- UseCancellationTokenThrowIfCancellationRequested +helpviewer_keywords: +- UseCancellationTokenThrowIfCancellationRequested +- CA2250 +author: NewellClark +dev_langs: +- CSharp +- VB +--- +# CA2250: Use `ThrowIfCancellationRequested` + +| | Value | +|-|-| +| **Rule ID** |CA2250| +| **Category** |[Usage](usage-warnings.md)| +| **Fix is breaking or non-breaking** |Non-breaking| + +## Cause + +This rule flags conditional statements that check before throwing . + +## Rule description + +You can accomplish the same thing by calling . + +## How to fix violations + +To fix violations, replace the conditional statement with a call to . + +```csharp +using System; +using System.Threading; + +public void MySlowMethod(CancellationToken token) +{ + // Violation + if (token.IsCancellationRequested) + throw new OperationCanceledException(); + + // Fix + token.ThrowIfCancellationRequested(); + + // Violation + if (token.IsCancellationRequested) + throw new OperationCanceledException(); + else + DoSomethingElse(); + + // Fix + token.ThrowIfCancellationRequested(); + DoSomethingElse(); +} +``` + +```vb +Imports System +Imports System.Threading + +Public Sub MySlowMethod(token As CancellationToken) + + ' Violation + If token.IsCancellationRequested Then + Throw New OperationCanceledException() + End If + + ' Fix + token.ThrowIfCancellationRequested() + + ' Violation + If token.IsCancellationRequested Then + Throw New OperationCanceledException() + Else + DoSomethingElse() + End If + + ' Fix + token.ThrowIfCancellationRequested() + DoSomethingElse() +End Sub +``` + +## When to suppress warnings + +It is safe to suppress warnings from this rule. + +## See also + +- [Usage Warnings](usage-warnings.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/index.md b/docs/fundamentals/code-analysis/quality-rules/index.md index 304884b47c730..4aaffa9e78442 100644 --- a/docs/fundamentals/code-analysis/quality-rules/index.md +++ b/docs/fundamentals/code-analysis/quality-rules/index.md @@ -177,6 +177,7 @@ The following table lists code quality analysis rules. > | [CA2247: Argument passed to TaskCompletionSource constructor should be TaskCreationOptions enum instead of TaskContinuationOptions enum.](ca2247.md) | TaskCompletionSource has constructors that take TaskCreationOptions that control the underlying Task, and constructors that take object state that's stored in the task. Accidentally passing a TaskContinuationOptions instead of a TaskCreationOptions will result in the call treating the options as state. | > | [CA2248: Provide correct enum argument to Enum.HasFlag](ca2248.md) | The enum type passed as an argument to the `HasFlag` method call is different from the calling enum type. | > | [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. | > | [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/usage-warnings.md b/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md index 807cfba035a14..dae64fc3a3ff1 100644 --- a/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md @@ -52,3 +52,4 @@ Usage rules support proper usage of .NET. |[CA2247: Argument passed to TaskCompletionSource constructor should be TaskCreationOptions enum instead of TaskContinuationOptions enum](ca2247.md)|TaskCompletionSource has constructors that take TaskCreationOptions that control the underlying Task, and constructors that take object state that's stored in the task. Accidentally passing a TaskContinuationOptions instead of a TaskCreationOptions will result in the call treating the options as state.| |[CA2248: Provide correct 'enum' argument to 'Enum.HasFlag'](ca2248.md)|The enum type passed as an argument to the `HasFlag` method call is different from the calling enum type.| |[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.| diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index c526dc191182a..aadecb7cd8a78 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -1182,6 +1182,8 @@ items: href: code-analysis/quality-rules/ca2248.md - name: CA2249 href: code-analysis/quality-rules/ca2249.md + - name: CA2250 + href: code-analysis/quality-rules/ca2250.md - name: Code style rules items: - name: Overview