Skip to content

Commit 87d2f14

Browse files
CopilotCopilot
authored
Document Cosmos JSON breaking changes
Document #5421
1 parent dc8fd06 commit 87d2f14

4 files changed

Lines changed: 172 additions & 9 deletions

File tree

‎entity-framework/core/providers/cosmos/unstructured-data.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,10 @@ EF Core was designed to make it easy to work with data that follows a schema def
1111

1212
## Accessing the raw JSON
1313

14-
It is possible to access the properties that are not tracked by EF Core through a special property in [shadow-state](xref:core/modeling/shadow-properties) named `"__jObject"` that contains a `JObject` representing the data received from the store and data that will be stored:
14+
> [!NOTE]
15+
> The `"__jObject"` shadow property was removed in EF Core 11. See [Breaking changes in EF Core 11](xref:core/what-is-new/ef-core-11.0/breaking-changes#jObject-removed) for details.
16+
17+
In EF Core 10 and earlier, it was possible to access properties not tracked by EF Core through a special property in [shadow-state](xref:core/modeling/shadow-properties) named `"__jObject"` that contained a `JObject` representing the data received from the store and data that will be stored:
1518

1619
[!code-csharp[Unmapped](../../../../samples/core/Cosmos/UnstructuredData/Sample.cs?highlight=21,22&name=Unmapped)]
1720

@@ -35,10 +38,7 @@ It is possible to access the properties that are not tracked by EF Core through
3538
```
3639

3740
> [!WARNING]
38-
> The `"__jObject"` property is part of the EF Core infrastructure and should only be used as a last resort as it is likely to have different behavior in future releases.
39-
40-
> [!NOTE]
41-
> Changes to the entity will override the values stored in `"__jObject"` during `SaveChanges`.
41+
> The `"__jObject"` property was part of the EF Core infrastructure and has been removed in EF Core 11. It should not be used in any version of EF Core as it may not be available.
4242
4343
## Using CosmosClient
4444

‎entity-framework/core/what-is-new/ef-core-11.0/breaking-changes.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Breaking changes in EF Core 11 (EF11) - EF Core
3+
description: List of breaking changes introduced in Entity Framework Core 11 (EF11)
4+
author: AndriySvyryd
5+
ms.date: 07/13/2026
6+
uid: core/what-is-new/ef-core-11.0/breaking-changes
7+
---
8+
9+
# Breaking changes in EF Core 11 (EF11)
10+
11+
This page documents API and behavior changes that have the potential to break existing applications updating from EF Core 10 to EF Core 11. Make sure to review earlier breaking changes if updating from an earlier version of EF Core:
12+
13+
- [Breaking changes in EF Core 10](xref:core/what-is-new/ef-core-10.0/breaking-changes)
14+
- [Breaking changes in EF Core 9](xref:core/what-is-new/ef-core-9.0/breaking-changes)
15+
- [Breaking changes in EF Core 8](xref:core/what-is-new/ef-core-8.0/breaking-changes)
16+
- [Breaking changes in EF Core 7](xref:core/what-is-new/ef-core-7.0/breaking-changes)
17+
- [Breaking changes in EF Core 6](xref:core/what-is-new/ef-core-6.0/breaking-changes)
18+
19+
## Summary
20+
21+
| **Breaking change** | **Impact** |
22+
|:----------------------------------------------------------------------------------------------------------|------------|
23+
| [Cosmos: `__jObject` shadow property removed; JObject no longer used for serialization](#jObject-removed) | High |
24+
| [Cosmos: Unmapped properties are no longer preserved](#unmapped-properties) | High |
25+
| [Cosmos: Floating-point values are now truncated when materializing to fixed-point types](#truncation) | Low |
26+
27+
## High-impact changes
28+
29+
<a name="jObject-removed"></a>
30+
31+
### Cosmos: `__jObject` shadow property removed; JObject no longer used for serialization
32+
33+
[Tracking Issue #5421](https://github.com/dotnet/EntityFramework.Docs/issues/5421)
34+
35+
#### Old behavior
36+
37+
Previously, the Azure Cosmos DB provider added a shadow property named `"__jObject"` of type `JObject` (from `Newtonsoft.Json`) to every entity type. This property contained the raw JSON document as received from and sent to Cosmos DB, allowing users to access unmapped or raw data:
38+
39+
```csharp
40+
var order = await context.Orders.FirstAsync();
41+
var rawJson = context.Entry(order).Property<JObject>("__jObject").CurrentValue;
42+
var billingAddress = rawJson["BillingAddress"]?.Value<string>();
43+
```
44+
45+
EF Core used `Newtonsoft.Json` (via `JObject`) internally for document serialization and deserialization.
46+
47+
#### New behavior
48+
49+
Starting with EF Core 11, the `__jObject` shadow property no longer exists. EF Core now uses `System.Text.Json` (`Utf8JsonReader`/`Utf8JsonWriter`) for document serialization and deserialization, and no longer relies on `Newtonsoft.Json`.
50+
51+
Accessing the `"__jObject"` property will throw an `InvalidOperationException`.
52+
53+
#### Why
54+
55+
The `JObject`-based approach required a dependency on `Newtonsoft.Json` and limited performance improvements. Switching to `System.Text.Json` aligns EF Core Cosmos with the rest of the .NET ecosystem and enables significant performance gains.
56+
57+
#### Mitigations
58+
59+
To access the raw JSON document, use the `CosmosClient` directly instead of relying on `__jObject`:
60+
61+
```csharp
62+
var cosmosClient = context.Database.GetCosmosClient();
63+
var container = cosmosClient.GetContainer("myDatabase", "myContainer");
64+
var response = await container.ReadItemAsync<JsonElement>("1", new PartitionKey("1"));
65+
var billingAddress = response.Resource.GetProperty("BillingAddress").GetString();
66+
```
67+
68+
For more information, see [Working with Unstructured Data in Azure Cosmos DB](xref:core/providers/cosmos/unstructured-data).
69+
70+
<a name="unmapped-properties"></a>
71+
72+
### Cosmos: Unmapped properties are no longer preserved
73+
74+
[Tracking Issue #5421](https://github.com/dotnet/EntityFramework.Docs/issues/5421)
75+
76+
#### Old behavior
77+
78+
Previously, when EF Core read a Cosmos DB document that contained properties not mapped in the EF model, those extra properties were preserved in the `__jObject` shadow property and written back to the database on the next `SaveChanges`. This meant unmapped data in documents was transparently round-tripped.
79+
80+
#### New behavior
81+
82+
Starting with EF Core 11, unmapped properties in a Cosmos DB document are ignored when reading. Any extra JSON properties that are not part of the EF model will be lost if the entity is subsequently saved.
83+
84+
#### Why
85+
86+
Because `__jObject` has been removed (see above), there is no mechanism to preserve unmapped properties. EF Core 11 uses a lean JSON reader that only processes the properties it knows about.
87+
88+
#### Mitigations
89+
90+
If your application relies on preserving unmapped data, consider one of the following options:
91+
92+
- **Use `CosmosClient` directly** for documents where you need full control over the JSON shape.
93+
- **Map all relevant properties** explicitly in your EF model, even if they are not used by application logic.
94+
- **Use a JSON column or an untyped dictionary property** to capture extra data, if that pattern fits your model.
95+
96+
## Low-impact changes
97+
98+
<a name="truncation"></a>
99+
100+
### Cosmos: Floating-point values are now truncated when materializing to fixed-point types
101+
102+
[Tracking Issue #38138](https://github.com/dotnet/efcore/issues/38138)
103+
104+
#### Old behavior
105+
106+
Previously, when a query projection returned a floating-point value (e.g., the result of a numeric expression such as `3 / 4` returned by Cosmos as `0.75`) and the target property was a fixed-point type (`int`, `long`, `decimal`, etc.), EF Core would **round** the value. This meant `0.75` would materialize as `1`.
107+
108+
#### New behavior
109+
110+
Starting with EF Core 11, such values are **truncated** instead of rounded. `0.75` now materializes as `0`, matching standard .NET integer truncation behavior (`(int)0.75 == 0`).
111+
112+
#### Why
113+
114+
Truncation is the standard .NET behavior for explicit numeric conversions and is consistent with how other providers behave. The previous rounding behavior was a bug.
115+
116+
#### Mitigations
117+
118+
If you relied on the previous rounding behavior, apply explicit rounding in your queries using `Math.Round`:
119+
120+
```csharp
121+
var result = await context.Products
122+
.Select(p => (int)Math.Round((double)(p.Int / (p.Int + 1))))
123+
.SingleAsync();
124+
```

‎entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: What's New in EF Core 11
3+
description: Overview of new features in EF Core 11
4+
author: AndriySvyryd
5+
ms.date: 07/13/2026
6+
uid: core/what-is-new/ef-core-11.0/whatsnew
7+
---
8+
9+
# What's New in EF Core 11
10+
11+
EF Core 11 (EF11) is the next release after EF Core 10 and is scheduled for release in November 2026.
12+
13+
EF11 is available as a preview. See [.NET 11 release notes](https://github.com/dotnet/core/tree/main/release-notes/11.0) to get information about the latest preview. This article will be updated as new preview releases are made available.
14+
15+
EF11 requires the .NET 11 SDK to build and requires the .NET 11 runtime to run. EF11 will not run on earlier .NET versions, and will not run on .NET Framework.
16+
17+
## Azure Cosmos DB for NoSQL
18+
19+
<a name="cosmos-modernized-materializer"></a>
20+
21+
### Modernized materializer using System.Text.Json
22+
23+
[Tracking Issue #5421](https://github.com/dotnet/EntityFramework.Docs/issues/5421)
24+
25+
EF Core 11 updates the Azure Cosmos DB provider to use `System.Text.Json` (`Utf8JsonReader`/`Utf8JsonWriter`) for document serialization and deserialization, replacing the previous `Newtonsoft.Json`-based approach.
26+
27+
As part of this change:
28+
29+
- The `__jObject` shadow property (of type `JObject`) that was previously added to every entity type has been removed.
30+
- Unmapped properties in Cosmos documents are no longer preserved on round-trip.
31+
- Floating-point query results are now **truncated** (rather than rounded) when materialized to fixed-point types such as `int`, matching standard .NET numeric conversion behavior.
32+
33+
These changes improve performance and align EF Core Cosmos with the rest of the .NET ecosystem. However, they are breaking changes for applications that relied on `__jObject` or unmapped property preservation. See the [breaking changes documentation](xref:core/what-is-new/ef-core-11.0/breaking-changes) for details and mitigations.

‎entity-framework/toc.yml‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,10 @@
3232
items:
3333
- name: Welcome!
3434
href: core/index.md
35-
- name: "What's new in EF Core 9.0"
36-
href: core/what-is-new/ef-core-9.0/whatsnew.md
37-
- name: "Breaking changes in EF Core 9.0"
38-
href: core/what-is-new/ef-core-9.0/breaking-changes.md
35+
- name: "What's new in EF Core 11.0"
36+
href: core/what-is-new/ef-core-11.0/whatsnew.md
37+
- name: "Breaking changes in EF Core 11.0"
38+
href: core/what-is-new/ef-core-11.0/breaking-changes.md
3939
- name: Getting started
4040
items:
4141
- name: EF Core Overview
@@ -61,6 +61,12 @@
6161
href: core/what-is-new/index.md
6262
- name: Release planning process
6363
href: core/what-is-new/release-planning.md
64+
- name: EF Core 11.0
65+
items:
66+
- name: "What's new?"
67+
href: core/what-is-new/ef-core-11.0/whatsnew.md
68+
- name: Breaking changes
69+
href: core/what-is-new/ef-core-11.0/breaking-changes.md
6470
- name: EF Core 10.0
6571
items:
6672
- name: "What's new?"

0 commit comments

Comments
 (0)