Add documentation for CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement (#49640)

Author: Copilot

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

@@ -0,0 +1,77 @@
+---
+title: "CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement"
+description: "Learn about code analysis rule CA2026 - Prefer JsonElement.Parse over JsonDocument.Parse().RootElement"
+ms.date: 11/05/2025
+f1_keywords:
+  - CA2026
+  - PreferJsonElementParseOverJsonDocumentParse
+helpviewer_keywords:
+  - CA2026
+ai-usage: ai-assisted
+dev_langs:
+- CSharp
+- VB
+---
+
+# CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement
+
+| Property                            | Value                                                                    |
+|-------------------------------------|--------------------------------------------------------------------------|
+| **Rule ID**                         | CA2026                                                                   |
+| **Title**                           | Prefer `JsonElement.Parse` over `JsonDocument.Parse().RootElement`       |
+| **Category**                        | [Reliability](reliability-warnings.md)                                   |
+| **Fix is breaking or non-breaking** | Non-breaking                                                             |
+| **Enabled by default in .NET 10**   | As suggestion                                                            |
+
+## Cause
+
+Code uses `JsonDocument.Parse().RootElement` to parse JSON into a <xref:System.Text.Json.JsonElement>.
+
+## Rule description
+
+<xref:System.Text.Json.JsonElement.Parse*?displayProperty=nameWithType> is more efficient than calling `JsonDocument.Parse().RootElement`. The <xref:System.Text.Json.JsonDocument> type implements <xref:System.IDisposable> and rents arrays from the <xref:System.Buffers.ArrayPool%601>, which can lead to memory leaks or increased GC pressure if you don't properly dispose the document. The `JsonElement.Parse` method, introduced in .NET 10, parses JSON directly into a <xref:System.Text.Json.JsonElement> without these concerns, making it more efficient and less error-prone.
+
+## How to fix violations
+
+Replace calls to `JsonDocument.Parse().RootElement` with `JsonElement.Parse()`.
+
+## Examples
+
+The following code snippet shows a violation of CA2026:
+
+:::code language="csharp" source="snippets/csharp/all-rules/ca2026.cs" id="Violation":::
+:::code language="vb" source="snippets/vb/all-rules/ca2026.vb" id="Violation":::
+
+The following code snippet fixes the violation:
+
+:::code language="csharp" source="snippets/csharp/all-rules/ca2026.cs" id="Fixed":::
+:::code language="vb" source="snippets/vb/all-rules/ca2026.vb" id="Fixed":::
+
+## When to suppress warnings
+
+Don't suppress warnings from this rule. If you're targeting .NET 10 or later, you should use `JsonElement.Parse()` for better performance and resource management.
+
+## 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 CA2026
+// The code that's violating the rule is on this line.
+#pragma warning restore CA2026
+```
+
+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.CA2026.severity = none
+```
+
+For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).
+
+## See also
+
+- [Reliability rules](reliability-warnings.md)
+- <xref:System.Text.Json.JsonElement.Parse%2A?displayProperty=nameWithType>
+- <xref:System.Text.Json.JsonDocument.Parse%2A?displayProperty=nameWithType>

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

@@ -196,6 +196,7 @@ The following table lists code quality analysis rules.
 > | [CA2023: Invalid braces in message template](ca2023.md) | The braces present in the message template are invalid. Ensure any braces in the message template are valid opening/closing braces, or are escaped. |
 > | [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. |
+> | [CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement](ca2026.md) | It's more efficient to call `JsonElement.Parse` directly than to call `JsonDocument.Parse().RootElement`. |
 > | [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
 | [CA2023: Invalid braces in message template](ca2023.md) | Logging message templates use curly braces `{` and `}` to denote named placeholders for values. Invalid brace usage in message templates can result in runtime exceptions or unexpected logging behavior. |
 | [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. |
+| [CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement](ca2026.md) | It's more efficient to call <xref:System.Text.Json.JsonElement.Parse%2A?displayProperty=nameWithType> directly than to call `JsonDocument.Parse().RootElement`. |

docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/all-rules.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net9.0</TargetFramework>
+    <TargetFramework>net10.0</TargetFramework>
     <Nullable>enable</Nullable>
     <RootNamespace>all_rules</RootNamespace>
   </PropertyGroup>

docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2026.cs

@@ -0,0 +1,23 @@
+using System.Text.Json;
+
+namespace ca2026
+{
+    public static class Examples
+    {
+        //<Violation>
+        public static void ProcessJsonViolation(string json)
+        {
+            JsonElement element = JsonDocument.Parse(json).RootElement;
+            //...
+        }
+        //</Violation>
+
+        //<Fixed>
+        public static void ProcessJsonFixed(string json)
+        {
+            JsonElement element = JsonElement.Parse(json);
+            //...
+        }
+        //</Fixed>
+    }
+}

docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <RootNamespace>all_rules</RootNamespace>
-    <TargetFramework>net9.0</TargetFramework>
+    <TargetFramework>net10.0</TargetFramework>
     <NoWarn>$(NoWarn);SYSLIB0050</NoWarn>
   </PropertyGroup>
 

docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2026.vb

@@ -0,0 +1,23 @@
+Imports System.Text.Json
+
+Namespace ca2026
+
+    Public Module Examples
+
+        '<Violation>
+        Public Sub ProcessJsonViolation(json As String)
+            Dim element As JsonElement = JsonDocument.Parse(json).RootElement
+            '...
+        End Sub
+        '</Violation>
+
+        '<Fixed>
+        Public Sub ProcessJsonFixed(json As String)
+            Dim element As JsonElement = JsonElement.Parse(json)
+            '...
+        End Sub
+        '</Fixed>
+
+    End Module
+
+End Namespace

docs/navigate/tools-diagnostics/toc.yml

@@ -3347,6 +3347,8 @@ items:
                     href: ../../fundamentals/code-analysis/quality-rules/ca2024.md
                   - name: CA2025
                     href: ../../fundamentals/code-analysis/quality-rules/ca2025.md
+                  - name: CA2026
+                    href: ../../fundamentals/code-analysis/quality-rules/ca2026.md
               - name: Security rules
                 items:
                   - name: Overview