Skip to content

Commit 67b8985

Browse files
CopilotCopilot
authored
Document PrunePackageReference automatic PrivateAssets marking breaking change in .NET 10 Preview 7 (#47924)
1 parent 43a44f9 commit 67b8985

File tree

4 files changed

+97
-5
lines changed

4 files changed

+97
-5
lines changed

‎docs/core/compatibility/10.0.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
108108
| [MSBuild custom culture resource handling](sdk/10.0/msbuild-custom-culture.md) | Behavioral change | Preview 1 |
109109
| [NU1510 is raised for direct references pruned by NuGet](sdk/10.0/nu1510-pruned-references.md) | Source incompatible | Preview 1 |
110110
| [PackageReference without a version raises an error](sdk/10.0/nu1015-packagereference-version.md) | Behavioral change | Preview 6 |
111+
| [PrunePackageReference marks direct prunable references with PrivateAssets=all and IncludeAssets=none](sdk/10.0/prune-packagereference-privateassets.md) | Behavioral change | Preview 7 |
111112
| [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 |
112113
| [NUGET_ENABLE_ENHANCED_HTTP_RETRY environment variable removed](sdk/10.0/nuget-enhanced-http-retry-removed.md) | Behavioral change | Preview 6 |
113114

‎docs/core/compatibility/sdk/10.0/nu1510-pruned-references.md

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
title: "Breaking change - NU1510 is raised for direct references pruned by NuGet"
3-
description: "Learn about the breaking change in .NET 10 where NU1510 is raised for unnecessary direct package references."
4-
ms.date: 3/25/2025
3+
description: "Learn about the breaking change in the .NET 10 SDK where NU1510 is raised for unnecessary direct package references."
4+
ms.date: 08/11/2025
55
ai-usage: ai-assisted
66
ms.custom: https://github.com/dotnet/docs/issues/45462
77
---
88

99
# NU1510 is raised for direct references pruned by NuGet
1010

11-
Starting in .NET 10, NuGet raises a [`NU1510` warning](/nuget/reference/errors-and-warnings/nu1510) when a project includes a direct package reference that overlaps with a framework-provided library and is not required.
11+
Starting in .NET 10, NuGet raises a [`NU1510` warning](/nuget/reference/errors-and-warnings/nu1510) when a project includes a direct package reference that overlaps with a framework-provided library and isn't required.
1212

1313
## Version introduced
1414

@@ -20,11 +20,14 @@ Previously, the .NET SDK ignored the contents of a package if it overlapped with
2020

2121
## New behavior
2222

23-
NuGet now removes unnecessary package references entirely and raises a `NU1510` warning to notify you of the issue.
23+
Starting in .NET 10, NuGet handles any unnecessary package references by raising a `NU1510` warning to notify you of the issue.
24+
25+
> [!NOTE]
26+
> In a later .NET 10 preview, this behavior changed again such that direct prunable package references are automatically excluded from the `.nuspec` file. For more information, see [PrunePackageReference marks direct prunable references with PrivateAssets=all and IncludeAssets=none](prune-packagereference-privateassets.md).
2427
2528
## Type of breaking change
2629

27-
This is a [source-incompatible change](../../categories.md#source-compatibility).
30+
This change can affect [source compatibility](../../categories.md#source-compatibility).
2831

2932
## Reason for change
3033

@@ -50,3 +53,7 @@ If your project targets only frameworks where the package is pruned, remove the
5053
## Affected APIs
5154

5255
None.
56+
57+
## See also
58+
59+
- [PrunePackageReference marks direct prunable references with PrivateAssets=all and IncludeAssets=none](prune-packagereference-privateassets.md)

‎docs/core/compatibility/sdk/10.0/prune-packagereference-privateassets.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: "Breaking change - PrunePackageReference marks direct prunable references with PrivateAssets=all and IncludeAssets=none"
3+
description: "Learn about the breaking change in the .NET 10 SDK where PrunePackageReference automatically marks directly prunable PackageReference with PrivateAssets=all and IncludeAssets=none."
4+
ms.date: 01/03/2025
5+
ai-usage: ai-assisted
6+
---
7+
8+
# PrunePackageReference marks direct prunable references with PrivateAssets=all and IncludeAssets=none
9+
10+
The [PrunePackageReference](/nuget/consume-packages/package-references-in-project-files#prunepackagereference) feature automatically removes *transitive* packages that are provided by the target platform. With this change, the feature also marks *directly* prunable `PackageReference` items with `PrivateAssets=all` and `IncludeAssets=none` attributes. These attributes prevent the packages from appearing in generated dependency lists for packages.
11+
12+
## Version introduced
13+
14+
.NET 10 Preview 7
15+
16+
## Previous behavior
17+
18+
In earlier .NET 10 previews, directly prunable `PackageReference` items might have generated an [`NU1510` warning](/nuget/reference/errors-and-warnings/nu1510) but still appeared in the generated *.nuspec* dependencies for all target frameworks, even those where the package is provided by the platform.
19+
20+
For example, consider a multi-targeting project with the following configuration:
21+
22+
```xml
23+
<PropertyGroup>
24+
<TargetFramework>net9.0;net472</TargetFramework>
25+
</PropertyGroup>
26+
27+
<ItemGroup>
28+
<PackageReference Include="System.Text.Json" Version="9.0.4" />
29+
</ItemGroup>
30+
```
31+
32+
Such a project file generated a *.nuspec* file with dependencies for both target frameworks:
33+
34+
```xml
35+
<dependencies>
36+
<group targetFramework=".NETFramework4.7.2">
37+
<dependency id="System.Text.Json" version="9.0.4" />
38+
</group>
39+
<group targetFramework="net9.0">
40+
<dependency id="System.Text.Json" version="9.0.4" />
41+
</group>
42+
</dependencies>
43+
```
44+
45+
## New behavior
46+
47+
Starting in .NET 10 Preview 7, directly prunable `PackageReference` items are automatically marked with `PrivateAssets=all` and `IncludeAssets=none`, which excludes them from the generated dependencies for target frameworks where they're provided by the platform.
48+
49+
The same project configuration now generates a *.nuspec* file with the prunable dependency removed from the target framework that provides it (.NET 9):
50+
51+
```xml
52+
<dependencies>
53+
<group targetFramework=".NETFramework4.7.2">
54+
<dependency id="System.Text.Json" version="9.0.4" />
55+
</group>
56+
<group targetFramework="net9.0">
57+
</group>
58+
</dependencies>
59+
```
60+
61+
## Type of breaking change
62+
63+
This is a [behavioral change](../../categories.md#behavioral-change).
64+
65+
## Reason for change
66+
67+
This change ensures that package dependencies accurately reflect the actual requirements for each target framework. It prevents unnecessary package references from appearing in generated packages when those APIs are already provided by the target framework.
68+
69+
## Recommended action
70+
71+
- If you create a package and get a [`NU1510` warning](/nuget/reference/errors-and-warnings/nu1510), follow the instructions there.
72+
- If you create a package and the generated *.nuspec* dependencies don't contain a referenced package for *any* target framework, remove the reference from the project file as it's not needed.
73+
- If the referenced package appears in the *.nuspec* file, no action is needed.
74+
75+
## Affected APIs
76+
77+
None.
78+
79+
## See also
80+
81+
- [PrunePackageReference](/nuget/consume-packages/package-references-in-project-files#prunepackagereference)
82+
- [NU1510 is raised for direct references pruned by NuGet](nu1510-pruned-references.md)

‎docs/core/compatibility/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,8 @@ items:
118118
href: sdk/10.0/nu1510-pruned-references.md
119119
- name: PackageReference without a version raises error
120120
href: sdk/10.0/nu1015-packagereference-version.md
121+
- name: PrunePackageReference marks direct prunable references with PrivateAssets=all and IncludeAssets=none
122+
href: sdk/10.0/prune-packagereference-privateassets.md
121123
- name: HTTP warnings promoted to errors in package list and search
122124
href: sdk/10.0/http-warnings-to-errors.md
123125
- name: NUGET_ENABLE_ENHANCED_HTTP_RETRY environment variable removed

0 commit comments

Comments
 (0)