In a nuget.config with packageSourceMapping, how does NuGet decide which source a package may come from, and what breaks when you first switch it on?
answer
- every package must match a pattern
- transitive packages included
- exact id beats longest prefix beats *
- NU1100: sources not considered
- cached packages skip the lookup
basics
~20 sOnce packageSourceMapping exists, every package, transitive ones included, may only be restored from a source whose pattern matches its id; an exact id beats the longest prefix, and * is the fallback. Unmapped packages fail restore with NU1100.
solid answer
~40 s`<packageSourceMapping>` assigns package-id patterns to the `key`s of `<packageSources>`. Once the element exists, **every** package — top-level and transitive — must match some pattern, or restore fails with **NU1100**, whose message says package source mapping is enabled and lists the sources it did not consider. Patterns are exact ids or prefixes ending in `*`; when several match, an **exact id** wins, then the **longest prefix**, and plain `*` is the lowest-precedence default. The first switch-on usually breaks on transitive packages nobody knew came from the internal feed, or on a mapping `key` that does not match a source key. One gap matters: a package already in the global packages folder is used without a source lookup, so mappings are not checked — give the repo its own `globalPackagesFolder` to get the full benefit.
code
bash · 3 lines# restore into a repo-local folder so cached packages were all fetched under the mapping
export NUGET_PACKAGES="$PWD/.nuget/packages"
dotnet restore Payments.sln --configfile nuget.configgo deeper
Recall that packageSourceMapping in nuget.config ties package id patterns to specific feeds.
Explain that every package must match once the element exists, the exact-id, longest-prefix and * precedence, and what NU1100 tells you.
Roll mapping out safely: generate patterns from a real restore, add a default *, use a repo-local package folder to close the cache gap, and pair it with CPM's NU1507.
Decide the feed topology the mapping enforces — internal-only, mixed or upstreamed — and how ownership of internal prefixes is governed.
## What source mapping is With more than one package source, plain NuGet asks every source for every package and takes whichever answers. **Package source mapping** replaces that with an allow-list: each package id may come only from the sources whose patterns match it. NuGet's docs pitch it as a supply-chain safeguard; this question is about the mechanics. ```xml <configuration> <packageSources> <clear /> <add key="nuget.org" value="https://api.nuget.org/v3/index.json" /> <add key="BankFeed" value="https://pkgs.example.internal/nuget/v3/index.json" /> </packageSources> <packageSourceMapping> <packageSource key="nuget.org"> <package pattern="*" /> </packageSource> <packageSource key="BankFeed"> <package pattern="Payments.*" /> </packageSource> </packageSourceMapping> </configuration> ``` Here every `Payments.*` package must come from the bank's feed and everything else from nuget.org. ## The matching rules - A `packageSource key` must equal a `key` in `<packageSources>`. - A pattern is either an **exact package id** (`Payments.Ledger`) or a **prefix ending in `*`** (`Payments.*`); `*` alone matches everything. - When several patterns match an id, the **most specific** wins: an exact id always beats a prefix, a longer prefix beats a shorter one, and `*` is the weakest. - The same pattern may sit under several sources; then any of them may supply it, which the docs warn makes restores less predictable. - Mapping settings follow the normal nuget.config precedence across machine, user and repository files. | Package id | Matching patterns | Allowed source | |---|---|---| | `Payments.Ledger` | `*`, `Payments.*` | BankFeed (longer prefix) | | `Polly.Core` | `*` | nuget.org | ## What breaks on day one Once the element exists, **every** package — including transitive ones — must match a pattern. Typical first failures: 1. **No default pattern.** Without a `*` entry, each transitive package from nuget.org needs its own pattern, and restore fails with **NU1100** ("Unable to resolve ... PackageSourceMapping is enabled, the following source(s) were not considered"). 2. **An internal package with an unusual prefix** falls through to `*` and is looked up on the wrong feed. 3. **A key that does not match** — a source renamed in `<packageSources>` but not under `<packageSourceMapping>` — leaves a whole group of patterns pointing at nothing. 4. **An internal package depending on another internal package** with a different prefix, which only shows up transitively. NuGet's docs point to a package source mapper tool that reads the `.nupkg.metadata` files of a successful restore to generate the first mapping, including transitive packages. ## Rolling it out without a broken day 1. Run a clean restore of the whole solution into an empty package folder, so every package is downloaded fresh and its `.nupkg.metadata` records the source it came from. 2. Generate or write the mapping from that evidence: internal prefixes to the internal feed, everything else to the public source through `*`. 3. Restore again with the mapping and fix each NU1100: a missing pattern, or an internal package with an unexpected prefix. 4. Distinguish NU1100 from **NU1101**: NU1100 with the mapping note means no allowed source matched the id at all, while NU1101 means the allowed sources were searched and none of them has the package. 5. Commit the mapping in the repository `nuget.config`, next to `<clear />`d sources, so developer machines and CI enforce the same rules. ## The global packages folder gap When a requested package already exists in the global packages folder, **no source lookup happens and the mappings are ignored**. A package first downloaded from the wrong source on a shared machine is reused silently. The docs' remedy is a **repository-specific** `globalPackagesFolder` in the repo's `nuget.config` (or a per-job `NUGET_PACKAGES` in CI), so every package in that folder was fetched under the mapping. Each extracted package also records its origin in `.nupkg.metadata`, which is how you audit where a cached package came from. ## How it meets the rest of NuGet - With **Central Package Management** and more than one source, restore warns **NU1507** until mapping is configured or a single source is used. - Vulnerability data can come from separate `<auditSources>`, so a bank can map packages to its own feed while still auditing against nuget.org's advisory data. - Source mapping is about **where** a package comes from; which **version** resolves is still decided by the project's references.
- With * mapped to nuget.org and Payments.* mapped to BankFeed, can restore ever fetch Payments.Ledger from nuget.org?Not under this mapping. The id matches both `*` and `Payments.*`, and the longer prefix wins, so BankFeed is the only allowed source. It would change only if nuget.org were also given `Payments.Ledger` or a longer `Payments.` prefix, or the same `Payments.*` pattern.
- What happens if you map an id to two sources?Both become valid origins and either may satisfy the request. NuGet allows it but recommends against it, because the same version could then arrive from different feeds on different machines; keep each pattern under one source unless you trust both equally.
- Source mapping only applies to top-level packages; transitive ones may come from any feed.
- When two patterns match, the one declared first in the file wins.
- Packages already in the global packages folder are re-validated against the mapping.
- A missing * pattern makes NuGet fall back to asking every source.
- packageSourceMapping also decides which version of a package is restored.