From 35673882a9d0c1ffead923170a80701d936b2864 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 5 Mar 2026 06:17:02 +0000
Subject: [PATCH] Document ExcludeForeignKeyFromMigrations

Document https://github.com/dotnet/efcore/issues/15854
---
 .../foreign-and-principal-keys.md             | 26 +++++++++++++++++++
 .../core/what-is-new/ef-core-11.0/whatsnew.md | 18 +++++++++++++
 2 files changed, 44 insertions(+)

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<Blog>()
+    .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/what-is-new/ef-core-11.0/whatsnew.md b/entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md
index 7dd9c837f9..a519703cec 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
@@ -197,6 +197,24 @@ This feature was contributed by [@JoasE](https://github.com/JoasE) - many thanks
 
 ## Migrations
 
+<a name="migrations-exclude-fk"></a>
+
+### 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<Blog>()
+    .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).
+
 <a name="migrations-snapshot-latest-id"></a>
 
 ### Latest migration ID recorded in model snapshot