From c6e8fd19c86ae3fd9be9c1818e14c37bb882ff91 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Sat, 4 Jun 2022 09:43:16 +0200 Subject: [PATCH] docs(nuget): rewrite (#15846) --- docs/usage/nuget.md | 46 ++++++++++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/docs/usage/nuget.md b/docs/usage/nuget.md index 8b55d8a75b301d..9ed2174b32f3df 100644 --- a/docs/usage/nuget.md +++ b/docs/usage/nuget.md @@ -5,33 +5,45 @@ description: NuGet (.NET) dependencies support in Renovate # NuGet -Renovate supports upgrading dependencies in `.csproj`, `.fsproj`, and `.vbproj` files. +Renovate can upgrade dependencies in these files: + +- `.csproj` +- `.fsproj` +- `.vbproj` ## Version Support -Only SDK-style `.csproj`/`.fsproj`/`.vbproj` files are currently supported. +Renovate only works with SDK-style `.csproj`, `.fsproj` or `.vbproj` files. By default, this includes: - .NET Core 1.0 and above - .NET Standard class libraries -- Any `.csproj`/`.fsproj`/`.vbproj` in the SDK-style syntax +- `.csproj`, `.fsproj` or `.vbproj` files that use the SDK-style syntax -To convert your .NET Framework `.csproj`/`.fsproj`/`.vbproj` into an SDK-style project, follow the steps in this [guide](https://natemcmaster.com/blog/2017/03/09/vs2015-to-vs2017-upgrade/). +To convert your .NET Framework `.csproj`, `.fsproj` or `.vbproj` files into an SDK-style project, follow the steps in this [guide](https://natemcmaster.com/blog/2017/03/09/vs2015-to-vs2017-upgrade/). ## How it works 1. Renovate searches in each repository for any files with a `.csproj`, `.fsproj`, or `.vbproj` extension 1. Existing dependencies are extracted from `` and `` tags -1. Renovate looks up the latest version on [nuget.org](https://nuget.org) (or on [alternate feeds](#Alternate%20feeds)) to determine if any upgrades are available -1. If the source package includes a GitHub URL as its source, and has either a "changelog" file or uses GitHub releases, then release notes for each version are embedded in the generated PR +1. Renovate looks up the latest version on [nuget.org](https://nuget.org) (or on [alternate feeds](#Alternate%20feeds)) to see if any upgrades are available +1. If the source package includes a GitHub URL as its source, and has either: + + - a "changelog" file, or + - uses GitHub releases + + then release notes for each version are embedded in the generated PR If your project file references a `packages.config` file, no dependencies will be extracted. Find out here how to [migrate from `packages.config` to `PackageReference`](https://docs.microsoft.com/en-us/nuget/consume-packages/migrate-packages-config-to-package-reference). ## Alternate feeds -By default Renovate performs all lookups on `https://api.nuget.org/v3/index.json`, but you can configure alternative NuGet feeds. -Alternative feeds can be specified either [in a `NuGet.config` file](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) within your repository (Renovate will not search outside the repository) or in Renovate configuration options: +By default Renovate performs all lookups on `https://api.nuget.org/v3/index.json`, but you can set alternative NuGet feeds. +You can set alternative feeds: + +- in a [`NuGet.config` file](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) within your repository (Renovate will not search outside the repository), or +- in a Renovate configuration options file like `renovate.json` ```json { @@ -45,17 +57,21 @@ Alternative feeds can be specified either [in a `NuGet.config` file](https://doc } ``` -In this example we defined 3 NuGet feeds. -The package resolving process uses the `merge` strategy to handle the 3 feeds. +In the example above we've set three NuGet feeds. +The package resolving process uses the `merge` strategy to handle the three feeds. All feeds are checked for dependency updates, and duplicate updates are merged/joined together into a single dependency update. If your project uses lockfiles (a `package.lock.json` exists), alternate feed settings must be defined in a `NuGet.config` only, as `registryUrls` are not passed through to the NuGet commands used. ### Protocol versions -NuGet supports two protocol versions, `v2` and `v3`, the NuGet client and server must use the same protocol version. -Renovate as a NuGet client supports both versions and will use `v2` unless the configured feed URL ends with `index.json` (which mirrors the behavior of the official NuGet client). -If you have a `v3` feed that does not match this pattern (e.g. JFrog Artifactory) you need to help Renovate by appending `#protocolVersion=3` to the registry URL: +NuGet supports two protocol versions, `v2` and `v3`. +The NuGet client and server must use the same version. + +Renovate as a NuGet client supports both `v2` and `v3` protocols, and will use `v2` unless the configured feed URL ends with `index.json`. +This mirrors the behavior of the official NuGet client. + +If you have a `v3` feed that doesn't end with `index.json`, like for example on the JFrog Artifactory, then you must append `#protocolVersion=3` to the registry URL: ```json { @@ -67,7 +83,7 @@ If you have a `v3` feed that does not match this pattern (e.g. JFrog Artifactory ## Authenticated feeds -Credentials for authenticated/private feeds can be provided via host rules in the configuration options (file or command line parameter). +Credentials for authenticated/private feeds can be given via host rules in the configuration options (file or command line parameter). ```json { @@ -84,7 +100,7 @@ Credentials for authenticated/private feeds can be provided via host rules in th !!! note - At the moment only Basic HTTP authentication (via username and password) is supported. + Only Basic HTTP authentication (via username and password) is supported. ## Future work