From 27f23e513500035756cee07864411d602803b4d2 Mon Sep 17 00:00:00 2001 From: Vishxlll20 Date: Sun, 21 Jun 2026 13:33:45 +0530 Subject: [PATCH] docs: add NuGet plugin documentation (#450) --- docs/plugins/README.md | 9 ++++ docs/plugins/nuget.md | 102 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 docs/plugins/nuget.md diff --git a/docs/plugins/README.md b/docs/plugins/README.md index 53fa7e64..85fdbec7 100644 --- a/docs/plugins/README.md +++ b/docs/plugins/README.md @@ -22,6 +22,7 @@ marketplace-style index for those plugins and a quick reference for how each one | `chocolatey` | Manages Chocolatey client configuration and feature flags. | `config_provider` | [Details](#chocolatey) | | `miniconda` | Python/R Package and Environment Manager | `config_provider` | [Details](./miniconda.md) | | `npm` | Manages user-level `.npmrc` settings. | `config_provider` | [Details](#npm) | +| `nuget` | Manages NuGet package sources and config in `NuGet.Config`. | `config_provider` | [Details](./nuget.md) | | `nvm` | Manages NVM for Windows `settings.txt`. | `config_provider` | [Details](#nvm) | | `pip` | Manages `pip.ini` settings for Python package installs. | `config_provider` | [Details](#pip) | | `pnpm` | Manages user-level `.npmrc` settings for pnpm. | `config_provider` | [Details](#pnpm) | @@ -198,6 +199,14 @@ Config key: `extensions.chocolatey` Manages `%ChocolateyInstall%\config\chocolatey.config`, including both `config` values and `features`. For package installs, see [Chocolatey module docs](../modules/chocolatey.md). + + +#### nuget + +Config key: `extensions.nuget` + +Merges settings into `%APPDATA%\NuGet\NuGet.Config`. See [full docs](nuget.md). + diff --git a/docs/plugins/nuget.md b/docs/plugins/nuget.md new file mode 100644 index 00000000..faf61efd --- /dev/null +++ b/docs/plugins/nuget.md @@ -0,0 +1,102 @@ +# NuGet Plugin + +## Overview + +The NuGet plugin manages NuGet's machine-wide configuration file (`NuGet.Config`) by merging +package sources, API keys, disabled/fallback sources, repository paths, and general config values +into it. It parses the existing XML file, applies only the settings you specify, and leaves +anything else already in the file untouched. + +## Prerequisites + +- Windows, with the `APPDATA` environment variable available +- Either the `nuget` or `dotnet` CLI available on `PATH` — `check_installed` also passes if + `NuGet.Config` already exists at the default path, even without either CLI installed + +## Configuration Schema + +The plugin accepts a top-level YAML object with these fields, all optional: + +| Field | Type | Description | +| --- | --- | --- | +| `packageSources` | list of `{ name, source }` | NuGet feeds to add/update under ``. | +| `apiKeys` | list of `{ key, source }` | API keys to add/update under ``. `key` is the API key value, `source` is the feed URL it applies to. | +| `disabledPackageSources` | list of strings | Source names to disable under ``. | +| `fallbackPackageSources` | list of `{ name, source }` | Feeds to add/update under ``. | +| `repositoryPaths` | list of strings | Paths to add under ``. | +| `globalPackagesFolder` | string | Sets the `globalPackagesFolder` key under ``. | +| `httpProxy` | string | Sets the `httpProxy` key under ``. | +| `httpsProxy` | string | Sets the `httpsProxy` key under ``. | +| `maxHttpRequestsPerSource` | number | Sets the `maxHttpRequestsPerSource` key under ``. | +| `signatureValidationMode` | string | Sets the `signatureValidationMode` key under ``. | + +The plugin also supports WinHome's `dryRun` apply option, which reports whether `NuGet.Config` +would change without writing it. + +## Usage Examples + +### Example 1 — Add a package source + +```yaml +extensions: + nuget: + settings: + packageSources: + - name: nuget.org + source: https://api.nuget.org/v3/index.json + - name: company-feed + source: https://nuget.mycompany.com/v3/index.json +``` + +### Example 2 — Set the global packages folder and a proxy + +```yaml +extensions: + nuget: + settings: + globalPackagesFolder: 'D:\nuget-packages' + httpProxy: 'http://proxy.mycompany.com:8080' + maxHttpRequestsPerSource: 16 +``` + +### Example 3 — Disable a source and add an API key for a private feed + +```yaml +extensions: + nuget: + settings: + disabledPackageSources: + - nuget.org + apiKeys: + - source: https://nuget.mycompany.com/v3/index.json + key: 'your-api-key-here' +``` + +## Verification Steps + +```powershell +Test-Path "$env:APPDATA\NuGet\NuGet.Config" +Get-Content "$env:APPDATA\NuGet\NuGet.Config" +``` + +Confirm the ``, ``, ``, ``, or +`` elements contain the values you configured. You can also run: + +```powershell +nuget sources list +``` + +(or `dotnet nuget list source`) to confirm the package sources are recognized by the NuGet/dotnet +CLI itself. + +## Notes / Caveats + +- This plugin targets Windows only — it resolves NuGet's config through `%APPDATA%`. +- The XML file is written atomically: a temp file is written in the same directory first, then + swapped into place with `os.replace`, so a crash mid-write won't corrupt the existing file. +- If the existing `NuGet.Config` can't be parsed (corrupted), the plugin backs it up to + `NuGet.Config.corrupted..bak` before writing a fresh file from your `settings`. +- `apiKeys` entries are keyed by `source` (the feed URL), not by the `key` value itself — if two + entries share the same `source`, the later one in your list wins. +- `check_installed` returns `true` if either the `nuget`/`dotnet` CLI is on `PATH`, or if + `NuGet.Config` already exists — it doesn't otherwise verify NuGet is fully functional.