Skip to content

Commit aff37f0

Browse files
Copilotgewarren
andcommitted
Add breaking change documentation for PackageReference version requirement
Co-authored-by: gewarren <[email protected]>
1 parent 4ab3dd1 commit aff37f0

File tree

3 files changed

+53
-0
lines changed

3 files changed

+53
-0
lines changed

docs/core/compatibility/10.0.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
7878
| [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md) | Behavioral change | Preview 1 |
7979
| [MSBuild custom culture resource handling](sdk/10.0/msbuild-custom-culture.md) | Behavioral change | Preview 1 |
8080
| [NU1510 is raised for direct references pruned by NuGet](sdk/10.0/nu1510-pruned-references.md) | Source incompatible | Preview 1 |
81+
| [PackageReference without a version will raise an error](sdk/10.0/nu1015-packagereference-version.md) | Behavioral change | Preview 6 |
8182
| [HTTP warnings promoted to errors in `dotnet package list` and `dotnet package search`](sdk/10.0/http-warnings-to-errors.md) | Behavioral/source incompatible change | Preview 4 |
8283

8384
## Windows Forms
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: "Breaking change - PackageReference without a version will raise an error"
3+
description: "Learn about the breaking change in .NET 10 where PackageReference without a version raises NU1015 error instead of NU1604 warning."
4+
ms.date: 12/17/2024
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs/issues/46386
7+
---
8+
9+
# PackageReference without a version will raise an error
10+
11+
Starting in .NET 10, NuGet raises a [`NU1015` error](/nuget/reference/errors-and-warnings/nu1015) when a `PackageReference` item doesn't have a version specified, instead of the previous [`NU1604` warning](/nuget/reference/errors-and-warnings/nu1604).
12+
13+
## Version introduced
14+
15+
.NET 10 Preview 6
16+
17+
## Previous behavior
18+
19+
Previously, NuGet raised a NU1604 warning with the text "Project dependency 'PackageA' does not contain an inclusive lower bound. Include a lower bound in the dependency version to ensure consistent restore results."
20+
21+
## New behavior
22+
23+
NuGet now raises a NU1015 error with the text "The following PackageReference item(s) do not have a version specified: PackageA"
24+
25+
## Type of breaking change
26+
27+
This is a [behavioral change](../../categories.md#behavioral-change).
28+
29+
## Reason for change
30+
31+
The "no lower bound" message was confusing, and it was unclear how to fix the issue. Additionally, NuGet would end up restoring the lowest version for that package, which is rarely what developers want. This change provides clearer and more actionable error messages when the version metadata is missing.
32+
33+
There's no change when using Central Package Management, since by design the PackageReference XML should not have a version in that scenario.
34+
35+
## Recommended action
36+
37+
Add a version to the package reference, for example:
38+
39+
```diff
40+
- <PackageReference Include="Some.Package" />
41+
+ <PackageReference Include="Some.Package" Version="1.2.3" />
42+
```
43+
44+
If the lowest package version is desired, then use `Version="0.0.0"`. In this case, NuGet will raise warning NU1603, rather than the previous NU1604.
45+
46+
`SdkAnalysisLevel` can be set to `9.0.300` or lower, and NuGet will revert to the previous warning. However, this will affect all features that gate on SdkAnalysisLevel.
47+
48+
## Affected APIs
49+
50+
None.

docs/core/compatibility/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@ items:
7474
href: sdk/10.0/msbuild-custom-culture.md
7575
- name: NU1510 is raised for direct references pruned by NuGet
7676
href: sdk/10.0/nu1510-pruned-references.md
77+
- name: PackageReference without a version will raise an error
78+
href: sdk/10.0/nu1015-packagereference-version.md
7779
- name: HTTP warnings promoted to errors in package list and search
7880
href: sdk/10.0/http-warnings-to-errors.md
7981
- name: Windows Forms

0 commit comments

Comments
 (0)