skip to content

In an EF Core 10 app on PostgreSQL, which packages must share EF Core's major version, and what breaks when they don't?

level: juniorimportance: should knowfreq 40%

answer

  1. providers compile against EF internals
  2. [10.0.4, 11.0.0) on the provider
  3. Design package and dotnet-ef tool
  4. NU1608 on restore
  5. net10.0 or nothing

basics

~10 s

Every EF Core package moves as one major: the Npgsql provider 10.x, Microsoft.EntityFrameworkCore.Design, test providers such as Microsoft.EntityFrameworkCore.Sqlite and the dotnet-ef tool. Mixing majors brings NU1608 warnings, tool warnings or runtime missing-member failures.

solid answer

~40 s

EF Core providers are built against EF Core's internal APIs, which change between majors, so all EF packages in an app move together. `Npgsql.EntityFrameworkCore.PostgreSQL` 10.0.3 depends on `Microsoft.EntityFrameworkCore` and `Microsoft.EntityFrameworkCore.Relational` in the range `[10.0.4, 11.0.0)` and on Npgsql 10.0.3, so any EF Core 10 patch from 10.0.4, including 10.0.12, works, while 11 does not. `Microsoft.EntityFrameworkCore.Design`, `Microsoft.EntityFrameworkCore.Sqlite` in test projects and the `dotnet-ef` tool belong on the same major; an older tool warns that its version is older than the runtime's. Forcing a package above a dependency's range raises NuGet's NU1608 warning, and can end in `MissingMethodException` or `TypeLoadException` at runtime. EF Core 10 also needs the .NET 10 runtime, so the project targets `net10.0`.

code

xml · 8 lines
xml
<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.3" />
  <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.12" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.12" />
</ItemGroup>

go deeper

for a junior

Recall that the provider, the Design package, test providers and the dotnet-ef tool all follow EF Core's major version, and EF Core 10 needs net10.0.

for a middle

Explain why providers depend on EF Core internals, how a dependency range such as [10.0.4, 11.0.0) works and what NU1608 reports.

for a senior

Show how you upgrade every EF package and the tool together, pin them in one place and diagnose a runtime missing-member failure.

for a principal

Plan major upgrades around LTS releases and third-party provider schedules, deciding when a provider lag should hold back the whole application.

## Why EF Core packages move as a set EF Core is not one package. A PostgreSQL app references a **provider**, which pulls in the core and relational packages, plus design-time packages and a command-line tool, and test projects often add another provider. Providers are compiled against EF Core's **internal** APIs, the ones marked "may be changed or removed without notice in any release". Those change between major versions, so a provider built for EF Core 9 cannot be trusted to run on EF Core 10, and the reverse. ## The packages in the clinic app | Package | Role | Version rule | |---|---|---| | `Npgsql.EntityFrameworkCore.PostgreSQL` | the provider: `UseNpgsql`, type mappings, migrations SQL | 10.x for EF Core 10 | | `Microsoft.EntityFrameworkCore`, `Microsoft.EntityFrameworkCore.Relational` | the runtime | pulled in by the provider; reference directly to pin a newer patch | | `Npgsql` | the ADO.NET driver | brought in by the provider, from 10.0.3 for provider 10.0.3 | | `Microsoft.EntityFrameworkCore.Design` | design-time services that `dotnet ef` loads from the startup project | same major as the runtime | | `Microsoft.EntityFrameworkCore.Sqlite` | provider used by some test projects | same major as the runtime | | `dotnet-ef` | the tool behind `dotnet ef migrations` and `dotnet ef dbcontext optimize` | same major, never older than the runtime | ## Patches are aligned by range, not by number The Npgsql provider is released on its own schedule. Version 10.0.3 is built against EF Core 10.0.4 and declares its EF dependencies as `[10.0.4, 11.0.0)`: any EF Core 10 patch from 10.0.4 upwards, never 11. So the provider at 10.0.3 with EF Core 10.0.12 is a normal, supported combination. Matching the **major** matters; matching the patch number does not. ## What a mismatch looks like 1. **Restore warnings.** Referencing a package version above a dependency's declared range, such as an EF Core 11 preview with the 10.x provider, produces NuGet warning **NU1608**: a package version outside a dependency constraint was detected. 2. **Tool warnings.** When the `dotnet-ef` tool is older than the project's `Microsoft.EntityFrameworkCore.Design`, commands that load the project print "The Entity Framework tools version '...' is older than that of the runtime '...'. Update the tools for the latest features and bug fixes." 3. **Runtime failures.** A provider loaded with the wrong EF major can fail on first use with `MissingMethodException` or `TypeLoadException`, when it calls an internal member that moved. 4. **Framework errors.** EF Core 10 needs the .NET 10 SDK and runtime and does not run on earlier .NET or on .NET Framework, so a `net8.0` project cannot restore it. ## Keeping them aligned - Upgrade every EF package, the provider and the tool in the **same change**, and read the major's breaking-changes list first. - Keep `dotnet-ef` in the repository's tool manifest, `.config/dotnet-tools.json`, so every developer and CI run use the same version. - Hold versions in one place, a shared property or central package management, so a test project cannot drift to another major. - Note EF Core 10's tool change: on a project with several target frameworks, `dotnet ef` now requires `--framework`. ## Diagnosing a suspected mismatch 1. Run `dotnet package list --include-transitive` on each project and compare the EF Core versions it resolved, including the ones a provider pulled in. 2. Check the restore output for NU1608 and fix the reference that sits outside a range. 3. Run `dotnet ef --version` and compare it with the project's `Microsoft.EntityFrameworkCore.Design` version. 4. Read a `MissingMethodException` stack trace: if the missing member belongs to an EF Core type and the caller is a provider assembly, the majors disagree. ## A typical upgrade from EF Core 8 Moving the clinic app from EF Core 8 to 10 means retargeting to `net10.0`, bumping the runtime, Design and test-provider packages to 10.0.x, the Npgsql provider to 10.x and the tool to 10.x, then reading the EF Core 9 and 10 breaking changes, for example pending model changes now throwing on migrate.

  • Is Npgsql.EntityFrameworkCore.PostgreSQL 10.0.3 with EF Core 10.0.12 a mismatch?
    No. The provider declares its EF Core dependency as `[10.0.4, 11.0.0)`, so any EF Core 10 patch from 10.0.4 upwards satisfies it. Providers ship on their own schedule; what must match is the major version, not the patch number.
  • Why does dotnet ef ask for --framework after the upgrade to EF Core 10?
    EF Core 10's tools resolve the project's packages through MSBuild's package-asset resolution, so on a project with `<TargetFrameworks>` they cannot pick one on their own and fail with "The project targets multiple frameworks. Use the --framework option...". Pass `--framework net10.0`, or keep the startup project single-targeted.

  • Any EF Core provider version works with any EF Core version because they share interfaces.
  • Npgsql.EntityFrameworkCore.PostgreSQL 10.0.3 requires exactly EF Core 10.0.3.
  • The dotnet-ef tool version doesn't matter as long as the command runs.
  • EF Core 10 can run in a net8.0 project when the .NET 10 SDK builds it.
  • Microsoft.EntityFrameworkCore.Design can stay on 9.x while the runtime moves to 10.

Assumes EF Core 10.0.x with Npgsql.EntityFrameworkCore.PostgreSQL 10.0.3, whose EF Core dependency range is [10.0.4, 11.0.0); EF Core 10 runs only on .NET 10.