diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2025.md b/docs/fundamentals/code-analysis/quality-rules/ca2025.md new file mode 100644 index 0000000000000..ba02b55805cd7 --- /dev/null +++ b/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). diff --git a/docs/fundamentals/code-analysis/quality-rules/index.md b/docs/fundamentals/code-analysis/quality-rules/index.md index 9ca888949c314..3a5f7c27fc3b8 100644 --- a/docs/fundamentals/code-analysis/quality-rules/index.md +++ b/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\ or Enumerable.OfType\ with incompatible types](ca2021.md) | A call to or 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 can cause unintended synchronous blocking when no data is buffered. Instead, use 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. | diff --git a/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md b/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md index 4104f7ec1c4c7..37a93a288af35 100644 --- a/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md +++ b/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\ or Enumerable.OfType\ with incompatible types](ca2021.md) | A call to or 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 can cause unintended synchronous blocking when no data is buffered. Instead, use 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. | diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 8f20bbccb3c04..c57d8d0ed86a5 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1166,6 +1166,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