Ca2250

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 <xref:System.Threading.CancellationToken.IsCancellationRequested> before throwing <xref:System.OperationCanceledException>.
+
+## Rule description
+
+You can accomplish the same thing by calling <xref:System.Threading.CancellationToken.ThrowIfCancellationRequested?displayProperty=nameWithType>.
+
+## How to fix violations
+
+To fix violations, replace the conditional statement with a call to <xref:System.Threading.CancellationToken.ThrowIfCancellationRequested>.
+
+```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)

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. |

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.|

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