NuGet Repositories

NuGet offers a robust package management solution for .NET developers, streamlining the handling of libraries and tools in .NET Framework Visual Studio projects.

Nexus Repository provides hosting, proxying, and grouping capabilities for NuGet repositories. This combination improves collaboration, control, and efficiency in .NET development. Utilize a centralized repository to maximize benefits and streamline access to internal and external packages.

The NuGet format uses OData queries for communication between the client and the repository. These queries include metadata information about available packages and other data. Nexus Repository caches recent queries and returns cached metadata when the same query is sent before the cache expires.

The initial installation of Nexus Repository includes the following NuGet repositories:

nuget.org-proxy - proxy to the NuGet gallery
nuget-hosted - to upload your developed packages and third-party packages
nuget-group - Group combining the proxy and the hosted repositories

NuGet Proxy Repository

Use the following to configure a proxy to a remote NuGet repository:

Create a new nuget (proxy) as documented in Repository Management
Set the remote storage to the URL of the remote repository. This is the default V3 endpoint:
```
https://api.nuget.org/v3/index.json
```
Set the Protocol version to use: NuGet V2 or NuGet V3.
Select Save

NuGet Hosted Repositories

Hosted NuGet repositories are used to upload your developed packages and third-party packages. NuGet-hosted repositories may use either the v2 or v3 endpoints.

Use the Nuget (hosted) repository recipe to create a NuGet-hosted repository.
To use the V3 protocol on a hosted repository, add the service index as the source.
```
http://localhost:8081/repository/nuget-hosted/index.json
```

NuGet Group Repository

Group repositories streamline how users access NuGet repositories. This eliminates the need for additional client-side configuration as the repository group aggregates the content of multiple proxy and hosted repositories, presenting them through a single URL for your tools. The system automatically includes new packages and repositories added to the group.

NuGet Group Version 3 API Support

The V3 API for NuGet is supported when using Nexus Repository NuGet group repositories. Read more on the Microsoft documentation.

To use a group repository using the V3 protocol you must observe the following rules:

Group members must be only V3 repositories
This rule applies only for proxy and group repositories because hosted repositories work as both V2 and V3.
A group repository is V3 when all members are V3.
Add the group service index
The repository URL ends with the /index.json file
Environments with a mix of V2 and V3 endpoints default to using the V2 protocol

Counts on Searches of NuGet Group Repositories

Searches of NuGet proxy repositories are passed to the remote repositories. Searches against group repositories combine these results with internal searches on the other repositories in the group.

This merging has to make assumptions to generate component counts so consider these counts as approximate numbers instead of exact counts.

Configure NuGet Client

You have several options for configuring your NuGet client to use Nexus Repository.

Updating the NuGet Config File

Depending on your OS and use case, this file can be in different locations. Common locations include:

Specific to the user's environment.

%appdata%\NuGet\NuGet.Config (Windows)
~/.nuget/NuGet/NuGet.Config (Linux/macOS)

In your solution's root directory.
Within a specific repository.

Edit nuget.config:

Add a new <packageSource> with a unique key and the URL of your NuGet group repository. For example:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="Nexus" value="http://your-nexus-server:8081/repository/nuget-group/index.json" /> 
  </packageSources>
</configuration>

Add a <clear /> tag before your <packageSource> to remove the default NuGet source.

Setting Authentication
We recommend configuring Nexus Repository to require authentication. Generate an API key in Nexus Repository and provide it in your nuget.config or on the command line.
```
<packageSourceCredentials>
  <Nexus>
    <add key="Username" value="%NUGET_USERNAME%" />
    <add key="ClearTextPassword" value="%NUGET_API_KEY%" />
  </Nexus>
</packageSourceCredentials>
```

Update the NuGet Config File from the Command Line

You may directly edit your nuget.config file to edit the <packageSource> elements as shown above. However, using the dotnet nuget add source command is generally more convenient and less error-prone.

dotnet nuget add source "http://your-nexus-server:8081/repository/nuget-group/index.json" --name "Nexus" --username "your-nexus-username" --password "your-nexus-api-passcode"

Use the Group Repository as the only Source for NuGet Packages

We recommend removing the default sources and only using Nexus Repository for retrieving packages.

Use the dotnet nuget remove source command with the --name option to remove each source individually.

dotnet nuget list source

dotnet nuget remove source --name "source_name_1"
dotnet nuget remove source --name "source_name_2"

Scope: This command modifies the user-level nuget.config file. To clear sources for a specific project or solution, you'll need to run the command within the respective directory.
Verification: After removing the sources, use dotnet nuget list source again to verify that they have been removed from your configuration.

Using the NuGet Command Line Directly

Specify the source directly when using NuGet commands:

dotnet add package Newtonsoft.Json --source http://your-nexus-server:8081/repository/nuget-group/index.json --username "your-nexus-username" --password "your-nexus-api-key"

Avoid storing your password or API key directly in the command. Consider using environment variables or other secure methods for handling credentials.

