Document breaking changes: EF tools .NET Framework support and Design dependency (#5281)

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

Author: 2 people

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

@@ -19,27 +19,56 @@ 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 tools packages no longer reference Microsoft.EntityFrameworkCore.Design](#ef-tools-no-design-dep) | Low        |
 
-### Medium-impact changes
+## Medium-impact changes
 
 <a name="cosmos-nosync"></a>
 
-#### 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()`.
+
+## Low-impact changes
+
+<a name="ef-tools-no-design-dep"></a>
+
+### 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
+<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="11.0.0" PrivateAssets="all" />
+```

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.
 
+<a name="ef-tools-no-netfx"></a>
+
+### 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.