Breaking changes in EF Core 9 (EF9)
This page documents API and behavior changes that have the potential to break existing applications updating from EF Core 8 to EF Core 9. Make sure to review earlier breaking changes if updating from an earlier version of EF Core:
Target Framework
EF Core 9 targets .NET 8. This means that existing applications that target .NET 8 can continue to do so. Applications targeting older .NET, .NET Core, and .NET Framework versions will need to target .NET 8 or .NET 9 to use EF Core 9.
Summary
Note
If you are using Azure Cosmos DB, please see the separate section below on Azure Cosmos DB breaking changes.
Low-impact changes
EF.Functions.Unhex() now returns byte[]?
Old behavior
The EF.Functions.Unhex() function was previously annotated to return byte[].
New behavior
Starting with EF Core 9.0, Unhex() is now annotated to return byte[]?.
Why
Unhex() is translated to the SQLite unhex function, which returns NULL for invalid inputs. As a result, Unhex() returned null for those cases, in violation of the annotation.
Mitigations
If you are sure that the text content passed to Unhex() represents a valid, hexadecimal string, you can simply add the null-forgiving operator as an assertion that the invocation will never return null:
var binaryData = await context.Blogs.Select(b => EF.Functions.Unhex(b.HexString)!).ToListAsync();
Otherwise, add runtime checks for null on the return value of Unhex().
SqlFunctionExpression's nullability arguments' arity validated
Old behavior
Previously it was possible to create a SqlFunctionExpression with a different number of arguments and nullability propagation arguments.
New behavior
Starting with EF Core 9.0, EF now throws if the number of arguments and nullability propagation arguments do not match.
Why
Not having matching number of arguments and nullability propagation arguments can lead to unexpected behavior.
Mitigations
Make sure the argumentsPropagateNullability has same number of elements as the arguments. When in doubt use false for nullability argument.
ToString() method now returns empty string for null instances
Old behavior
Previously EF returned inconsistent results for the ToString() method when the argument value was null. E.g. ToString() on bool? property with null value returned null, but for non-property bool? expressions whose value was null it returned True. The behavior was also inconsistent for other data types, e.g. ToString() on null value enum returned empty string.
New behavior
Starting with EF Core 9.0, the ToString() method now consistently returns empty string in all cases when the argument value is null.
Why
The old behavior was inconsistent across different data types and situations, as well as not aligned with the C# behavior.
Mitigations
To revert to the old behavior, rewrite the query accordingly:
var newBehavior = context.Entity.Select(x => x.NullableBool.ToString());
var oldBehavior = context.Entity.Select(x => x.NullableBool == null ? null : x.NullableBool.ToString());
Shared framework dependencies were updated to 9.0.x
Old behavior
Apps using the Microsoft.NET.Sdk.Web SDK and targetting net8.0 would resolve packages like System.Text.Json, Microsoft.Extensions.Caching.Memory, Microsoft.Extensions.Configuration.Abstractions, Microsoft.Extensions.Logging and Microsoft.Extensions.DependencyModel from the shared framework, so these assemblies wouldn't normally be deployed with the app.
New behavior
While EF Core 9.0 still supports net8.0 it now references the 9.0.x versions of System.Text.Json, Microsoft.Extensions.Caching.Memory, Microsoft.Extensions.Configuration.Abstractions, Microsoft.Extensions.Logging and Microsoft.Extensions.DependencyModel. Apps targetting net8.0 will not be able to leverage the shared framework to avoid deploying these assemblies.
Why
The matching dependency versions contain the latest security fixes and using them simplifies the servicing model for EF Core.
Mitigations
Change your app to target net9.0 to get the previous behavior.
Azure Cosmos DB breaking changes
Extensive work has gone into making the Azure Cosmos DB provider better in 9.0. The changes include a number of high-impact breaking changes; if you are upgrading an existing application, please read the following carefully.
High-impact changes
The discriminator property is now named $type instead of Discriminator
Old behavior
EF automatically adds a discriminator property to JSON documents to identify the entity type that the document represents. In previous versions of EF, this JSON property used to be named Discriminator by default.
New behavior
Starting with EF Core 9.0, the discriminator property is now called $type by default. If you have existing documents in Azure Cosmos DB from previous versions of EF, these use the old Discriminator naming, and after upgrading to EF 9.0, queries against those documents will fail.
Why
An emerging JSON practice uses a $type property in scenarios where a document's type needs to be identified. For example, .NET's System.Text.Json also supports polymorphism, using $type as its default discriminator property name (docs). To align with the rest of the ecosystem and make it easier to interoperate with external tools, the default was changed.
Mitigations
The easiest mitigation is to simply configure the name of the discriminator property to be Discriminator, just as before:
modelBuilder.Entity<Session>().HasDiscriminator<string>("Discriminator");
Doing this for all your top-level entity types will make EF behave just like before.
At this point, if you wish, you can also update all your documents to use the new $type naming.
The id property now contains only the EF key property by default
Old behavior
Previously, EF inserted the discriminator value of your entity type into the id property of the document. For example, if you saved a Blog entity type with an Id property containing 8, the JSON id property would contain Blog|8.
New behavior
Starting with EF Core 9.0, the JSON id property no longer contains the discriminator value, and only contains the value of your key property. For the above example, the JSON id property would simply be 8. If you have existing documents in Azure Cosmos DB from previous versions of EF, these have the discriminator value in the JSON id property, and after upgrading to EF 9.0, queries against those documents will fail.
Why
Since the JSON id property must be unique, the discriminator was previously added to it to allow different entities with the same key value to exist. For example, this allowed having both a Blog and a Post with an Id property containing the value 8 within the same container and partition. This aligned better with relational database data modeling patterns, where each entity type is mapped to its own table, and therefore has its own key-space.
EF 9.0 generally changed the mapping to be more aligned with common Azure Cosmos DB NoSQL practices and expectations, rather than to correspond to the expectations of users coming from relational databases. In addition, having the discriminator value in the id property made it more difficult for external tools and systems to interact with EF-generated JSON documents; such external systems aren't generally aware of the EF discriminator values, which are by default derived from .NET types.
Mitigations
The easiest mitigation is to simply configure EF to include the discriminator in the JSON id property, as before. A new configuration option has been introduced for this purpose:
modelBuilder.Entity<Session>().HasDiscriminatorInJsonId();
Doing this for all your top-level entity types will make EF behave just like before.
At this point, if you wish, you can also update all your documents to rewrite their JSON id property. Note that this is only possible if entities of different types don't share the same id value within the same container.
Medium-impact changes
Sync I/O via the Azure Cosmos DB provider is no longer supported
Old behavior
Previously, calling synchronous methods like ToList or SaveChanges would cause EF Core to block synchronously using .GetAwaiter().GetResult() when executing async calls against the Azure Cosmos DB SDK. This can result in deadlock.
New behavior
Starting with EF Core 9.0, EF now throws by default when attempting to use synchronous I/O. The exception message is "Azure Cosmos DB does not support synchronous I/O. Make sure to use and correctly await only async methods when using Entity Framework Core to access Azure Cosmos DB. See https://aka.ms/ef-cosmos-nosync for more information."
Why
Synchronous blocking on asynchronous methods can result in deadlock, and the Azure Cosmos DB SDK only supports async methods.
Mitigations
In EF Core 9.0, the error can be suppressed with:
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
optionsBuilder.ConfigureWarnings(w => w.Ignore(CosmosEventId.SyncNotSupported));
}
That being said, applications should stop using sync APIs with Azure Cosmos DB since this is not supported by the Azure Cosmos DB SDK. The ability to suppress the exception will be removed in a future release of EF Core, after which the only option will be to use async APIs.
SQL queries must now project JSON values directly
Old behavior
Previously, EF generated queries such as the following:
SELECT c["City"] FROM root c
Such queries cause Azure Cosmos DB to wrap each result in a JSON object, as follows:
[
{
"City": "Berlin"
},
{
"City": "México D.F."
}
]
New behavior
Starting with EF Core 9.0, EF now adds the VALUE modifier to queries as follows:
SELECT VALUE c["City"] FROM root c
Such queries cause Azure Cosmos DB to return the values directly, without being wrapped:
[
"Berlin",
"México D.F."
]
If your application makes use of SQL queries, such queries are likely broken after upgrading to EF 9.0, as they don't include the VALUE modifier.
Why
Wrapping each result in an additional JSON object can cause performance degradation in some scenarios, bloats the JSON result payload, and isn't the natural way to work with Azure Cosmos DB.
Mitigations
To mitigate, simply add the VALUE modifier to the projections of your SQL queries, as shown above.
Undefined results are now automatically filtered from query results
Old behavior
Previously, EF generated queries such as the following:
SELECT c["City"] FROM root c
Such queries cause Azure Cosmos DB to wrap each result in a JSON object, as follows:
[
{
"City": "Berlin"
},
{
"City": "México D.F."
}
]
If any of the results were undefined (e.g. the City property was absent from the document), an empty document was returned, and EF would return null for that result.
New behavior
Starting with EF Core 9.0, EF now adds the VALUE modifier to queries as follows:
SELECT VALUE c["City"] FROM root c
Such queries cause Azure Cosmos DB to return the values directly, without being wrapped:
[
"Berlin",
"México D.F."
]
The Azure Cosmos DB behavior is to automatically filter undefined values out of results; this means that if one of the City properties is absent from the document, the query would return just a single result, rather than two results, with one being null.
Why
Wrapping each result in an additional JSON object can cause performance degradation in some scenarios, bloats the JSON result payload, and isn't the natural way to work with Azure Cosmos DB.
Mitigations
If getting null values for undefined results is important for your application, coalesce the undefined values to null using the new EF.Functions.Coalesce operator:
var users = await context.Customer
.Select(c => EF.Functions.CoalesceUndefined(c.City, null))
.ToListAsync();
Incorrectly translated queries are no longer translated
Old behavior
Previously, EF translated queries such as the following:
var sessions = await context.Sessions
.Take(5)
.Where(s => s.Name.StartsWith("f"))
.ToListAsync();
However, the SQL translation for this query was incorrect:
SELECT c
FROM root c
WHERE ((c["Discriminator"] = "Session") AND STARTSWITH(c["Name"], "f"))
OFFSET 0 LIMIT @__p_0
In SQL, the WHERE clause is evaluated before the OFFSET and LIMIT clauses; but in the LINQ query above, the Take operator appears before the Where operator. As a result, such queries could return incorrect results.
New behavior
Starting with EF Core 9.0, such queries are no longer translated, and an exception is thrown.
Why
Incorrect translations can cause silent data corruption, which can introduce hard-to-discover bugs in your application. EF always prefer to fail-fast by throwing up-front rather than to possibly cause data corruption.
Mitigations
If you were happy with the previous behavior and would like to execute the same SQL, simply swap around the order of LINQ operators:
var sessions = await context.Sessions
.Where(s => s.Name.StartsWith("f"))
.Take(5)
.ToListAsync();
Unfortunately, Azure Cosmos DB does not currently support the OFFSET and LIMIT clauses in SQL subqueries, which is what the proper translation of the original LINQ query requires.
Low-impact changes
HasIndex now throws instead of being ignored
Old behavior
Previously, calls to HasIndex were ignored by the EF Cosmos DB provider.
New behavior
The provider now throws if HasIndex is specified.
Why
In Azure Cosmos DB, all properties are indexed by default, and no indexing needs to be specified. While it's possible to define a custom indexing policy, this isn't currently supported by EF, and can be done via the Azure Portal without EF support. Since HasIndex calls weren't doing anything, they are no longer allowed.
Mitigations
Remove any calls to HasIndex.
IncludeRootDiscriminatorInJsonId was renamed to HasRootDiscriminatorInJsonId after 9.0.0-rc.2
Old behavior
The IncludeRootDiscriminatorInJsonId API was introduced in 9.0.0 rc.1.
New behavior
For the final release of EF Core 9.0, the API was renamed to HasRootDiscriminatorInJsonId
Why
Another related API was renamed to start with Has instead of Include, and so this one was renamed for consistency as well.
Mitigations
If your code is using the IncludeRootDiscriminatorInJsonId API, simply change it to reference HasRootDiscriminatorInJsonId instead.
