Skip to content

Commit e43d9d8

Browse files
Copilotgewarren
Copilot
and
gewarren
committed
Add documentation for PrunePackageReference PrivateAssets automatic marking breaking change
Co-authored-by: gewarren <[email protected]>
1 parent f2cc59b commit e43d9d8

File tree

2 files changed

+98
-0
lines changed

2 files changed

+98
-0
lines changed

‎docs/core/compatibility/10.0.md‎

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

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

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: "Breaking change - PrunePackageReference automatically marks direct prunable references with PrivateAssets=all and IncludeAssets=none"
3+
description: "Learn about the breaking change in .NET 10 Preview 7 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 automatically marks direct prunable references with PrivateAssets=all and IncludeAssets=none
9+
10+
Starting in .NET 10 Preview 7, the PrunePackageReference feature automatically marks directly prunable PackageReference items with `PrivateAssets=all` and `IncludeAssets=none` attributes. This prevents these packages from appearing in generated dependency lists for multi-targeting packages.
11+
12+
## Version introduced
13+
14+
.NET 10 Preview 7
15+
16+
## Previous behavior
17+
18+
In .NET 10 Preview 6 and earlier, directly prunable PackageReference items would generate an [`NU1510` warning](/nuget/reference/errors-and-warnings/nu1510) but would still appear in the generated *.nuspec* dependencies for all target frameworks, even those where the package is provided by the platform.
19+
20+
For example, 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+
Would generate 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 target frameworks that provide it:
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-changes).
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, reducing maintenance burden and avoiding false dependency issues.
68+
69+
## Recommended action
70+
71+
If you're creating packages and the generated *.nuspec* dependencies are missing a PackageReference for certain target frameworks:
72+
73+
1. **If the package is no longer needed for any target framework**: Remove the PackageReference entirely from your project file.
74+
75+
2. **If the package is still needed for some target frameworks**: Use conditional PackageReference to include it only where necessary. For example:
76+
77+
```xml
78+
<ItemGroup>
79+
<!-- Include System.Text.Json only for frameworks older than .NET 8 -->
80+
<PackageReference Include="System.Text.Json" Version="9.0.4"
81+
Condition="!$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))" />
82+
</ItemGroup>
83+
```
84+
85+
3. **If you need to override the automatic pruning behavior**: Set `RestoreEnablePackagePruning` to `false` in your project file or *Directory.Build.props* file:
86+
87+
```xml
88+
<PropertyGroup>
89+
<RestoreEnablePackagePruning>false</RestoreEnablePackagePruning>
90+
</PropertyGroup>
91+
```
92+
93+
For more information about package pruning, see [PrunePackageReference](/nuget/consume-packages/package-references-in-project-files#prunepackagereference).
94+
95+
## Affected APIs
96+
97+
None.

0 commit comments

Comments
 (0)