CA2025 Analyzer documentation (#46051)

Author: steveberdy

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

@@ -0,0 +1,82 @@
+---
+title: "CA2025: Do not pass 'IDisposable' instances into unawaited tasks"
+description: "Learn about code analysis rule CA2025 - Do not pass 'IDisposable' instances into unawaited tasks"
+ms.date: 05/08/2025
+ms.topic: reference
+f1_keywords:
+  - CA2025
+  - DoNotPassDisposablesIntoUnawaitedTasksAnalyzer
+helpviewer_keywords:
+  - CA2025
+author: steveberdy
+dev_langs:
+- CSharp
+---
+
+# CA2025: Do not pass 'IDisposable' instances into unawaited tasks
+
+| Property                            | Value                                                |
+|-------------------------------------|------------------------------------------------------|
+| **Rule ID**                         | CA2025                                               |
+| **Title**                           | Do not pass 'IDisposable' instances into unawaited tasks |
+| **Category**                        | [Reliability](reliability-warnings.md)               |
+| **Fix is breaking or non-breaking** | Non-breaking                                         |
+| **Enabled by default in .NET 10**   | As warning                                           |
+
+## Cause
+
+An `IDisposable` instance is passed into an unawaited task and potentially disposed before the task is finished using the instance.
+
+## Rule description
+
+Unawaited tasks that use `IDisposable` instances might use those instances long after they've been disposed. Ensure tasks using those instances are completed before the instances are disposed.
+
+## Examples
+
+The following code snippets (and their Visual Basic equivalents) are violations of CA2025:
+
+```csharp
+public Task DoSomethingAsync()
+{
+    // Using statements and using blocks can both be violations.
+    using (var disposable = new DisposableThing())
+    {
+        return DoSomethingInternalAsync(disposable);
+    }
+}
+```
+
+```csharp
+public async Task DoThingsAsync()
+{
+    var disposable = new DisposableThing();
+    var task = DoSomethingInternalAsync(disposable);
+    // More code here.
+    dispose.Dispose();
+    // It's a violation if arguments are disposed before the task is awaited.
+    await task.ConfigureAwait(false);
+}
+```
+
+## When to suppress warnings
+
+Suppress these warnings if you know tasks finish using `IDisposable` instances before they're disposed.
+
+## 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.
+
+```csharp
+#pragma warning disable CA2025
+// The code that's violating the rule is on this line.
+#pragma warning restore CA2025
+```
+
+To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md).
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.CA2025.severity = none
+```
+
+For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).

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

@@ -190,6 +190,7 @@ The following table lists code quality analysis rules.
 > | [CA2021: Don't call Enumerable.Cast\<T> or Enumerable.OfType\<T> with incompatible types](ca2021.md) | A call to <xref:System.Linq.Enumerable.Cast%60%601(System.Collections.IEnumerable)?displayProperty=nameWithType> or <xref:System.Linq.Enumerable.OfType%60%601(System.Collections.IEnumerable)?displayProperty=nameWithType> specifies a type parameter that's incompatible with the type of the input collection. |
 > | [CA2022: Avoid inexact read with Stream.Read](ca2022.md) | A call to `Stream.Read` might return fewer bytes than requested, resulting in unreliable code if the return value isn't checked. |
 > | [CA2024: Do not use StreamReader.EndOfStream in async methods](ca2024.md) | The property <xref:System.IO.StreamReader.EndOfStream?displayProperty=nameWithType> can cause unintended synchronous blocking when no data is buffered. Instead, use <xref:System.IO.StreamReader.ReadLineAsync?displayProperty=nameWithType> directly, which returns `null` when reaching the end of the stream. |
+> | [CA2025: Do not pass `IDisposable` instances into unawaited tasks](ca2025.md) | Unawaited tasks that use `IDisposable` instances might use those instances long after they have been disposed. Ensure tasks using those instances are completed before the instances are disposed. |
 > | [CA2100: Review SQL queries for security vulnerabilities](ca2100.md) | A method sets the System.Data.IDbCommand.CommandText property by using a string that is built from a string argument to the method. This rule assumes that the string argument contains user input. A SQL command string that is built from user input is vulnerable to SQL injection attacks. |
 > | [CA2101: Specify marshalling for P/Invoke string arguments](ca2101.md) | A platform invoke member allows partially trusted callers, has a string parameter, and does not explicitly marshal the string. This can cause a potential security vulnerability. |
 > | [CA2109: Review visible event handlers](ca2109.md) | A public or protected event-handling method was detected. Event-handling methods should not be exposed unless absolutely necessary. |

docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md

@@ -35,3 +35,4 @@ Reliability rules support library and application reliability, such as correct m
 | [CA2021: Don't call Enumerable.Cast\<T> or Enumerable.OfType\<T> with incompatible types](ca2021.md) | A call to <xref:System.Linq.Enumerable.Cast%60%601(System.Collections.IEnumerable)?displayProperty=nameWithType> or <xref:System.Linq.Enumerable.OfType%60%601(System.Collections.IEnumerable)?displayProperty=nameWithType> specifies a type parameter that's incompatible with the type of the input collection. |
 | [CA2022: Avoid inexact read with Stream.Read](ca2022.md) | A call to `Stream.Read` might return fewer bytes than requested, resulting in unreliable code if the return value isn't checked. |
 | [CA2024: Do not use StreamReader.EndOfStream in async methods](ca2024.md) | The property <xref:System.IO.StreamReader.EndOfStream?displayProperty=nameWithType> can cause unintended synchronous blocking when no data is buffered. Instead, use <xref:System.IO.StreamReader.ReadLineAsync?displayProperty=nameWithType> directly, which returns `null` when reaching the end of the stream. |
+| [CA2025: Do not pass `IDisposable` instances into unawaited tasks](ca2025.md) | Unawaited tasks that use `IDisposable` instances might use those instances long after they have been disposed. Ensure tasks using those instances are completed before the instances are disposed. |

docs/navigate/tools-diagnostics/toc.yml

@@ -1170,6 +1170,8 @@ items:
                     href: ../../fundamentals/code-analysis/quality-rules/ca2022.md
                   - name: CA2024
                     href: ../../fundamentals/code-analysis/quality-rules/ca2024.md
+                  - name: CA2025
+                    href: ../../fundamentals/code-analysis/quality-rules/ca2025.md
               - name: Security rules
                 items:
                   - name: Overview