diff --git a/entity-framework/core/cli/msbuild.md b/entity-framework/core/cli/msbuild.md index 7a537fa00b..7302fa5904 100644 --- a/entity-framework/core/cli/msbuild.md +++ b/entity-framework/core/cli/msbuild.md @@ -2,7 +2,7 @@ title: EF Core MSBuild tasks - EF Core description: Reference guide for the Entity Framework Core .NET MSBuild tasks author: AndriySvyryd -ms.date: 01/17/2025 +ms.date: 03/04/2026 uid: core/cli/msbuild --- @@ -30,7 +30,7 @@ If the project specifies `true` then by default the MSB | MSBuild property | Description | |--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| EFOptimizeContext | Set to `true` to enable MSBuild integration. | +| EFOptimizeContext | Set to `true` to enable MSBuild integration. **EF Core 9-10 only; removed in EF Core 11.** | | EFScaffoldModelStage | Set to `publish`, `build` or `none` to indicate at which stage the compiled model will be generated. Defaults to `publish`. | | EFPrecompileQueriesStage | Set to `publish`, `build` or `none` to indicate at which stage the precompiled queries will be generated. Defaults to `publish`. | | DbContextName | The derived `DbContext` class to use. Class name only or fully qualified with namespaces. If this option is omitted, EF Core will perform generation for all context classes in the project. | @@ -38,6 +38,9 @@ If the project specifies `true` then by default the MSB | EFOutputDir | The folder to put the generated files before the project is compiled. If this option is omitted, EF Core will use `$(IntermediateOutputPath)`. | | EFNullable | Whether nullable reference types will be used in the generated code. If this option is omitted, EF Core will use `$(Nullable)`. | +> [!NOTE] +> Starting with EF Core 11, the `EFOptimizeContext` property has been [removed](xref:core/what-is-new/ef-core-11.0/breaking-changes#ef-optimize-context-removed). The `EFScaffoldModelStage` and `EFPrecompileQueriesStage` properties now work independently and don't require an additional enablement flag. + ## Limitations * When using the integration during the `publish` stage also set the rid in the startup project (e.g. \win-x64\) diff --git a/entity-framework/core/managing-schemas/migrations/projects.md b/entity-framework/core/managing-schemas/migrations/projects.md index a306bde830..657459747e 100644 --- a/entity-framework/core/managing-schemas/migrations/projects.md +++ b/entity-framework/core/managing-schemas/migrations/projects.md @@ -8,7 +8,7 @@ uid: core/managing-schemas/migrations/projects # Using a Separate Migrations Project -You may want to store your migrations in a different project than the one containing your `DbContext`. You can also use this strategy to maintain multiple sets of migrations, for example, one for development and another for release-to-release upgrades. +You may want to store your migrations in a different project than the one containing your `DbContext`. This is recommended if your project uses a platform-specific project type, such as WinUI, Xamarin, MAUI, Blazor, or Azure Functions, or if it targets a specific runtime identifier (RID). You can also use this strategy to maintain multiple sets of migrations, for example, one for development and another for release-to-release upgrades. > [!TIP] > You can view this article's [sample on GitHub](https://github.com/dotnet/EntityFramework.Docs/tree/main/samples/core/Schemas/ThreeProjectMigrations). @@ -59,3 +59,6 @@ Add-Migration NewMigration -Project WebApplication1.Migrations ``` *** + +> [!TIP] +> If your application uses dependency injection, consider implementing in your migrations project. This allows the EF tools to create your `DbContext` without needing to run the startup project. For more information, see [From a design-time factory](xref:core/cli/dbcontext-creation#from-a-design-time-factory). diff --git a/entity-framework/core/managing-schemas/migrations/teams.md b/entity-framework/core/managing-schemas/migrations/teams.md index 0a99ca8231..f11152ed8c 100644 --- a/entity-framework/core/managing-schemas/migrations/teams.md +++ b/entity-framework/core/managing-schemas/migrations/teams.md @@ -2,56 +2,33 @@ title: Migrations in Team Environments - EF Core description: Best practices for managing migrations and resolving conflicts in team environments with Entity Framework Core author: SamMonoRT -ms.date: 10/30/2017 +ms.date: 02/18/2026 uid: core/managing-schemas/migrations/teams --- # Migrations in Team Environments -When working with Migrations in team environments, pay extra attention to the model snapshot file. This file can tell you if your teammate's migration merges cleanly with yours or if you need to resolve a conflict by re-creating your -migration before sharing it. +When working with Migrations in team environments, various problems can arise when migrations are added by multiple developers around the same time; note that migrations aren't simply SQL scripts but also include a snapshot of the model at the time of that migration. -## Merging +For example, imagine developer A and B both create work branches at the same time, and generate a migration in their branches. If developer A merges their branch and then developer B does the same, the latest migration (developer B's) will have a context snapshot that does not include the changes from developer A's migration. This can cause various forms of corruption in later migrations. -When you merge migrations from your teammates, you may get conflicts in your model snapshot file. If both changes are unrelated, the merge is trivial and the two migrations can coexist. For example, you may get a merge conflict in the customer entity type configuration that looks like this: +As a result, it is highly recommended to coordinate in advance and to avoid working concurrently on migrations in multiple branches when possible. -```output -<<<<<<< Mine -b.Property("Deactivated"); -======= -b.Property("LoyaltyPoints"); ->>>>>>> Theirs -``` +## Detecting diverged migration trees -Since both of these properties need to exist in the final model, complete the merge by adding both properties. In many -cases, your version control system may automatically merge such changes for you. +> [!NOTE] +> This feature is being introduced in EF Core 11 from preview-3 onwards. -```csharp -b.Property("Deactivated"); -b.Property("LoyaltyPoints"); -``` +Starting with EF 11, the model snapshot records the ID of the latest migration. This means that if two developers each create a migration on separate branches, merging those branches will produce a source control conflict in the model snapshot file — since both branches modify the latest migration ID. This conflict is an important signal: it tells you that the migration trees have diverged, and one of them must be discarded before proceeding. -In these cases, your migration and your teammate's migration are independent of each other. Since either of them could be applied first, you don't need to make any additional changes to your migration before sharing it with your team. +To resolve this, follow the steps in [Resolving diverged migration trees](#resolving-diverged-migration-trees) below: abort the merge, remove your migration (keeping your model changes), merge your teammate's changes, and then re-add your migration. -## Resolving conflicts +## Resolving diverged migration trees -Sometimes you encounter a true conflict when merging the model snapshot model. For example, you and your teammate may each have renamed the same property. - -```output -<<<<<<< Mine -b.Property("Username"); -======= -b.Property("Alias"); ->>>>>>> Theirs -``` - -If you encounter this kind of conflict, resolve it by re-creating your migration. Follow these steps: +If, when merging a branch, a diverged migration tree is detected, resolve it by re-creating your migration. Follow these steps: 1. Abort the merge and rollback to your working directory before the merge 2. Remove your migration (but keep your model changes) 3. Merge your teammate's changes into your working directory 4. Re-add your migration -After doing this, the two migrations can be applied in the correct order. Their migration is applied first, renaming -the column to *Alias*, thereafter your migration renames it to *Username*. - -Your migration can safely be shared with the rest of the team. +After doing this, your migration is cleanly based on top of any migrations that have been added in the other branch, and its context snapshot contains all previous changes. Your migration can now be safely shared with the rest of the team. diff --git a/entity-framework/core/modeling/relationships/foreign-and-principal-keys.md b/entity-framework/core/modeling/relationships/foreign-and-principal-keys.md index 5ff361945a..0851e82de7 100644 --- a/entity-framework/core/modeling/relationships/foreign-and-principal-keys.md +++ b/entity-framework/core/modeling/relationships/foreign-and-principal-keys.md @@ -189,6 +189,32 @@ This can be changed in the model building API using `HasConstraintName`. For exa > [!TIP] > The constraint name is not used by the EF runtime. It is only used when creating a database schema using [EF Core Migrations](xref:core/managing-schemas/migrations/index). +### Excluding foreign key constraints from migrations + +> [!NOTE] +> This feature is being introduced in EF Core 11, which is currently in preview. + +Sometimes it is useful to have the foreign key relationship represented in the EF model, but without creating the corresponding foreign key constraint in the database. This can happen with legacy databases where constraints don't exist, or in data synchronization scenarios where the order of inserting related entities might temporarily violate referential integrity constraints. In these cases, use `ExcludeForeignKeyFromMigrations` to prevent EF from generating the foreign key constraint in migrations (and `EnsureCreated`): + +```csharp +modelBuilder.Entity() + .HasMany(e => e.Posts) + .WithOne(e => e.Blog) + .HasForeignKey(e => e.BlogId) + .ExcludeForeignKeyFromMigrations(); +``` + +With this configuration, EF will not create a foreign key constraint in the database, but the relationship is still tracked in the EF model and can be used normally for loading related data, change tracking, etc. EF will still create a database index for the foreign key column, since indexes benefit queries regardless of whether a constraint exists. + +To apply this across all foreign keys in the model (e.g. to globally disable all foreign key constraints), you can iterate over all foreign keys in `OnModelCreating`: + +```csharp +foreach (var foreignKey in modelBuilder.Model.GetEntityTypes().SelectMany(e => e.GetForeignKeys())) +{ + foreignKey.SetIsExcludedFromMigrations(true); +} +``` + ### Indexes for foreign keys By convention, EF creates a database index for the property or properties of a foreign key. See [_Model building conventions_](xref:core/modeling/relationships/conventions) for more information about the types of indexes created by convention. diff --git a/entity-framework/core/providers/sql-server/functions.md b/entity-framework/core/providers/sql-server/functions.md index 5f5b801224..f7dae58129 100644 --- a/entity-framework/core/providers/sql-server/functions.md +++ b/entity-framework/core/providers/sql-server/functions.md @@ -232,6 +232,13 @@ stringValue.Trim() | LTRIM( stringValue.TrimEnd() | RTRIM(@stringValue) stringValue.TrimStart() | LTRIM(@stringValue) +## JSON functions + +.NET | SQL | Added in +----------------------------------------------------------------- | --------------------------------------------------------- | -------- +EF.Functions.JsonContains(json, searchValue, path?, searchMode?) | JSON_CONTAINS(@json, @searchValue, @path?, @searchMode?) | EF 11.0 +EF.Functions.JsonPathExists(json, path) | JSON_PATH_EXISTS(@json, @path) | EF 11.0 + ## Miscellaneous functions .NET | SQL | Added in diff --git a/entity-framework/core/providers/sql-server/vector-search.md b/entity-framework/core/providers/sql-server/vector-search.md index 29843fc23f..77f510c409 100644 --- a/entity-framework/core/providers/sql-server/vector-search.md +++ b/entity-framework/core/providers/sql-server/vector-search.md @@ -66,6 +66,9 @@ await context.SaveChangesAsync(); Once you have embeddings saved to your database, you're ready to perform vector similarity search over them. +> [!NOTE] +> Starting with EF Core 11, vector properties are not loaded by default when querying entities, since vectors are typically large and are rarely needed to be read back. Prior to EF Core 11, vector properties were always loaded like any other property. + ## Exact search with VECTOR_DISTANCE() The [`EF.Functions.VectorDistance()`](/sql/t-sql/functions/vector-distance-transact-sql) function computes the *exact* distance between two vectors. Use it to perform similarity search for a given user query: @@ -126,7 +129,7 @@ Once you have a vector index, use the `VectorSearch()` extension method on your ```csharp var blogs = await context.Blogs - .VectorSearch(b => b.Embedding, "cosine", embedding, topN: 5) + .VectorSearch(b => b.Embedding, embedding, "cosine", topN: 5) .ToListAsync(); foreach (var (blog, score) in blogs) @@ -138,7 +141,7 @@ foreach (var (blog, score) in blogs) This translates to the following SQL: ```sql -SELECT [v].[Id], [v].[Embedding], [v].[Name] +SELECT [v].[Id], [v].[Name], [v].[Distance] FROM VECTOR_SEARCH([Blogs], 'Embedding', @__embedding, 'metric = cosine', @__topN) ``` @@ -148,7 +151,7 @@ The `topN` parameter specifies the maximum number of results to return. ```csharp var searchResults = await context.Blogs - .VectorSearch(b => b.Embedding, "cosine", embedding, topN: 5) + .VectorSearch(b => b.Embedding, embedding, "cosine", topN: 5) .Where(r => r.Distance < 0.05) .Select(r => new { Blog = r.Value, Distance = r.Distance }) .ToListAsync(); @@ -206,7 +209,7 @@ This query: The query produces the following SQL: ```sql -SELECT TOP(@p3) [a0].[Id], [a0].[Content], [a0].[Embedding], [a0].[Title] +SELECT TOP(@p3) [a0].[Id], [a0].[Content], [a0].[Title] FROM FREETEXTTABLE([Articles], *, @p, @p1) AS [f] LEFT JOIN VECTOR_SEARCH( TABLE = [Articles] AS [a0], diff --git a/entity-framework/core/what-is-new/ef-core-11.0/breaking-changes.md b/entity-framework/core/what-is-new/ef-core-11.0/breaking-changes.md index 09707d279e..ece54855f2 100644 --- a/entity-framework/core/what-is-new/ef-core-11.0/breaking-changes.md +++ b/entity-framework/core/what-is-new/ef-core-11.0/breaking-changes.md @@ -22,31 +22,231 @@ This page documents API and behavior changes that have the potential to break ex | **Breaking change** | **Impact** | |:--------------------------------------------------------------------------------------------------------------- | -----------| | [Sync I/O via the Azure Cosmos DB provider has been fully removed](#cosmos-nosync) | Medium | +| [Microsoft.Data.SqlClient has been updated to 7.0](#sqlclient-7) | Medium | +| [EF Core now throws by default when no migrations are found](#migrations-not-found) | Low | +| [`EFOptimizeContext` MSBuild property has been removed](#ef-optimize-context-removed) | Low | +| [EF tools packages no longer reference Microsoft.EntityFrameworkCore.Design](#ef-tools-no-design-dep) | Low | +| [SqlVector properties are no longer loaded by default](#sqlvector-not-auto-loaded) | Low | +| [Cosmos: empty owned collections now return an empty collection instead of null](#cosmos-empty-collections) | Low | -### Medium-impact changes +## Medium-impact changes -#### Sync I/O via the Azure Cosmos DB provider has been fully removed +### Sync I/O via the Azure Cosmos DB provider has been fully removed [Tracking Issue #37059](https://github.com/dotnet/efcore/issues/37059) -##### Old behavior +#### Old behavior Synchronous I/O via the Azure Cosmos DB provider has been unsupported since EF 9.0 ([note](/ef/core/what-is-new/ef-core-9.0/breaking-changes#cosmos-nosync)); calling any sync I/O API - like `ToList` or `SaveChanges` threw an exception, unless a special opt-in was configured. When the opt-in was configured, sync I/O APIs worked as before, causing the provider to perform "sync-over-async" blocking against the Azure Cosmos DB SDK, which could result in deadlocks and other performance issues. -##### New behavior +#### New behavior Starting with EF Core 11.0, EF now always throws when a synchronous I/O API is called. There is no way to opt back into using sync I/O APIs. -##### Why +#### Why Synchronous blocking on asynchronous methods ("sync-over-async") is highly discouraged, and can lead to deadlock and other performance problems. Since the Azure Cosmos DB SDK only supports async methods, so does the EF Cosmos provider. -##### Mitigations +#### Mitigations Convert your code to use async I/O APIs instead of sync I/O ones. For example, replace calls to `SaveChanges()` with `await SaveChangesAsync()`. + + +### Microsoft.Data.SqlClient has been updated to 7.0 + +#### Old behavior + +EF Core 10 used [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient/) 6.x, which included Azure/Entra ID authentication dependencies (such as `Azure.Core`, `Azure.Identity`, and `Microsoft.Identity.Client`) in the core package. + +#### New behavior + +EF Core 11 now depends on [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient/) 7.0. This version removes Azure/Entra ID (formerly Azure Active Directory) authentication dependencies from the core package. If your application uses Entra ID authentication (for example, `ActiveDirectoryDefault`, `ActiveDirectoryInteractive`, `ActiveDirectoryManagedIdentity`, or `ActiveDirectoryServicePrincipal`), you must now install the [`Microsoft.Data.SqlClient.Extensions.Azure`](https://www.nuget.org/packages/Microsoft.Data.SqlClient.Extensions.Azure/) package separately. + +In addition, `SqlAuthenticationMethod.ActiveDirectoryPassword` has been marked as obsolete. + +For more details, see the [Microsoft.Data.SqlClient 7.0 release notes](https://github.com/dotnet/SqlClient/blob/main/release-notes/7.0/7.0.0.md). + +#### Why + +This change was made in [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient/) to reduce dependency bloat for applications that don't use Azure authentication, which is especially beneficial for containerized deployments and local development. + +#### Mitigations + +If your application uses Entra ID authentication with SQL Server, add a reference to the `Microsoft.Data.SqlClient.Extensions.Azure` package in your project: + +```xml + +``` + +No code changes are required beyond adding this package reference. If you use `SqlAuthenticationMethod.ActiveDirectoryPassword`, migrate to a modern authentication method such as `ActiveDirectoryDefault` or `ActiveDirectoryInteractive`. + +## Low-impact changes + + + +### EF Core now throws by default when no migrations are found + +[Tracking Issue #35218](https://github.com/dotnet/efcore/issues/35218) + +#### Old behavior + +Previously, when calling or on a database with no migrations in the assembly, EF Core logged an informational message and returned without applying any changes. + +#### New behavior + +Starting with EF Core 11.0, EF Core throws an exception by default when no migrations are found in the assembly. This is consistent with the `PendingModelChangesWarning` behavior [introduced in EF 9.0](xref:core/what-is-new/ef-core-9.0/breaking-changes#pending-model-changes). + +#### Why + +Calling `Migrate()` or `MigrateAsync()` when no migrations exist typically indicates a misconfiguration. Rather than silently continuing and leaving the database in a potentially incorrect state, EF Core now alerts developers to this issue immediately. + +#### Mitigations + +If you intentionally call `Migrate()` without having any migrations (for example, because you manage the database schema through other means), remove the `Migrate()` call or suppress the exception by configuring warnings: + +```csharp +options.ConfigureWarnings(w => w.Ignore(RelationalEventId.MigrationsNotFound)) +``` + +Or to log the event instead of throwing: + +```csharp +options.ConfigureWarnings(w => w.Log(RelationalEventId.MigrationsNotFound)) +``` + + + +### `EFOptimizeContext` MSBuild property has been removed + +[Tracking Issue #35079](https://github.com/dotnet/efcore/issues/35079) + +#### Old behavior + +Previously, the `EFOptimizeContext` MSBuild property could be set to `true` to enable compiled model and precompiled query code generation during build or publish: + +```xml +true +``` + +#### New behavior + +Starting with EF Core 11.0, the `EFOptimizeContext` MSBuild property has been removed. Code generation is now controlled exclusively through the `EFScaffoldModelStage` and `EFPrecompileQueriesStage` properties. When `PublishAOT` is set to `true`, code generation is automatically enabled during publish without needing any additional property. + +#### Why + +The `EFScaffoldModelStage` and `EFPrecompileQueriesStage` properties already provide fine-grained control over when code generation occurs. `EFOptimizeContext` was a redundant enablement gate. + +#### Mitigations + +Replace usages of `EFOptimizeContext` with the `EFScaffoldModelStage` and `EFPrecompileQueriesStage` properties. These can be set to `publish` or `build` to control at which stage code generation occurs: + +```xml +publish +publish +``` + +Any other value (for example, `none`) disables the corresponding generation. + +If you have `PublishAOT` set to `true`, code generation is automatically enabled during publish and no additional configuration is needed. + + + +### EF tools packages no longer reference Microsoft.EntityFrameworkCore.Design + +[Tracking Issue #37739](https://github.com/dotnet/efcore/issues/37739) + +#### Old behavior + +Previously, the `Microsoft.EntityFrameworkCore.Tools` and `Microsoft.EntityFrameworkCore.Tasks` NuGet packages had a dependency on `Microsoft.EntityFrameworkCore.Design`. + +#### New behavior + +Starting with EF Core 11.0, the `Microsoft.EntityFrameworkCore.Tools` and `Microsoft.EntityFrameworkCore.Tasks` NuGet packages no longer have a dependency on `Microsoft.EntityFrameworkCore.Design`. + +#### Why + +There was no hard dependency on the code in `Microsoft.EntityFrameworkCore.Design`, and this dependency was causing issues when using the latest `Microsoft.EntityFrameworkCore.Tools` with projects targeting older frameworks. + +#### Mitigations + +If your project relies on `Microsoft.EntityFrameworkCore.Design` being brought in transitively through the tools packages, add a direct reference to it in your project: + +```xml + +``` + + + +### SqlVector properties are no longer loaded by default + +[Tracking Issue #37279](https://github.com/dotnet/efcore/issues/37279) + +#### Old behavior + +Previously, when querying entities with `SqlVector` properties, EF Core included the vector column in `SELECT` statements and populated the property on the returned entity. + +#### New behavior + +Starting with EF Core 11.0, `SqlVector` properties are no longer included in `SELECT` statements when materializing entities. The property will be `null` on returned entities. + +Vector properties can still be used in `WHERE` and `ORDER BY` clauses—including with `VectorDistance()` and `VectorSearch()`; they just won't be included in the entity projection. + +#### Why + +Vector columns can be very large, containing hundreds or thousands of floating-point values. In the vast majority of cases, vectors are written to the database and then used for search, without needing to be read back. Excluding them from `SELECT` by default avoids unnecessary data transfer. + +#### Mitigations + +> [!NOTE] +> A mechanism for opting vector properties back into automatic loading will be introduced later in the EF Core 11 release. + +If you need to read back vector values, use an explicit projection: + +```csharp +var embeddings = await context.Blogs + .Select(b => new { b.Id, b.Embedding }) + .ToListAsync(); +``` + + + +### Cosmos: empty owned collections now return an empty collection instead of null + +[Tracking Issue #36577](https://github.com/dotnet/efcore/issues/36577) + +#### Old behavior + +Previously, when querying entities via the Azure Cosmos DB provider where an owned collection contained no items, the collection property was `null` on the materialized entity. + +#### New behavior + +Starting with EF Core 11.0, the Azure Cosmos DB provider correctly initializes empty owned collections, returning an empty collection instead of `null`. + +#### Why + +The previous behavior of materializing empty owned collections as `null` was a bug. + +#### Mitigations + +If your code explicitly checks owned collection properties for `null` to detect that the collection is empty, those checks can simply be removed, since the collection is now always initialized: + +```csharp +// Before +if (entity.OwnedCollection is null or { Count: 0 }) +{ + // treated as empty +} + +// After +if (entity.OwnedCollection is { Count: 0 }) +{ + // treated as empty +} +``` + ## Microsoft.Data.Sqlite breaking changes diff --git a/entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md b/entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md index 6842144aeb..1783c0a7a6 100644 --- a/entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md +++ b/entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md @@ -83,8 +83,87 @@ For more information on inheritance mapping strategies, see [Inheritance](xref:c Complex types are now fully supported in the Azure Cosmos DB provider, embedded as nested JSON objects or arrays. For more information, [see the Cosmos DB section below](#cosmos-complex-types). + + +### Stabilization and bug fixes + +Significant effort has gone into making sure that complex type support is stable and bug-free, to unblock using complex types as an alternative to the owned entity mapping approach. Bugs fixed include: + +* [Error querying on complex type whose container is mapped to a table and a view](https://github.com/dotnet/efcore/issues/34706) +* [Problem with ComplexProperty in EF9, when using the TPT approach](https://github.com/dotnet/efcore/issues/35392) +* [Comparison of complex types does not compare properties within nested complex types](https://github.com/dotnet/efcore/issues/37391) +* [Assignment of complex type does not assign nested properties correctly (ExecuteUpdate)](https://github.com/dotnet/efcore/issues/37395) +* [Map two classes with same nullable complex properties to same column → NullReferenceException](https://github.com/dotnet/efcore/issues/37335) +* [Complex property stored as JSON marked non-nullable in TPH class hierarchy](https://github.com/dotnet/efcore/issues/37404) +* [EntityEntry.ReloadAsync throws when nullable complex property is null](https://github.com/dotnet/efcore/issues/37559) +* [Unnecessary columns in SQL with Complex Types + object closures in projections](https://github.com/dotnet/efcore/issues/37551) + ## LINQ and SQL translation + + +### Better SQL for to-one joins + +EF Core 11 generates better SQL when querying with to-one (reference) navigation includes in two ways. + +First, when using split queries (`AsSplitQuery()`), EF previously added unnecessary joins to reference navigations in the SQL generated for collection queries. For example, consider the following query: + +```csharp +var blogs = context.Blogs + .Include(b => b.BlogType) + .Include(b => b.Posts) + .AsSplitQuery() + .ToList(); +``` + +EF Core previously generated a split query for `Posts` that unnecessarily joined `BlogType`: + +```sql +-- Before EF Core 11 +SELECT [p].[Id], [p].[BlogId], [p].[Title], [b].[Id], [b0].[Id] +FROM [Blogs] AS [b] +INNER JOIN [BlogType] AS [b0] ON [b].[BlogTypeId] = [b0].[Id] +INNER JOIN [Post] AS [p] ON [b].[Id] = [p].[BlogId] +ORDER BY [b].[Id], [b0].[Id] +``` + +In EF Core 11, the unneeded join is pruned: + +```sql +-- EF Core 11 +SELECT [p].[Id], [p].[BlogId], [p].[Title], [b].[Id] +FROM [Blogs] AS [b] +INNER JOIN [Post] AS [p] ON [b].[Id] = [p].[BlogId] +ORDER BY [b].[Id] +``` + +Second, EF no longer adds redundant keys from reference navigations to `ORDER BY` clauses. Because a reference navigation's key is functionally determined by the parent entity's key (via the foreign key), it does not need to appear separately. For example: + +```csharp +var blogs = context.Blogs + .Include(b => b.Owner) + .Include(b => b.Posts) + .ToList(); +``` + +EF Core previously included `[p].[PersonId]` in the `ORDER BY`, even though `[b].[BlogId]` already uniquely identifies the row: + +```sql +-- Before EF Core 11 +ORDER BY [b].[BlogId], [p].[PersonId] +``` + +In EF Core 11, the redundant column is omitted: + +```sql +-- EF Core 11 +ORDER BY [b].[BlogId] +``` + +Both optimizations can have a significant positive impact on query performance, especially when multiple reference navigations are included. A simple, common split query scenario showed a **29% improvement in querying performance**, as the database no longer has to perform the to-one join; single queries are also significantly improved by the removal of the ORDER BY, even if a bit less: one scenario showed a **22% improvement**. + +More details on the benchmark are available [here](https://github.com/dotnet/efcore/issues/29182#issuecomment-4231140289), and as always, actual performance in your application will vary based on your schema, data and a variety of other factors. + ### MaxBy and MinBy @@ -110,6 +189,211 @@ ORDER BY ( Similarly, `MinByAsync` orders ascending and returns the element with the minimum value for the key selector. +### EF.Functions.JsonPathExists() + +EF Core 11 introduces `EF.Functions.JsonPathExists()`, which checks whether a given JSON path exists in a JSON document. On SQL Server, this translates to the [`JSON_PATH_EXISTS`](/sql/t-sql/functions/json-path-exists-transact-sql) function (available since SQL Server 2022). + +The following query filters blogs to those whose JSON data contains an `OptionalInt` property: + +```csharp +var blogs = await context.Blogs + .Where(b => EF.Functions.JsonPathExists(b.JsonData, "$.OptionalInt")) + .ToListAsync(); +``` + +This generates the following SQL: + +```sql +SELECT [b].[Id], [b].[Name], [b].[JsonData] +FROM [Blogs] AS [b] +WHERE JSON_PATH_EXISTS([b].[JsonData], N'$.OptionalInt') = 1 +``` + +`EF.Functions.JsonPathExists()` accepts a JSON value and a JSON path to check for. It can be used with scalar string properties, complex types, and owned entity types mapped to JSON columns. + +For the full `JSON_PATH_EXISTS` SQL Server documentation, see [`JSON_PATH_EXISTS`](/sql/t-sql/functions/json-path-exists-transact-sql). + +## SQL Server + + + +### VECTOR_SEARCH() and vector indexes + +> [!WARNING] +> `VECTOR_SEARCH()` and vector indexes are currently experimental features in SQL Server and are subject to change. The APIs in EF Core for these features are also subject to change. + +In EF Core 10, we introduced translation for `EF.Functions.VectorDistance()`, which is a scalar function that computes the distance between two vectors. This function can be used in LINQ queries for vector similarity search, allowing you to find the most similar embeddings to a given embedding. However, `VectorDistance()` computes an _exact_ distance between the given vectors. + +When querying large datasets, SQL Server 2025 also supports performing _approximate_ search over a [vector index](/sql/t-sql/statements/create-vector-index-transact-sql), which provides much better performance at the expense of returning items that are approximately similar - rather than exactly similar - to the query. EF 11 now supports creating vector indexes through migrations: + +```csharp +protected override void OnModelCreating(ModelBuilder modelBuilder) +{ + modelBuilder.Entity() + .HasVectorIndex(b => b.Embedding, "cosine"); +} +``` + +Once you have a vector index, you can use the `VectorSearch()` extension method on your `DbSet` to perform an approximate search: + +```csharp +var blogs = await context.Blogs + .VectorSearch(b => b.Embedding, embedding, "cosine", topN: 5) + .ToListAsync(); +``` + +This translates to the SQL Server [`VECTOR_SEARCH()`](/sql/t-sql/functions/vector-search-transact-sql) table-valued function, which performs an approximate search over the vector index. The `topN` parameter specifies the number of results to return. + +`VectorSearch()` returns `VectorSearchResult`, allowing you to access the distance alongside the entity. + +For more information, see the [full documentation on vector search](xref:core/providers/sql-server/vector-search). + + + +### Vector properties not loaded by default + +EF Core 11 changes how vector properties are loaded: `SqlVector` columns are no longer included in `SELECT` statements when materializing entities. Since vectors can be quite large—containing hundreds or thousands of floating-point numbers—this avoids unnecessary data transfer in the common case where vectors are ingested and used for search but not read back. + +```csharp +// Vector column is excluded from the projected entity +var blogs = await context.Blogs.OrderBy(b => b.Name).ToListAsync(); +// Generates: SELECT [b].[Id], [b].[Name] FROM [Blogs] AS [b] ... + +// Explicit projection still loads the vector +var embeddings = await context.Blogs + .Select(b => new { b.Id, b.Embedding }) + .ToListAsync(); +``` + +Vector properties can still be used in `WHERE` and `ORDER BY` clauses—including with `VectorDistance()` and `VectorSearch()`—and EF will correctly include them in the SQL, just not in the entity projection. + +This optimization can have a dramatic impact on application speed: a minimal benchmark showed an almost 9x (that's nine-fold) increase in performance, and that's while running against a local database. The optimization is even more impactful as latency to the database grows: when executing against a remote Azure SQL database, an improvement of around 22x was observed. More details on the benchmark are available [here](https://github.com/dotnet/efcore/issues/37279#issuecomment-4232243062), and as always, actual performance in your application will vary based on your entity, vector properties and latency. + + + +### Full-text search improvements + +#### Full-text search catalog and index creation + +SQL Server's [full-text search](/sql/relational-databases/search/full-text-search) requires a full-text catalog and index to be set up on your database before you can use it. EF 11 now allows configuring full-text catalogs and indexes in your model, so that [EF migrations](xref:core/managing-schemas/migrations/index) can automatically create and manage them for you: + +```csharp +// In your OnModelCreating: +modelBuilder.HasFullTextCatalog("ftCatalog"); + +modelBuilder.Entity() + .HasFullTextIndex(b => b.FullName) + .HasKeyIndex("PK_Blogs") + .OnCatalog("ftCatalog"); +``` + +This generates the following SQL in a migration: + +```sql +CREATE FULLTEXT CATALOG [ftCatalog]; +CREATE FULLTEXT INDEX ON [Blogs]([FullName]) KEY INDEX [PK_Blogs] ON [ftCatalog]; +``` + +Previously, full-text catalog and index creation had to be managed manually by adding SQL to migrations. For full details on setting up full-text catalogs and indexes, see the [full-text search documentation](xref:core/providers/sql-server/full-text-search#setting-up-full-text-search). + + + +#### Full-text search table-valued functions + +EF Core has long provided support for SQL Server's full-text search predicates `FREETEXT()` and `CONTAINS()`, via `EF.Functions.FreeText()` and `EF.Functions.Contains()`. These predicates can be used in LINQ `Where()` clauses to filter results based on search criteria. + +However, SQL Server also has table-valued function versions of these functions, [`FREETEXTTABLE()`](/sql/relational-databases/system-functions/freetexttable-transact-sql) and [`CONTAINSTABLE()`](/sql/relational-databases/system-functions/containstable-transact-sql), which also return a ranking score along with the results, providing additional flexibility over the predicate versions. EF 11 now supports these table-valued functions: + +```csharp +// Using FreeTextTable with a search query +var results = await context.Blogs + .FreeTextTable(b => b.FullName, "John") + .Select(r => new { Blog = r.Value, Rank = r.Rank }) + .OrderByDescending(r => r.Rank) + .ToListAsync(); + +// Using ContainsTable with a search query +var results = await context.Blogs + .ContainsTable(b => b.FullName, "John") + .Select(r => new { Blog = r.Value, Rank = r.Rank }) + .OrderByDescending(r => r.Rank) + .ToListAsync(); +``` + +Both methods return `FullTextSearchResult`, giving you access to both the entity and the ranking value from SQL Server's full-text engine. This allows for more sophisticated result ordering and filtering based on relevance scores. + +For more information, see the [full documentation on full-text search](xref:core/providers/sql-server/full-text-search). + + + +### Contains operations using JSON_CONTAINS + +SQL Server 2025 introduced the [`JSON_CONTAINS`](/sql/t-sql/functions/json-contains-transact-sql) function, which checks whether a value exists in a JSON document. Starting with EF Core 11, when targeting SQL Server 2025, LINQ `Contains` queries over primitive (or scalar) collections stored as JSON are translated to use this function, replacing the previous, less efficient `OPENJSON`-based translation. + +The following query checks whether a blog's `Tags` collection contains a specific tag: + +```csharp +var blogs = await context.Blogs + .Where(b => b.Tags.Contains("ef-core")) + .ToListAsync(); +``` + +Before EF 11 - or when targeting older SQL Server versions - this generates the following SQL: + +```sql +SELECT [b].[Id], [b].[Name], [b].[Tags] +FROM [Blogs] AS [b] +WHERE N'ef-core' IN ( + SELECT [t].[value] + FROM OPENJSON([b].[Tags]) WITH ([value] nvarchar(max) '$') AS [t] +) +``` + +With EF 11, configure EF to target SQL Server 2025 by setting the compatibility level as follows: + +```csharp +protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) + => optionsBuilder + .UseSqlServer("", o => o.UseCompatibilityLevel(170)); +``` + +At that point, EF will instead generate the following SQL: + +```sql +SELECT [b].[Id], [b].[Name], [b].[Tags] +FROM [Blogs] AS [b] +WHERE JSON_CONTAINS([b].[Tags], 'ef-core') = 1 +``` + +`JSON_CONTAINS()` can notably make use of a [JSON index](/sql/t-sql/statements/create-json-index-transact-sql), if one is defined. + +> [!NOTE] +> `JSON_CONTAINS` does not support searching for null values. As a result, this translation is only applied when EF can determine that at least one side is non-nullable — either the item being searched for (e.g. a non-null constant or a non-nullable column), or the collection's elements. When this cannot be determined, EF falls back to the previous `OPENJSON`-based translation. + +#### EF.Functions.JsonContains() + +In the section above, EF Core automatically translates LINQ `Contains` queries over primitive collections to use the SQL Server `JSON_CONTAINS` function. In some cases, however, you may want to directly invoke `JSON_CONTAINS` yourself, for example to search for a value at a specific path, or to specify a search mode. For these cases, EF Core 11 introduces `EF.Functions.JsonContains()`. + +The following query checks whether a blog's JSON data contains a specific value at a given path: + +```csharp +var blogs = await context.Blogs + .Where(b => EF.Functions.JsonContains(b.JsonData, 8, "$.Rating") == 1) + .ToListAsync(); +``` + +This generates the following SQL: + +```sql +SELECT [b].[Id], [b].[Name], [b].[JsonData] +FROM [Blogs] AS [b] +WHERE JSON_CONTAINS([b].[JsonData], 8, N'$.Rating') = 1 +``` + +`EF.Functions.JsonContains()` accepts the JSON value to search in, the value to search for, and optionally a JSON path and a search mode. It can be used with scalar string properties, complex types, and owned entity types mapped to JSON columns. + +For the full `JSON_CONTAINS` SQL Server documentation, see [`JSON_CONTAINS`](/sql/t-sql/functions/json-contains-transact-sql). + ## Cosmos DB @@ -211,6 +495,34 @@ This feature was contributed by [@JoasE](https://github.com/JoasE) - many thanks ## Migrations + + +### Excluding foreign key constraints from migrations + +It is now possible to configure a foreign key relationship in the EF model while preventing the corresponding database constraint from being created by migrations. This is useful for legacy databases without existing constraints, or in data synchronization scenarios where referential integrity constraints might conflict with the synchronization order: + +```csharp +modelBuilder.Entity() + .HasMany(e => e.Posts) + .WithOne(e => e.Blog) + .HasForeignKey(e => e.BlogId) + .ExcludeForeignKeyFromMigrations(); +``` + +The relationship is fully supported in EF for queries, change tracking, etc. Only the foreign key constraint in the database is suppressed; a database index is still created on the foreign key column. + +For more information, see [Excluding foreign key constraints from migrations](xref:core/modeling/relationships/foreign-and-principal-keys#excluding-foreign-key-constraints-from-migrations). + + + +### Latest migration ID recorded in model snapshot + +When working in team environments, it's common for multiple developers to create migrations on separate branches. When these branches are merged, the migration trees can diverge, leading to issues that are sometimes difficult to detect. + +Starting with EF Core 11, the model snapshot now records the ID of the latest migration. When two developers create migrations on divergent branches, both branches will modify this value in the model snapshot, causing a source control merge conflict. This conflict alerts the team that they need to resolve the divergence - typically by discarding one of the migration trees and creating a new, unified migration. + +For more information on managing migrations in team environments, see [Migrations in Team Environments](xref:core/managing-schemas/migrations/teams). + ### Create and apply migrations in one step @@ -263,136 +575,6 @@ Remove-Migration -Offline Drop-Database -Connection "Server=test;Database=MyDb;..." -Force ``` -## SQL Server - - - -### VECTOR_SEARCH() and vector indexes - -> [!WARNING] -> `VECTOR_SEARCH()` and vector indexes are currently experimental features in SQL Server and are subject to change. The APIs in EF Core for these features are also subject to change. - -In EF Core 10, we introduced translation for `EF.Functions.VectorDistance()`, which is a scalar function that computes the distance between two vectors. This function can be used in LINQ queries for vector similarity search, allowing you to find the most similar embeddings to a given embedding. However, `VectorDistance()` computes an _exact_ distance between the given vectors. - -When querying large datasets, SQL Server 2025 also supports performing _approximate_ search over a [vector index](/sql/t-sql/statements/create-vector-index-transact-sql), which provides much better performance at the expense of returning items that are approximately similar - rather than exactly similar - to the query. EF 11 now supports creating vector indexes through migrations: - -```csharp -protected override void OnModelCreating(ModelBuilder modelBuilder) -{ - modelBuilder.Entity() - .HasVectorIndex(b => b.Embedding, "cosine"); -} -``` - -Once you have a vector index, you can use the `VectorSearch()` extension method on your `DbSet` to perform an approximate search: - -```csharp -var blogs = await context.Blogs - .VectorSearch(b => b.Embedding, "cosine", embedding, topN: 5) - .ToListAsync(); -``` - -This translates to the SQL Server [`VECTOR_SEARCH()`](/sql/t-sql/functions/vector-search-transact-sql) table-valued function, which performs an approximate search over the vector index. The `topN` parameter specifies the number of results to return. - -`VectorSearch()` returns `VectorSearchResult`, allowing you to access the distance alongside the entity. - -For more information, see the [full documentation on vector search](xref:core/providers/sql-server/vector-search). - - - -### Full-text search improvements - -#### Full-text search catalog and index creation - -SQL Server's [full-text search](/sql/relational-databases/search/full-text-search) requires a full-text catalog and index to be set up on your database before you can use it. EF 11 now allows configuring full-text catalogs and indexes in your model, so that [EF migrations](xref:core/managing-schemas/migrations/index) can automatically create and manage them for you: - -```csharp -// In your OnModelCreating: -modelBuilder.HasFullTextCatalog("ftCatalog"); - -modelBuilder.Entity() - .HasFullTextIndex(b => b.FullName) - .HasKeyIndex("PK_Blogs") - .OnCatalog("ftCatalog"); -``` - -This generates the following SQL in a migration: - -```sql -CREATE FULLTEXT CATALOG [ftCatalog]; -CREATE FULLTEXT INDEX ON [Blogs]([FullName]) KEY INDEX [PK_Blogs] ON [ftCatalog]; -``` - -Previously, full-text catalog and index creation had to be managed manually by adding SQL to migrations. For full details on setting up full-text catalogs and indexes, see the [full-text search documentation](xref:core/providers/sql-server/full-text-search#setting-up-full-text-search). - -#### Full-text search table-valued functions - -EF Core has long provided support for SQL Server's full-text search predicates `FREETEXT()` and `CONTAINS()`, via `EF.Functions.FreeText()` and `EF.Functions.Contains()`. These predicates can be used in LINQ `Where()` clauses to filter results based on search criteria. - -However, SQL Server also has table-valued function versions of these functions, [`FREETEXTTABLE()`](/sql/relational-databases/system-functions/freetexttable-transact-sql) and [`CONTAINSTABLE()`](/sql/relational-databases/system-functions/containstable-transact-sql), which also return a ranking score along with the results, providing additional flexibility over the predicate versions. EF 11 now supports these table-valued functions: - -```csharp -// Using FreeTextTable with a search query -var results = await context.Blogs - .FreeTextTable(b => b.FullName, "John") - .Select(r => new { Blog = r.Value, Rank = r.Rank }) - .OrderByDescending(r => r.Rank) - .ToListAsync(); - -// Using ContainsTable with a search query -var results = await context.Blogs - .ContainsTable(b => b.FullName, "John") - .Select(r => new { Blog = r.Value, Rank = r.Rank }) - .OrderByDescending(r => r.Rank) - .ToListAsync(); -``` - -Both methods return `FullTextSearchResult`, giving you access to both the entity and the ranking value from SQL Server's full-text engine. This allows for more sophisticated result ordering and filtering based on relevance scores. - -For more information, see the [full documentation on full-text search](xref:core/providers/sql-server/full-text-search). - - - -### Translate Contains over primitive collections using JSON_CONTAINS - -SQL Server 2025 introduced the [`JSON_CONTAINS`](/sql/t-sql/functions/json-contains-transact-sql) function, which checks whether a value exists in a JSON document. Starting with EF Core 11, when targeting SQL Server 2025, LINQ `Contains` queries over primitive (or scalar) collections stored as JSON are translated to use this function, replacing the previous, less efficient `OPENJSON`-based translation. - -The following query checks whether a blog's `Tags` collection contains a specific tag: - -```csharp -var blogs = await context.Blogs - .Where(b => b.Tags.Contains("ef-core")) - .ToListAsync(); -``` - -Before EF 11 - or when targeting older SQL Server versions - this generates the following SQL: - -```sql -SELECT [b].[Id], [b].[Name], [b].[Tags] -FROM [Blogs] AS [b] -WHERE N'ef-core' IN ( - SELECT [t].[value] - FROM OPENJSON([b].[Tags]) WITH ([value] nvarchar(max) '$') AS [t] -) -``` - -With EF 11, configure EF to target SQL Server 2025 by setting the compatibility level as follows: - -```csharp -protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) - => optionsBuilder - .UseSqlServer("", o => o.UseCompatibilityLevel(170)); -``` - -At that point, EF will instead generate the following SQL: +## Other improvements -```sql -SELECT [b].[Id], [b].[Name], [b].[Tags] -FROM [Blogs] AS [b] -WHERE JSON_CONTAINS([b].[Tags], 'ef-core') = 1 -``` - -`JSON_CONTAINS()` can notably make use of a [JSON index](/sql/t-sql/statements/create-json-index-transact-sql), if one is defined. - -> [!NOTE] -> `JSON_CONTAINS` does not support searching for null values. As a result, this translation is only applied when EF can determine that at least one side is non-nullable — either the item being searched for (e.g. a non-null constant or a non-nullable column), or the collection's elements. When this cannot be determined, EF falls back to the previous `OPENJSON`-based translation. +* The EF command-line tool now writes all logging and status messages to standard error, reserving standard output only for the command's actual expected output. For example, when generating a migration SQL script with `dotnet ef migrations script`, only the SQL is written to standard output. diff --git a/entity-framework/core/what-is-new/ef-core-9.0/breaking-changes.md b/entity-framework/core/what-is-new/ef-core-9.0/breaking-changes.md index ecd7089fe9..33c5838232 100644 --- a/entity-framework/core/what-is-new/ef-core-9.0/breaking-changes.md +++ b/entity-framework/core/what-is-new/ef-core-9.0/breaking-changes.md @@ -33,6 +33,7 @@ EF Core 9 targets .NET 8. This means that existing applications that target .NET | [SqlFunctionExpression's nullability arguments' arity validated](#sqlfunctionexpression-nullability) | Low | | [`ToString()` method now returns empty string for `null` instances](#nullable-tostring) | Low | | [Shared framework dependencies were updated to 9.0.x](#shared-framework-dependencies) | Low | +| [EF tools no longer support .NET Framework projects](#ef-tools-no-netfx) | Low | ## High-impact changes @@ -333,6 +334,28 @@ The matching dependency versions contain the latest security fixes and using the Change your app to target net9.0 to get the previous behavior. + + +### EF tools no longer support .NET Framework projects + +[Tracking Issue #37745](https://github.com/dotnet/efcore/issues/37745) + +#### Old behavior + +Previously, the EF Core tools (`dotnet-ef` CLI and Package Manager Console tools) worked with projects targeting .NET Framework. + +#### New behavior + +Starting with EF Core 9.0, the EF Core tools no longer work with projects targeting .NET Framework. The tools produce an error when the startup project targets .NET Framework. + +#### Why + +The current version of EF Core tools works with all supported EF Core versions and there are no longer any supported EF Core versions that work on .NET Framework. + +#### Mitigations + +Update your project to target .NET (e.g., .NET 8 or later). If your project currently targets .NET Framework, see the [porting guide](/dotnet/core/porting/) for information on migrating to .NET. + ## 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.