Introduce package downloading feature to dotnet - #14495

My suggestion would be to avoid adding all of these options everywhere.
There are ways to do it in the nuget.config and we'd respect that.

Since this command will be used primarily in CI scenarios, I think having this option is critical. In cases where a dynamic source is required, relying on a nuget.config file can be cumbersome. For example, users encountered similar challenges with the push command, as noted in #14047.

Do we have links to GitHub issues or FeedbackTickets that we can add here?

yes, the original issue is linked at the top of the page: #12513. Do we also have other GitHub issues or Feedback Tickets that we should add here?

Did we ever discuss how PackageSourceMapping integrates with dotnet package download?

I think dotnet tool install is supposed to support it dotnet/sdk#41871 and it might've regressed.

Think we need to support source mapping in package download too.

Great catch! We did not discuss it. But I also think it is something we should support

I have added PSM to the doc https://github.com/NuGet/Home/blob/dev-nyenework-install/accepted/2025/dotnet-package-download.md#source-selection-and-package-source-mapping.

nuget install is a bit sloppy with how it handles package source mapping.
My testing gave me

Package 'Newtonsoft.json 13.0.4' is not found in the following primary source(s): 'https://api.nuget.org/v3/index.json,C:\Program Files (x86)\Microsoft SDKs\NuGetPackages'. Please verify all your online package sources are available (OR) package id, version are specified correctly.

At best, the error message isn't giving me a clear understanding of the problem (likely the logic finding the unmapped package is happening later than other commands like Restore). At worst, I wonder if install is trying to retrieve the package from the source first, then failing due to PSM being enabled.

I find it weird that some commands support both config files and override flags like --source, etc.
It makes it hard to decide here if we should also have some --ignore-package-source-mappings or similar - but my opinion is we should either use a config or use the CLI options. Mixing the concepts is likely confusing and error-prone.

Perhaps we can error if --configFile is specified in addition to any other configuration related option?

That's not a bad idea at all, but please compare and contrast this proposed behavior against all of the other dotnet CLI commands that interact with the NuGet config file and that have explicit source management flags.

We need to bias very hard in the direction of consistency with the rest of the CLI. Anytime there's a command that behaves inconsistently with the rest of the CLI surface area we get a long tail of issues and confusion from end users.

My understanding is that --source option and nuget.config are designed to complement each other in most of our commands.
Users can define their package sources through configuration files, but in dynamic environments: such as CI scenarios they may prefer to specify sources directly via the --source argument in scripts.

In other cases, when users already have multiple sources configured in their nuget.config but want to target one specifically, they can run --source <sourceName> to select it from their existing configuration.

In terms of precedence:

• The --source option always takes priority over sources(replaces them basically) defined in nuget.config.

• When --source <packageSource> is used, the CLI first checks whether the given value corresponds to a named source in the configuration file.

  • If it does, that configured source is used.
  • Otherwise, it’s treated as a direct source URI.

• If --source is not specified, the CLI falls back to the sources defined in the user’s configuration files.

This pattern is consistent across commands like dotnet nuget push, dotnet package search, and others.

When package source mapping is involved:

• If --source <packageSource> is specified, the CLI should follow the same behavior as above resolving the named source if present or treating it as a URI. In this case, package source mapping is not applied.
• If --source is not specified, the CLI reads the configuration file and uses package source mapping to determine the appropriate source.

For example, dotnet tool install does support package source mapping. However, in my testing, I observed a bug where the --source option is ignored when a nearby nuget.config file is present, and I’ve reported this issue for further investigation dotnet/sdk#51412.

When it comes to the package download, command I think we should follow the same pattern too.

• If --source is specified, the CLI should follow the same behavior as above: resolving the named source if present or treating it as a URI. In this case, package source mapping should not be applied.

• If --source is not specified, the CLI should read the configuration file and use package source mapping to determine the appropriate source.

What do you think @nkolev92

works for me.

works for me.