Documentation Nexus Repository Manager 3.0

Chapter 8. .NET Package Repositories with NuGet

Available in Nexus Repository OSS and Nexus Repository Pro

8.1. Introduction

With the creation of the NuGet project, a package management solution for .NET developers has become available. Similar to Apache Maven dependency management for Java developers, NuGet makes it easy to add, remove, and update libraries and tools in Visual Studio projects that use the .NET Framework.

The project websites at www.nuget.org and nuget.codeplex.com host tool downloads and detailed documentation as well as links to further resources and provide a repository and features to upload your open source NuGet packages. With the NuGet Gallery a repository of open source libraries and tools is available and the need for repository management arises.

Nexus Repository Manager Pro and Nexus Repository Manager OSS support the NuGet repository format for hosted and proxy repositories as well as exposing them to the client-side tools as a repository group and has related repositories preconfigured.

Nexus Repository Manager and NuGet allow you to improve collaboration and control, while speeding up .NET development, facilitating open source libraries and sharing of internal component across teams. When you standardize on a single repository for all your development and use it for internal components as well, you will get all the benefits of using a repository manager when working in the .NET architecture.

To share a library or tool with NuGet, you create a NuGet package and store it in the NuGet repository on the repository manager. Similarly, you can use packages others have created and made available in their NuGet repositories by proxying them or downloading the packages and installing them in your own hosted repository for third party packages.

The NuGet Visual Studio extension allows you to download the package from the repository and install it in your Visual Studio project or solution. NuGet copies everything and makes any required changes to your project setup and configuration files. Removing a package will clean up any changes as required.

8.2. NuGet Repository Format

The NuGet repository format uses OData queries for communication between the client and the repository. These queries include metadata information about available packages and other data.

When the repository manager receives queries from the nuget client, it passes these queries on to the remote repositories, configured as proxy repository, if necessary.

To avoid sending identical queries to the remote repository, the repositry manager caches the queries and will rely on previously stored metadata if the same query is received again before the cache expires.

The NuGet section is included in for NuGet Proxy repositories to allow configuration of this caching. The parameters Query cache size and Query cache age can be used to configure the size of this cache in terms of how many queries are cached as well as the rate at which queries expire and are subsequently re-run.

8.3. NuGet Proxy Repositories

The NuGet Gallery is the common repository used by all package authors and consumers. To reduce duplicate downloads and improve download speeds for your developers and CI severs, you should proxy the NuGet Gallery with the repository manager. If you use other external repositories, you should also proxy these. A default installation of the repository manager has the NuGet gallery set up as a proxy repository with the name nuget.org-proxy.

To proxy another external NuGet repository, you simply create a new nuget (proxy) as documented in Section 4.3, “Repository Management”. The Remote Storage has to be set to the URL of the remote repository you want to proxy.

The default configuration for proxying the NuGet Gallery is partially visible in Figure 8.1, “NuGet Proxy Repository Configuration for the NuGet Gallery” and uses the URL of the API http://www.nuget.org/api/v2/.

figs/web/nuget-proxy-org.png

Figure 8.1. NuGet Proxy Repository Configuration for the NuGet Gallery


By default, searches in NuGet proxy repositories in the repository manager initiated by a client like nuget or VisualStudio will be passed through to the remote repositories. The search results are merged with internal search results and included in an internally managed index. This merging has to make some assumptions to generate component counts. These counts should therefore be considered approximate numbers. The cache can be configured in the NuGet section documented in Section 8.2, “NuGet Repository Format”.

8.4. NuGet Hosted Repositories

A hosted repository for NuGet can be used to upload your own packages as well as third-party packages. The repository manager includes a hosted NuGet repository named nuget-hosted by default.

To create another NuGet hosted repository, simply create a new nuget (hosted) repository. An example configuration from the default nuget-hosted repository is displayed in Figure 8.2, “Example Configuration for a NuGet Hosted Repository”.

figs/web/nuget-hosted-releases-configuration.png

Figure 8.2. Example Configuration for a NuGet Hosted Repository


The NuGet feed is immediately updated as packages are deployed or deleted from the host repository.

8.5. NuGet Repository Groups

A repository group is the recommended way to expose all your NuGet repositories from the repository manager to your users, without needing any further client side configuration. A repository group allows you to expose the aggregated content of multiple proxy and hosted repositories with one URL to your tools.

Nexus Repository Manager includes a nuget-group repository group by default. This typical, useful example groups the nuget.org-proxy proxy repository that proxies the NuGet Gallery and the nuget-hosted hosted repository.

The URL of the repository group can be used in your client tool and will give you access to the packages in all repositories from the group with one URL. Any new packages added as well as any new repositories added to the group will automatically be available.

8.6. Accessing Packages in Repositories and Groups

You can access the repository group or individual repositories with the nuget tool on the command line using their URL e.g.:

nuget sources add -name nuget-group -source http://localhost:8081/repository/nuget-group/

After this source was added, you can list the available packages with the command nuget list.

Access to the packages is not restricted by default. If access restrictions are desired, you can configure security directly or via LDAP/Active Directory external role mappings combined with repository targets for fine grained control. Authentication from NuGet is then handled via NuGet API keys as documented in Section 8.7, “Deploying Packages to NuGet Hosted Repositories”.

8.7. Deploying Packages to NuGet Hosted Repositories

In order to authenticate a client against a NuGet repository, NuGet uses an API key for deployment requests. The API key is acts as an alias for the user account, so the same API key is used for all NuGet repositories within the repository manager. This user-specific key is generated separately by a user and can be regenerated at any time. At regeneration, all previous keys generated for that user are invalid.

8.7.1. Accessing your NuGet API Key

For usage with the repository manager, NuGet API keys are only needed when packages are going to be deployed. Users with the necessary apikey-all security privilege can access the NuGet API Key feature view via the User menu by pressing on their username in the main toolbar.

You can access your API key by pressing on the Access API Key button and providing your username and password again. The resulting dialog as well as the surrounding user interface context is displayed in Figure 8.3, “Accessing your NuGet API Key”. It shows the API key itself as well as the full command line to register the key for usage with nuget.

The Reset API Key button can be used to invalidate an existing API key and create a new one.

figs/web/nuget-api-key.png

Figure 8.3. Accessing your NuGet API Key


[Important]

Usage of the API key requires the NuGet API-Key Realm to be activated. To do this, simply add the realm to the active realms in the Realms feature of the Security menu from the Administration menu.

8.7.2. Creating a Package for Deployment

Creating a package for deployment can be done with the pack command of the nuget command line tool or within Visual Studio. Detailed documentation can be found on the NuGet website.

8.7.3. Command line based Deployment to a NuGet Hosted Repository

The nuget command line tool allows you to deploy packages to a repository with the push command. The command requires you to use the NuGet API Key and the URL of the target hosted repository. For example, you could push to the hosted repository created in Section 8.4, “NuGet Hosted Repositories” using the URL http://localhost:8081/repository/nuget-hosted.

Using the delete command of nuget allows you to remove packages in a similar fashion. Further information about the command line tool is available in the on-line help.

8.8. Integration with Visual Studio

In order to access a NuGet repository or preferably all NuGet repositories exposed in a repository group, you 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 as displayed in Figure 8.4, “Package Source Configuration for the NuGet Package Manager in Visual Studio”.

figs/web/nuget-visualstudio-packageoptions.png

Figure 8.4. Package Source Configuration for the NuGet Package Manager in Visual Studio


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