Document breaking changes for MigrationsNotFound default throw and EFOptimizeContext removal (#5282)

Co-authored-by: AndriySvyryd <6539701+AndriySvyryd@users.noreply.github.com>

Author: 2 people

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,14 +30,17 @@ If the project specifies `<PublishAot>true</PublishAot>` 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. |
 | EFTargetNamespace  | The namespace to use for all generated classes. If this option is omitted, EF Core will use `$(RootNamespace)`.                      |
 | 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. \<RuntimeIdentifier\>win-x64\</RuntimeIdentifier\>)

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

@@ -19,6 +19,8 @@ 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     |
+| [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        |
 
 ## Medium-impact changes
@@ -47,6 +49,73 @@ Convert your code to use async I/O APIs instead of sync I/O ones. For example, r
 
 ## Low-impact changes
 
+<a name="migrations-not-found"></a>
+
+### 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 <xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.Migrate*> or <xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.MigrateAsync*> 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))
+```
+
+<a name="ef-optimize-context-removed"></a>
+
+### `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
+<EFOptimizeContext Condition="'$(Configuration)'=='Release'">true</EFOptimizeContext>
+```
+
+#### 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
+<EFScaffoldModelStage>publish</EFScaffoldModelStage>
+<EFPrecompileQueriesStage>publish</EFPrecompileQueriesStage>
+```
+
+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.
+
 <a name="ef-tools-no-design-dep"></a>
 
 ### EF tools packages no longer reference Microsoft.EntityFrameworkCore.Design