From 3f3151ae49040820b52ddb1796e6d00d6a21c4d2 Mon Sep 17 00:00:00 2001 From: Mario Pistrich Date: Thu, 16 Jan 2025 03:26:44 +0100 Subject: [PATCH 1/2] Add documentation for CA2024 --- .../code-analysis/quality-rules/ca2024.md | 107 ++++++++++++++++++ .../code-analysis/quality-rules/index.md | 1 + .../quality-rules/reliability-warnings.md | 1 + docs/navigate/tools-diagnostics/toc.yml | 2 + 4 files changed, 111 insertions(+) create mode 100644 docs/fundamentals/code-analysis/quality-rules/ca2024.md diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2024.md b/docs/fundamentals/code-analysis/quality-rules/ca2024.md new file mode 100644 index 0000000000000..db8c290b4bf9f --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/ca2024.md @@ -0,0 +1,107 @@ +--- +title: "CA2024: Do not use StreamReader.EndOfStream in async methods" +description: "Learn about code analysis rule CA2024 - Do not use StreamReader.EndOfStream in async methods" +ms.date: 01/16/2025 +ms.topic: reference +f1_keywords: + - CA2024 + - DoNotUseEndOfStreamInAsyncMethodsAnalyzer +helpviewer_keywords: + - CA2024 +author: mpidash +dev_langs: +- CSharp +- VB +--- + +# CA2024: Do not use StreamReader.EndOfStream in async methods + +| Property | Value | +|-------------------------------------|------------------------------------------------------| +| **Rule ID** | CA2024 | +| **Title** | Do not use StreamReader.EndOfStream in async methods | +| **Category** | [Reliability](reliability-warnings.md) | +| **Fix is breaking or non-breaking** | Non-breaking | +| **Enabled by default in .NET 10** | As warning | + +## Cause + +A call to is made inside an async method. + +## Rule description + +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. + +## How to fix violations + +To fix a violation, directly call and check the return value for `null`. + +## Example + +The following code snippet shows a violation of CA2024 and the fix for the violation. + +```csharp +public async Task Example(StreamReader streamReader) +{ + while (!streamReader.EndOfStream) + { + string? line = await streamReader.ReadLineAsync(); + // Do something with line. + } +} +``` + +```vb +Public Async Function Example(streamReader As StreamReader) As Task + While Not streamReader.EndOfStream + Dim line As String = Await streamReader.ReadLineAsync() + ' Do something with line. + End While +End Function +``` + +The following code snippet fixes the violation: + +```csharp +public async Task Example(StreamReader streamReader) +{ + string? line; + while ((line = await streamReader.ReadLineAsync()) is not null) + { + // Do something with line. + } +} +``` + +```vb +Public Async Function Example(streamReader As StreamReader) As Task + Dim line As String = Await streamReader.ReadLineAsync() + While line IsNot Nothing + ' Do something with line. + line = Await streamReader.ReadLineAsync() + End While +End Function +``` + +## When to suppress warnings + +You shouldn't suppress warnings from this rule, as your app might hang if you don't fix the violations. + +## 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 CA2024 +// The code that's violating the rule is on this line. +#pragma warning restore CA2024 +``` + +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.CA2024.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 67a16fb26a64c..9ca888949c314 100644 --- a/docs/fundamentals/code-analysis/quality-rules/index.md +++ b/docs/fundamentals/code-analysis/quality-rules/index.md @@ -189,6 +189,7 @@ The following table lists code quality analysis rules. > | [CA2020: Prevent behavioral change caused by built-in operators of IntPtr/UIntPtr](ca2020.md) | Some built-in operators added in .NET 7 behave differently than the user-defined operators in .NET 6 and earlier versions. Some operators that used to throw in unchecked context while overflowing don't throw anymore unless wrapped within checked context. Some operators that previously didn't throw in checked context now throw unless wrapped within unchecked context. | > | [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. | > | [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 19400284ef2b3..afa93cc217a70 100644 --- a/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md @@ -33,3 +33,4 @@ Reliability rules support library and application reliability, such as correct m | [CA2019: `ThreadStatic` fields should not use inline initialization](ca2019.md) | A field that's annotated with is initialized inline or explicitly in a `static` (`Shared` in Visual Basic) constructor. | | [CA2020: Prevent behavioral change caused by built-in operators of IntPtr/UIntPtr](ca2020.md) | Some built-in operators added in .NET 7 behave differently than the user-defined operators in .NET 6 and earlier versions. Some operators that used to throw in unchecked context while overflowing don't throw anymore unless wrapped within checked context. Some operators that previously didn't throw in checked context now throw unless wrapped within unchecked context. | | [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. | +| [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. | diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 33f7ed0c9aa30..ec776c6c512a6 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1147,6 +1147,8 @@ items: href: ../../fundamentals/code-analysis/quality-rules/ca2021.md - name: CA2022 href: ../../fundamentals/code-analysis/quality-rules/ca2022.md + - name: CA2024 + href: ../../fundamentals/code-analysis/quality-rules/ca2024.md - name: Security rules items: - name: Overview From 1ca732957c2a92d4c1f1072fb659540929db7124 Mon Sep 17 00:00:00 2001 From: Mario Pistrich Date: Thu, 16 Jan 2025 20:41:36 +0100 Subject: [PATCH 2/2] Apply suggestion from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fundamentals/code-analysis/quality-rules/ca2024.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2024.md b/docs/fundamentals/code-analysis/quality-rules/ca2024.md index db8c290b4bf9f..83a889f5bc2e3 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2024.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2024.md @@ -38,7 +38,7 @@ To fix a violation, directly call