Document parameterized collection translation as breaking change in EF Core 10

[Copilot]

EF Core 10 changed the default parameterized collection translation from JSON arrays (OPENJSON) to multiple scalar parameters. Applications relying on the EF Core 8-9 OPENJSON performance characteristics may experience regressions when upgrading.

Changes

• Added NOTE block to the existing "Parameterized collections now use multiple parameters by default" breaking change section
• Clarifies that while most applications won't be affected, those with large collections or specific query patterns optimized for OPENJSON may see performance differences
• Directs users to existing mitigation strategies (UseParameterizedCollectionMode, EF.Parameter) if regressions occur

The note follows the same pattern as the documented EF Core 8 breaking change for similar parameterized collection performance issues.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Changes to default translation of parameterized collections should be documented as a breaking change in EF Core 10</issue_title>
<issue_description>### Type of issue

Missing information

Description

The default translation of parameterized collections has changed again in EF Core 10 as documented here.

This change should be considered a breaking change as it can affect performance, sometimes drastically reduce performance or even cause the query to fail (especially when the collection contains a large number of items). In EF Core 8, OPENJSON was the default (initially there was no option to change the behavior, that ability was introduced in EF Core 9). Any project written with EF Core 8 that relied on the performance characteristics of OPENJSON that is then upgraded to version 10 would need to be updated to use UseParameterizedCollectionMode or EF.Parameter wherever necessary.

This is the same idea as the documented breaking change for EF Core 8.

Page URL

https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-10.0/breaking-changes

Content source URL

https://github.com/dotnet/EntityFramework.Docs/blob/main/entity-framework/core/what-is-new/ef-core-10.0/breaking-changes.md

Document Version Independent Id

bbde202d-67a5-fa94-03cd-8a526a1f2a56

Platform Id

9992e66c-a232-bf52-db0b-d236573bddb5

Article author

@roji</issue_description>

<agent_instructions>Add a low-impact note in the 10.0 breaking changes page. Make it clear that this is a behavioral change that in the majority of cases will not cause any change in behavior or regress performance; but it's definitely a change in the way the query is translated to SQL, and might therefore have adverse consequence.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@roji Have you yourself experienced experienced a drastic performance reduction because of this change?

• Fixes Changes to default translation of parameterized collections should be documented as a breaking change in EF Core 10 #5152

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.