You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -140,3 +141,7 @@ In this case, every request to the service index will have additional latency, d
140
141
141
142
While NuGet's V3 API was designed to work on a static file server, the search resource is the exception that always requires a dynamic web service to process requests.
142
143
If you wish to host search, or indeed any other NuGet API resource, on different servers, in order to benefit from `HttpClientHandler`'s `PreAuthenticate`, you will need to use a reverse proxy to ensure all customer facing URLs in the service index meet the "same or subdirectory" rule.
144
+
145
+
## Enable embedded README downloads
146
+
147
+
A [new resource](./readme-template-resource.md) was documented for constructing a URL that can be used to download a README for a given package. This will allow client, like the Package Management UI in VS, to display the embedded README for packages which haven't been previously installed by the user. The client will construct this URL and attempt to download the README, using the response to the request to determine if a README is available. This means servers should expect multiple requests to the constructed endpoint as users navigate the PM UI.
Copy file name to clipboardExpand all lines: docs/consume-packages/Package-References-in-Project-Files.md
+59-9Lines changed: 59 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,7 +61,7 @@ This may be useful, if you reference projects which are PackageReference styled
61
61
62
62
## PackageReference and sources
63
63
64
-
In PackageReference projects, the transitive dependency versions are resolved at restore time. As such, in PackageReference projects all sources need to be available for all restores.
64
+
In PackageReference projects, the transitive dependency versions are resolved at restore time. As such, in PackageReference projects all sources need to be available for all restores.
65
65
66
66
## Floating Versions
67
67
@@ -285,7 +285,7 @@ To suppress a warning project wide, consider doing:
285
285
</ItemGroup>
286
286
```
287
287
288
-
Sometimes warnings apply only to a certain package in the graph. We can choose to suppress that warning more selectively by adding a `NoWarn` on the PackageReference item.
288
+
Sometimes warnings apply only to a certain package in the graph. We can choose to suppress that warning more selectively by adding a `NoWarn` on the PackageReference item.
289
289
290
290
```xml
291
291
<PropertyGroup>
@@ -307,15 +307,15 @@ When in Visual Studio, you can also [suppress warnings](/visualstudio/ide/how-to
307
307
308
308
Input to NuGet restore is a set of `PackageReference` items from the project file (top-level or direct dependencies) and the output is a full closure of all the package dependencies including transitive dependencies. NuGet tries to always produce the same full closure of package dependencies if the input PackageReference list has not changed. However, there are some scenarios where it is unable to do so. For example:
309
309
310
-
* When you use floating versions like `<PackageReference Include="My.Sample.Lib" Version="4.*"/>`. While the intention here is to float to the latest version on every restore of packages, there are scenarios where users require the graph to be locked to a certain latest version and float to a later version, if available, upon an explicit gesture.
311
-
* A newer version of the package matching PackageReference version requirements is published. E.g.
310
+
- When you use floating versions like `<PackageReference Include="My.Sample.Lib" Version="4.*"/>`. While the intention here is to float to the latest version on every restore of packages, there are scenarios where users require the graph to be locked to a certain latest version and float to a later version, if available, upon an explicit gesture.
311
+
- A newer version of the package matching PackageReference version requirements is published. E.g.
312
312
313
-
* Day 1: if you specified `<PackageReference Include="My.Sample.Lib" Version="4.0.0"/>` but the versions available on the
313
+
- Day 1: if you specified `<PackageReference Include="My.Sample.Lib" Version="4.0.0"/>` but the versions available on the
314
314
NuGet repositories were 4.1.0, 4.2.0 and 4.3.0. In this case, NuGet would have resolved to 4.1.0 (nearest minimum version)
315
315
316
-
* Day 2: Version 4.0.0 gets published. NuGet will now find the exact match and start resolving to 4.0.0
316
+
- Day 2: Version 4.0.0 gets published. NuGet will now find the exact match and start resolving to 4.0.0
317
317
318
-
* A given package version is removed from the repository. Though nuget.org does not allow package deletions, not all package repositories have this constraint. This results in NuGet finding the best match when it cannot resolve to the deleted version.
318
+
- A given package version is removed from the repository. Though nuget.org does not allow package deletions, not all package repositories have this constraint. This results in NuGet finding the best match when it cannot resolve to the deleted version.
319
319
320
320
### Enabling the lock file
321
321
@@ -329,12 +329,13 @@ In order to persist the full closure of package dependencies you can opt-in to t
329
329
</PropertyGroup>
330
330
```
331
331
332
-
If this property is set, NuGet restore will generate a lock file - `packages.lock.json` file at the project root directory that lists all the package dependencies.
332
+
If this property is set, NuGet restore will generate a lock file - `packages.lock.json` file at the project root directory that lists all the package dependencies.
333
333
334
334
> [!Note]
335
335
> Once a project has `packages.lock.json` file in its root directory, the lock file is always used with restore even if the property `RestorePackagesWithLockFile` is not set. So another way to opt-in to this feature is to create a dummy blank `packages.lock.json` file in the project's root directory.
336
336
337
337
### `restore` behavior with lock file
338
+
338
339
If a lock file is present for project, NuGet uses this lock file to run `restore`. NuGet does a quick check to see if there were any changes in the package dependencies as mentioned in the project file (or dependent projects' files) and if there were no changes it just restores the packages mentioned in the lock file. There is no re-evaluation of package dependencies.
339
340
340
341
If NuGet detects a change in the defined dependencies as mentioned in the project file(s), it re-evaluates the package graph and updates the lock file to reflect the new package closure for the project.
@@ -366,6 +367,7 @@ You may also set this conditional MSBuild property in your project file:
366
367
If locked mode is `true`, restore will either restore the exact packages as listed in the lock file or fail if you updated the defined package dependencies for the project after lock file was created.
367
368
368
369
### Make lock file part of your source repository
370
+
369
371
If you are building an application, an executable and the project in question is at the start of the dependency chain then do check in the lock file to the source code repository so that NuGet can make use of it during restore.
370
372
371
373
However, if your project is a library project that you do not ship or a common code project on which other projects depend upon, you **should not** check in the lock file as part of your source code. There is no harm in keeping the lock file but the locked package dependencies for the common code project may not be used, as listed in the lock file, during the restore/build of a project that depends on this common-code project.
@@ -388,7 +390,7 @@ You can control various behaviors of restore with lock file as described below:
|`-UseLockFile`|`--use-lock-file`| RestorePackagesWithLockFile | Opts into the usage of a lock file. |
391
-
|`-LockedMode`|`--locked-mode`| RestoreLockedMode | Enables locked mode for restore. This is useful in CI/CD scenarios where you want repeatable builds.|
393
+
|`-LockedMode`|`--locked-mode`| RestoreLockedMode | Enables locked mode for restore. This is useful in CI/CD scenarios where you want repeatable builds.|
392
394
|`-ForceEvaluate`|`--force-evaluate`| RestoreForceEvaluate | This option is useful with packages with floating version defined in the project. By default, NuGet restore will not update the package version automatically upon each restore unless you run restore with this option. |
393
395
|`-LockFilePath`|`--lock-file-path`| NuGetLockFilePath | Defines a custom lock file location for a project. By default, NuGet supports `packages.lock.json` at the root directory. If you have multiple projects in the same directory, NuGet supports project specific lock file `packages.<project_name>.lock.json`|
394
396
@@ -458,3 +460,51 @@ You can leave off `$(AssetTargetFallback)` if you wish to overwrite, instead of
458
460
> If you are using a [.NET SDK based project](/dotnet/core/sdk), appropriate `$(AssetTargetFallback)` values are configured and you do not need to set them manually.
459
461
>
460
462
> `$(PackageTargetFallback)` was an earlier feature that attempted to address this challenge, but it is fundamentally broken and *should* not be used. To migrate from `$(PackageTargetFallback)` to `$(AssetTargetFallback)`, simply change the property name.
463
+
464
+
## PrunePackageReference
465
+
466
+
The .NET Runtime is constantly evolving, with performance improvements and new APIs each release.
467
+
There is a lot of functionality that's available within the runtime, but also as packages, such as [System..Text.Json](https://www.nuget.org/packages/System.Text.Json). This can often lead to a `System.Text.Json 8.0.0` in a project targeting `.NET 9` or `.NET 8`. This dependency is unnecessary and the build conflict resolution would not use the assembly coming from the package since it's already available in the .NET Runtime.
468
+
Starting in in [NuGet version 6.13](..\release-notes\NuGet-6.13.md) and .NET SDK 9.0.200, `PrunePackageReference` enables the pruning of these packages at restore time for .NET SDK based projects.
469
+
470
+
Package pruning is available as an opt-in feature with the .NET 9 SDK, and will be enabled by default for all `.NET` frameworks and `>= .NET Standard 2.0` starting with .NET 10 SDK.
471
+
472
+
Package pruning is only available with the default dependency resolver as [released in 6.12](#nuget-dependency-resolver).
473
+
474
+
### PrunePackageReference specification
475
+
476
+
The list of packages to be pruned is defined with the `PrunePackageReference` item.
477
+
478
+
| Attributes | Description |
479
+
|------------|-------------|
480
+
| Version | Specifies the maximum version to be pruned. `1.0.0` means that all packages up to and including 1.0.0 will be pruned. For `1.0.0`, `0.9.0` and `1.0.0` will be pruned, but `1.0.1` would not. |
481
+
482
+
The following properties can be used to modify the pruning behavior.
483
+
484
+
| PropertyName | Description |
485
+
|--------------|-------------|
486
+
| RestoreEnablePackagePruning | Enables package pruning for the packages specified with `PrunePackageReference`. This property is per target framework and the valid values are `true` and `false`. Defaults may differ based on the .NET SDK as defined above. |
487
+
488
+
The .NET SDK predefines the list of packages to be pruned for you.
489
+
490
+
### How PrunePackageReference works
491
+
492
+
When a package is specified to be pruned during restore, it is removed from the dependency graph. This package is not downloaded and does not appear in any of the outputs of NuGet. When a package is pruned, there is a detailed verbosity message indicating that the package has been removed for the given target framework.
493
+
494
+
Pruning is only supported for transitive packages, meaning packages that are referenced by other packages or projects. The following table illustrates various package pruning behaviors.
495
+
496
+
| Dependency disposition | Behavior |
497
+
|-----------------|----------|
498
+
| Matches the ID of a transitive package coming through another package | Prune |
499
+
| Matches the ID of a transitive package coming through another project | Prune |
500
+
| Matches the ID of a direct `PackageReference`| Raise the [NU1510](../reference/errors-and-warnings/NU1510.md) warning and do not prune |
501
+
| Matches the ID of a `ProjectReference`| Raise the [NU1511](../reference/errors-and-warnings/NU1511.md) warning and do not prune |
502
+
503
+
### PrunePackageReference applications
504
+
505
+
The benefits of package pruning are two-fold:
506
+
507
+
- Performance benefits, by virtue of reducing the number of packages within a dependency graph
508
+
- Reduction of false positives by component scanners such as `NuGetAudit`
509
+
510
+
Pruning is particularly valuable when [auditing](./../concepts/Auditing-Packages.md) packages with `NuGetAuditMode` is set to `all`. If you are using the .NET 9, we recommend you try out pruning by setting `RestoreEnablePackagePruning` to `true`.
Copy file name to clipboardExpand all lines: docs/consume-packages/install-use-packages-visual-studio.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -53,7 +53,9 @@ To find and install a NuGet package with Visual Studio, follow these steps:
53
53
54
54
- Select a package to see detailed package information.
55
55
The details pane on the right appears and enables you to select a version to install.
56
-
56
+
57
+
You can see package metadata, information about the owner(s), author(s), license, etc., in the Package Details tab and the package README file (if it is provided by the package author) in the README tab.
58
+
57
59
58
60
1. In the right pane, select a **Version** from the dropdown list. If you want to include prerelease versions in the **Version** list, select **Include prerelease**.
0 commit comments