Add documentation for CA2024 (#44401)

Author: mpidash

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 <xref:System.IO.StreamReader.EndOfStream?displayProperty=nameWithType> is made inside an async method.
+
+## Rule description
+
+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.
+
+## How to fix violations
+
+To fix a violation, directly call <xref:System.IO.StreamReader.ReadLineAsync?displayProperty=nameWithType> and check the return value for `null`.
+
+## Example
+
+The following code snippet shows a violation of CA2024:
+
+```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).

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

@@ -34,3 +34,4 @@ Reliability rules support library and application reliability, such as correct m
 | [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\<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. |

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