diff --git a/docs/archive/media/project-json-migrator.png b/docs/archive/media/project-json-migrator.png new file mode 100644 index 000000000..4328dfa7f Binary files /dev/null and b/docs/archive/media/project-json-migrator.png differ diff --git a/docs/archive/project-json-and-uwp.md b/docs/archive/project-json-and-uwp.md index b36ab5d20..0d88aa35a 100644 --- a/docs/archive/project-json-and-uwp.md +++ b/docs/archive/project-json-and-uwp.md @@ -10,7 +10,8 @@ ms.topic: conceptual # project.json and UWP > [!Important] -> This content is deprecated. Projects should use either the `packages.config` or PackageReference formats. +> This content is deprecated. Projects should use the PackageReference formats. +> Learn how to [migrate your project.json project to PackageReference](./project-json.md#migrate-projectjson-to-packagereference). This document describes the package structure that employs features in NuGet 3+ (Visual Studio 2015 and later). The `minClientVersion` property of your `.nuspec` can be used to state that you require the features described here by setting it to 3.1. diff --git a/docs/archive/project-json-impact.md b/docs/archive/project-json-impact.md index 3f171f019..23aae4fc2 100644 --- a/docs/archive/project-json-impact.md +++ b/docs/archive/project-json-impact.md @@ -10,7 +10,8 @@ ms.topic: conceptual # Impact of project.json when creating packages > [!Important] -> This content is deprecated. Projects should use either the `packages.config` or PackageReference formats. +> This content is deprecated. Projects should use the PackageReference formats. +> Learn how to [migrate your project.json project to PackageReference](./project-json.md#migrate-projectjson-to-packagereference). The `project.json` system used in NuGet 3+ affects package authors in several ways as described in the following sections. diff --git a/docs/archive/project-json.md b/docs/archive/project-json.md index ec21cf7e0..4b6243821 100644 --- a/docs/archive/project-json.md +++ b/docs/archive/project-json.md @@ -10,9 +10,10 @@ ms.topic: reference # project.json reference > [!Important] -> This content is deprecated. Projects should use either the `packages.config` or PackageReference formats. +> This content is deprecated. Projects should use the PackageReference formats. +> Learn how to [migrate your project.json project to PackageReference](#migrate-projectjson-to-packagereference). -*NuGet 3.x+* +*NuGet 3.x* The `project.json` file maintains a list of packages used in a project, known as a package management format. It supersedes `packages.config` but is in turn superseded by [PackageReference](../consume-packages/package-references-in-project-files.md) with NuGet 4.0+. @@ -37,6 +38,18 @@ The [`project.lock.json`](#projectlockjson) file (described below) is also used } ``` +## Migrate project.json to PackageReference + +The migration between project.json and PackageReference is straightforward. The easiest way to do it to use the built-in migrator in the latest Visual Studio 2022, Update 14. + +1. Load the project.json project in Visual Studio. +1. Go to the solution explorer of the project.json project and find the dependencies node. +1. Click `Migrate project.json to PackageReference...`! + +![Migrating from project.json to PackageReference](media/project-json-migrator.png) + +Alternatively, you may use the [dotnet migrate](/dotnet/core/tools/dotnet-migrate), or do the migration manually by taking all of the content from the project.json file and replacing it with the equivalent [PackageReference syntax](../consume-packages/Package-References-in-Project-Files.md). + ## Dependencies Lists the NuGet package dependencies of your project in the following form: diff --git a/docs/concepts/Dependency-Resolution.md b/docs/concepts/Dependency-Resolution.md index 0f7da2b60..81cb86f50 100644 --- a/docs/concepts/Dependency-Resolution.md +++ b/docs/concepts/Dependency-Resolution.md @@ -63,6 +63,7 @@ When using a floating version, NuGet resolves the highest version of a package t | 1.1.* | 1.1.0
1.1.1
1.1.2-alpha
1.2.0-alpha | 1.1.1 | The highest stable version that respects the specified pattern.| | \*-\* | 1.1.0
1.1.1
1.1.2-alpha
1.3.0-beta | 1.3.0-beta | The highest version including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 | | 1.1.\*-\* | 1.1.0
1.1.1
1.1.2-alpha
1.1.2-beta
1.3.0-beta | 1.1.2-beta | The highest version respecting the pattern and including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 | +| 1.2.0-rc.* | 1.1.0
1.2.0-rc.1
1.2.0-rc.2
1.2.0 | 1.2.0 | Despite this being a version range with a prerelease part, stables are allowed if they match the stable part. Given that 1.2.0 > 1.2.0-rc.2, it is chosen. | | > [!Note] > Floating version resolution does not take into account whether or not a package is listed. diff --git a/docs/consume-packages/Central-Package-Management.md b/docs/consume-packages/Central-Package-Management.md index 06890cf72..029b2fad7 100644 --- a/docs/consume-packages/Central-Package-Management.md +++ b/docs/consume-packages/Central-Package-Management.md @@ -38,6 +38,11 @@ Central package management applies to all ``-based MSBuild pro To get started with central package management, you must create a `Directory.Packages.props` file at the root of your repository and set the MSBuild property `ManagePackageVersionsCentrally` to `true`. +You can create it manually or you can use the dotnet CLI: +``` shell +dotnet new packagesprops +``` + Inside, you then define each of the respective package versions required of your projects using `` elements that define the package ID and version. @@ -117,6 +122,7 @@ For an idea of how central package management may look like, refer to our [sampl You can automatically override a transitive package version even without an explicit top-level `` by opting into a feature known as transitive pinning. This promotes a transitive dependency to a top-level dependency implicitly on your behalf when necessary. +Note that downgrades are allowed when transitive pinning a package. If you attempt to pin a package to a lower version than the one requested by your dependencies, restore will raise a [NU1109](../reference/errors-and-warnings/NU1109.md) error. You can enable this feature by setting the MSBuild property `CentralPackageTransitivePinningEnabled` to `true` in a project or in a `Directory.Packages.props` or `Directory.Build.props` import file: @@ -127,6 +133,45 @@ or `Directory.Build.props` import file: ``` +### Transitive pinning and pack + +When a package is transitively pinned, your project uses a higher than the one requested by your dependencies. +If you create a package from your project, in order to ensure that your package will work, NuGet will promote the transitively pinned dependencies to explicit dependencies in the nuspec. + +In the following example, `PackageA 1.0.0` has a dependency on `PackageB 1.0.0`. + +```xml + + + + + + +``` + +```xml + + + true + net6.0 + + + + + +``` + +When you use the pack command to create a package, both packages will appear in the dependency group. + +```xml + + + + +``` + +Because of this, the use of transitive pinning should be carefully evaluated when authoring a library as it may lead to dependencies you did not expect. + ## Overriding package versions You can override an individual package version by using the `VersionOverride` property on a `` item. This overrides any `` @@ -176,6 +221,7 @@ If you'd like to disable central package management for any a particular project ``` ## Global Package References + > [!Note] > This feature is only available in Visual Studio 2022 17.4 or higher, .NET SDK 7.0.100.preview7 or higher, and NuGet 6.4 or higher. diff --git a/docs/hosting-packages/Overview.md b/docs/hosting-packages/Overview.md index b016cef0d..a19316165 100644 --- a/docs/hosting-packages/Overview.md +++ b/docs/hosting-packages/Overview.md @@ -39,5 +39,6 @@ There are also several other NuGet hosting products such as [Azure Artifacts](ht - [ProGet](https://inedo.com/proget) from Inedo - [Sleet](https://github.com/emgarten/sleet), an open-source NuGet V3 static feed generator - [TeamCity](https://www.jetbrains.com/teamcity/) from JetBrains. +- [RepoFlow](https://www.repoflow.io), a simple and easy-to-use package management platform. Regardless of how packages are hosted, you access them by adding them to the list of available sources in `NuGet.Config`. This can be done in Visual Studio as described in [Package Sources](../consume-packages/install-use-packages-visual-studio.md#package-sources), or from the command line using [`nuget sources`](../reference/cli-reference/cli-ref-sources.md). The path to a source can be a local folder pathname, a network name, or a URL. diff --git a/docs/reference/cli-reference/cli-ref-sources.md b/docs/reference/cli-reference/cli-ref-sources.md index 827cdb3c4..56935e51b 100644 --- a/docs/reference/cli-reference/cli-ref-sources.md +++ b/docs/reference/cli-reference/cli-ref-sources.md @@ -107,5 +107,7 @@ nuget sources Enable -Name "nuget.org" nuget sources add -name foo.bar -source C:\NuGet\local -username foo -password bar -StorePasswordInClearText -configfile %AppData%\NuGet\my.config +nuget sources add -name MyAzureDevOpsSource -source "https://pkgs.dev.azure.com/yourorgname/yourprojectname/_packaging/yourfeedname/nuget/v3/index.json" -username ignored -password + nuget sources Update -Name "nuget.org" -ProtocolVersion 3 ```