C#idiomatic C#
ca2026fundamentals/code-analysis/quality-rules

Code analysis

CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement

Learn about code analysis rule CA2026 - Prefer JsonElement.Parse over JsonDocument.Parse().RootElement

CA2026 Reliability enabled by default in .NET 10: As suggestion
Fix is breaking or non-breaking Non-breakingApplicable languages C# and Visual Basic

Cause

Code uses JsonDocument.Parse().RootElement to parse JSON into a System.Text.Json.JsonElement.

Rule description

System.Text.Json.JsonElement.Parse is more efficient than calling JsonDocument.Parse().RootElement. The System.Text.Json.JsonDocument type implements System.IDisposable and rents arrays from the System.Buffers.ArrayPool, 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 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:

sample · csharpdocs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2026.csViolation

csharp
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>
    }
}

sample · vbdocs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2026.vbViolation

vb
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

The following code snippet fixes the violation:

sample · csharpdocs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2026.csFixed

csharp
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>
    }
}

sample · vbdocs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2026.vbFixed

vb
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

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.

ini
[*.{cs,vb}]
dotnet_diagnostic.CA2026.severity = none

For more information, see How to suppress code analysis warnings.

See also