Docs - Json+PipeReader deserialization support in MVC and Minimal APIs (#36102)

Author: tdykstra

aspnetcore/fundamentals/minimal-apis.md

@@ -70,6 +70,10 @@ The <xref:System.Delegate> arguments passed to these methods are called "route h
 
 [!INCLUDE [](~/fundamentals/minimal-apis/includes/parameter-binding10.md)]
 
+## Json+PipeReader deserialization in minimal APIs
+
+[!INCLUDE [](~/includes/net10pipereader.md)]
+
 ## Validation support in Minimal APIs
 
 Enabling validation allows the ASP.NET Core runtime to perform validations defined on the:

aspnetcore/fundamentals/minimal-apis/includes/parameter-binding10.md

@@ -427,4 +427,4 @@ The preceding code:
 * Accesses the request body using <xref:Microsoft.AspNetCore.Http.HttpRequest.BodyReader?displayProperty=nameWithType>.
 * Copies the request body to a local file.
 
-:::moniker-end
+:::moniker-end

aspnetcore/includes/net10pipereader.md

@@ -0,0 +1,53 @@
+<!--
+This include file is used in 
+minimal-apis.md
+model-binding.md
+-->
+
+Starting in .NET 10, the following functional areas of ASP.NET Core use overloads of <xref:System.Text.Json.JsonSerializer.DeserializeAsync%2A?displayProperty=nameWithType> based on PipeReader instead of Stream:
+
+* Minimal APIs (parameter binding, read request body)
+* MVC (input formatters, model)
+* The <xref:Microsoft.AspNetCore.Http.HttpRequestJsonExtensions> Extension methods to read the request body as JSON.
+
+For most applications, a transition from Stream to PipeReader provides better performance without requiring changes in application code. But if your application has a custom converter, the converter might not handle <xref:System.Text.Json.Utf8JsonReader.HasValueSequence%2A?displayProperty=nameWithType> correctly. If it doesn't, the result could be errors such as <xref:System.ArgumentOutOfRangeException> or missing data when deserializing. You have the following options for getting your converter to work without PipeReader-related errors.
+
+### Option 1: Temporary workaround
+
+The quick workaround is to go back to using Stream without PipeReader support. To implement this option, set the "Microsoft.AspNetCore.UseStreamBasedJsonParsing" AppContext switch to "true". We recommend that you do this only as a temporary workaround, and update your converter to support `HasValueSequence` as soon as possible. The switch might be removed in .NET 11. Its only purpose was to give developers time to get their converters updated.
+
+### Option 2: A quick fix for `JsonConverter` implementations
+
+For this fix, you allocate an array from the `ReadOnlySequence`. This example shows what the code would look like:
+
+```csharp
+public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+{
+    var span = reader.HasValueSequence ? reader.ValueSequence.ToArray() : reader.ValueSpan;
+    // previous code
+}
+```
+
+### Option 3: A more complicated but better performing fix
+
+This fix involves setting up a separate code path for the `ReadOnlySequence` handling:
+
+```csharp
+public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+{
+    if (reader.HasValueSequence)
+    {
+        reader.ValueSequence;
+        // ReadOnlySequence optimized path
+    }
+    else
+    {
+        reader.ValueSpan;
+        // ReadOnlySpan optimized path
+    }
+}
+```
+
+For more information, see
+* <xref:System.Text.Json.Serialization.JsonConverter?displayProperty=nameWithType>
+* [github.com/dotnet/aspnetcore/pull/62895](https://github.com/dotnet/aspnetcore/pull/62895)

aspnetcore/mvc/models/model-binding.md

@@ -8,7 +8,7 @@ ms.date: 07/19/2025
 ai-usage: ai-assisted
 uid: mvc/models/model-binding
 ---
-
+<!-- Note the use of inline moniker tags at the end of the file. -->
 # Model Binding in ASP.NET Core
 
 [!INCLUDE[](~/includes/not-latest-version.md)]
@@ -722,6 +722,16 @@ If an instance of the type isn't registered in the dependency injection containe
 
 For nullable parameters, ensure that the parameter isn't `null` before accessing it.
 
+:::moniker-end
+:::moniker range=">= aspnetcore-10.0"
+
+## Json+PipeReader deserialization in MVC
+
+[!INCLUDE [](~/includes/net10pipereader.md)]
+
+:::moniker-end
+:::moniker range=">= aspnetcore-8.0"
+
 ## Additional resources
 
 * [View or download sample code](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/mvc/models/model-binding/samples) ([how to download](xref:fundamentals/index#how-to-download-a-sample))
@@ -731,4 +741,3 @@ For nullable parameters, ensure that the parameter isn't `null` before accessing
 :::moniker-end
 
 [!INCLUDE[](~/mvc/models/model-binding/includes/model-binding7.md)]
-