🛠️ The Package Version That Wasn’t the One in the File
A PackageReference listing a specific version tells you the version you asked for – not necessarily the version that’s actually loaded at build or runtime. NuGet’s dependency resolution can bump that to a higher version automatically if a different package you also reference has its own transitive dependency on the same library at a higher minimum version, and unless you specifically open the dependency tree, the version actually running in your app can silently diverge from the one line in the project file that looks like it’s deciding the matter.
🔎 The Problem
<!-- MyApp.csproj -->
<ItemGroup>
<PackageReference Include="Newtonsoft.Json" Version="12.0.3" />
<PackageReference Include="SomeThirdPartySdk" Version="3.0.0" />
</ItemGroup>
<!-- SomeThirdPartySdk 3.0.0 itself depends on
Newtonsoft.Json 13.0.1 or higher as one of its OWN
package references. NuGet's default resolution picks the
highest version required anywhere in the graph - so the
version actually loaded is 13.0.1, not the 12.0.3
explicitly written in MyApp.csproj. -->
dotnet list package --include-transitive
> Newtonsoft.Json Requested: 12.0.3 Resolved: 13.0.1
✅ Fix: Check the Resolved Version, Not Just the .csproj
- Run dotnet list package –include-transitive, or check the Dependencies node under the project in Solution Explorer, whenever a package’s behavior doesn’t match the version you believe you’re using – the .csproj’s Version attribute is a request to the resolver, not a guarantee of what it produces.
- If you genuinely need the exact version you wrote rather than whatever the resolver bumps it to, pin it explicitly with a central package version override or a direct reference with the version you require pinned, and verify the resolved version afterward with the same list-package command rather than trusting the .csproj alone.
- Before filing a bug against a specific version’s documented behavior, confirm which version is actually resolved and loaded first – a surprising number of version-specific bug reports turn out to be against a transitively-bumped version the reporter never intended to be running.
⚠️ Why This Is Easy to Miss
- The build succeeds without any warning in the default output – NuGet considers resolving to a higher compatible version a completely normal, successful resolution, not a conflict worth flagging, so there’s no red text or build warning pointing you toward the mismatch.
- IntelliSense and Go To Definition both quietly follow whatever version actually got resolved, not the one written in the .csproj – so code completion and API availability can look wrong for the version you think you’re on, when they’re actually correctly reflecting a different version you didn’t realize was loaded.
A PackageReference’s version attribute is your opening offer to the dependency resolver, not its final answer – and the final answer is the one your code actually runs with.