Publishing to a Hosted Repository

You use the group repository when adding packages to your project to access packages from any source in your group. When publishing, you must publish directly to the hosted repository.

The following includes an example of setting your nuget.config to include both the group and hosted repository.

<configuration>
  <packageSources>
    <clear />
    <add key="Nexus" value="http://your-nexus-server:8081/repository/nuget-group/index.json" />
    <add key="NexusHosted" value="http://your-nexus-server:8081/repository/nuget-hosted/" />
  </packageSources>
  <packageSourceCredentials>
    <Nexus>
      <add key="Username" value="%NUGET_USERNAME%" />
      <add key="ClearTextPassword" value="%NUGET_API_KEY%" />
    </Nexus>
    <NexusHosted>
      <add key="Username" value="%NUGET_USERNAME%" />
      <add key="ClearTextPassword" value="%NUGET_API_KEY%" /> 
    </NexusHosted>
  </packageSourceCredentials>
</configuration>

When pushing your package to the hosted repository use the following format:

dotnet nuget push your-package.nupkg -s NexusHosted

For better security, store your API key as an environment variable to reference in your nuget.config.

Avoid storing sensitive information directly in the configuration file.

Setting Environment Variables

The dotnet CLI can then use environment variables for authentication.

export NUGET_USERNAME="user-token"
export NUGET_PASSWORD="user-token-pass-code"

For Windows use the following:

setx NUGET_USERNAME "user-token"
setx NUGET_API_KEY "user-token-pass-code"

NuGet Client Ignoring Pushes

Starting in NuGet v5.1 there is support for ignoring pushes where the package already exists in the repository (using the -SkipDuplicate flag). The NuGet client expects to get a 409 response in this case but Nexus Repository returns a 400 in all cases.

The --skip-duplicate option is not supported in Nexus Repository.

Support Notes

NuGet V2 verse V3 Permissions

NuGet version 2 does not need the browse permissions while NuGet v3 does.

Nuget Client's Set API Key Command

The nuget client uses an API Key for pushing packages to authenticate a client against a NuGet repository. The API key acts as an alias for the user account, so the same API key is used for all NuGet repositories. This user-specific key is generated separately by a user and may be regenerated. When regenerating, all previous keys for that user are invalidated.

nuget setapikey <API_key> -Source <source_URL>

The dotnet CLI does not directly support the setapikey command. The dotnet CLI uses user tokens for authentication with NuGet sources. These tokens are managed more securely and offer a broader scope of authentication than API keys used by setapikey.

Accessing the NuGet API Key

Users with the nx-apikey-all privilege may access the NuGet API key feature. Using API keys requires the NuGet API-Key Realm to be activated.

See details in Realms.

Access your NuGet API key by selecting Access API Key from the user account view. The view shows the key as well as the command line to register the key for usage with nuget.

Change for H2 or PostgreSQL Deployments

In Sonatype Nexus Repository release 3.43.0, we added support aligning with official NuGet v2 clients. The support for NuGet v2 in PostgreSQL or H2 environments is compatible with Microsoft's NuGet Gallery.

The NuGet V2 protocol makes use of a query mechanism called OData. Microsoft has deprecated parts of the v2 API therefore Nexus Repository does not support many common Chocolatey use cases and some custom OData queries.

Legacy NuGet V2 URLs

NuGet.org had updated its package service to version 3 to provide performance improvements over its legacy version 2 (OData-based) service.

Nexus Repository continues to provide limited support for the V2 endpoint, however, they are not recommended. You may use the following legacy NuGet V2 entry or configure the repository to use NuGet V2 in the protocol version field.

http://www.nuget.org/api/v2/

The NuGet V3 entry points need to include the /index.json in the URL. This package source is required by the Nuget client.

<nexus-host>:<nexus-port>/repository/<repository-name>/index.json

Integration with Visual Studio

To access a NuGet repository provide the URL from the repository manager to configure Name and Source in the Visual Studio configuration for the Package Sources of the NuGet Package Manager

With this configuration in place, packages available in your NuGet repository are available in the NuGet Package Manager in Visual Studio.

Moving From NuGet Version 2

NuGet introduced a new version of its protocol based on JSON instead of XML. The newer version 3 protocol stores package details in a static JSON format. NuGet version 3 repositories end with /index.json

When NuGet sees that the source ends with "index.json", it expects the source URL to point to the service index and performs calls using the version 3 API.

Migrating from Version 2 to Version 3

You cannot modify existing version 2 repositories and turn them into version 3 repositories. recreate them to fully migrate to version 3.

NuGet Proxy
Create a new version 3 proxy repository. Include the /index.json at the end of your remote URL.
To retain packages from your version 2 proxy, use the Export and Import tasks to move them to a hosted repository.
NuGet Hosted
No migration is needed; NuGet-hosted repositories support both NuGet v2 and v3 protocols
NuGet Group
Create a new NuGet version 3 group repository. Only include Version 3 proxy repositories.