Docs menu

Package managers

How NuGet restore works on Primcloud: supported sources, private feeds, credentials via environment variables, and lockfile behavior.

On this page

.NET apps use NuGet. Every dependency you declare, whether a <PackageReference>, a legacy packages.config, or a local tool in dotnet-tools.json, comes from a NuGet feed.

Supported package sources#

By default, NuGet restores from nuget.org, the public NuGet Gallery.

To add or override sources, drop a nuget.config file at the repo root. The .NET SDK reads it during restore:

nuget.config
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="my-private-feed" value="https://pkgs.example.com/nuget/v3/index.json" />
  </packageSources>
</configuration>

<clear /> drops the default sources, so restore uses only the ones you list. Everything else nuget.config supports, like source mapping, works as it does locally.

Install behavior#

The build runs dotnet tool restore if .config/dotnet-tools.json exists, putting your local tools on the PATH for the rest of the build. It then runs dotnet publish, which restores your packages from your NuGet sources before compiling. Packages are reused from the previous build when they haven't changed.

Private packages and registries#

For a private feed, give the .NET SDK its credentials as secrets named after the feed:

  • NuGetPackageSourceCredentials_<feed-name>__Username
  • NuGetPackageSourceCredentials_<feed-name>__Password (encrypted) or NuGetPackageSourceCredentials_<feed-name>__ClearTextPassword

<feed-name> is the key attribute of the <add> element in your nuget.config, with any characters other than letters and digits replaced by underscores.

Note

There's a double underscore before Username/Password.

Example. For the private feed above:

nuget.config
<add key="my-private-feed" value="https://pkgs.example.com/nuget/v3/index.json" />

Set:

  • NuGetPackageSourceCredentials_my_private_feed__Username = your username or PAT ID
  • NuGetPackageSourceCredentials_my_private_feed__ClearTextPassword = your token

They take effect on the next build.

Lockfiles#

Lockfiles are opt-in on .NET. Without one, dotnet restore picks the highest matching version for each <PackageReference> on every build. Set RestorePackagesWithLockFile on a project to generate and enforce one:

MyApp.csproj
<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

The next dotnet restore (locally or on Primcloud) produces a packages.lock.json alongside the project file. Commit it. From then on:

  • Restore fails if the lockfile disagrees with the version graph the <PackageReference> values would resolve to.
  • To lock more strictly on CI-style builds where the graph shouldn't change, add RestoreLockedMode=true. Primcloud's builds are not CI in the .NET sense, so this is opt-in behavior at your discretion.

Without a lockfile, the build still succeeds if the graph is resolvable, but two builds of the same commit can produce different dependency graphs if a package publishes a new patch between them.