Skip to content
This repository has been archived by the owner on Nov 19, 2020. It is now read-only.

Latest commit

 

History

History
255 lines (191 loc) · 12.1 KB

chapter-nuget.asciidoc

File metadata and controls

255 lines (191 loc) · 12.1 KB

.NET Package Repositories with NuGet

{inall}

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 https://github.com/NuGet/Home 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.

Important
With the release of version 2.9, NuGet support is available in {pro} and {oss}.

{pro} and {oss} support the NuGet repository format for hosted and proxy repositories. They also supports aggregation of NuGet repositories and conversion of other repositories containing .nupkg components to the NuGet format. This allows 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 repository manager-based NuGet repository. 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.

Note
Users can enable Repository Health Check on a repository using the NuGet format to retrieve all metadata from components in the repository, such as security and license. See [rhc] for details.

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.

Tip
Using NuGet repositories benefits from a larger memory size available to the repository manager. This memory allocation can be configured in wrapper.conf as documented in [running].

NuGet Proxy Repositories

The NuGet Gallery is the central repository used by all package authors and consumers. To reduce duplicate downloads and improve download speeds for your developers and CI servers, you should proxy the NuGet Gallery with the repository manager. If you use other external repositories, you should also proxy these.

To proxy an external NuGet repository, you simply create a new 'Proxy Repository' as documented in [confignx-sect-manage-repo]. The 'Provider' has to be set to NuGet. The 'Remote Storage Location' has to be set to the URL of the remote repository you want to proxy. The URL for the main NuGet Gallery repository is

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

A complete configuration for proxying the NuGet Gallery is visible in NuGet Proxy Repository Configuration for the NuGet Gallery.

nuget proxy org
Figure 1. NuGet Proxy Repository Configuration for the NuGet Gallery

The repository configuration for a NuGet proxy repository has an additional tab titled 'NuGet' as visible in NuGet Gallery with Package Source URL. It displays the 'Package Source' URL that is the URL where the repository is available as a NuGet repository.

By default, searches in NuGet repositories in the repository manager are passed through to the remote repositories, and 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.

NuGet Hosted Repositories

A hosted repository for NuGet can be used to upload your own packages as well as third-party packages. It is good practice to create two separate hosted repositories for these purposes.

To create a NuGet hosted repository, simply create a new 'Hosted Repository' and set the 'Provider' to NuGet. A sample configuration for an internal releases NuGet hosted repository is displayed in Example Configuration for a NuGet Hosted Repository for Release Packages.

nuget hosted releases configuration
Figure 3. Example Configuration for a NuGet Hosted Repository for Release Packages

Besides the 'NuGet' tab, the configuration for the repository has a 'NuPkg Upload' tab as displayed in The NuPkg Upload Panel for a Hosted NuGet Repository that allows you to manually upload one or multiple packages.

nuget hosted nupkg upload
Figure 4. The NuPkg Upload Panel for a Hosted NuGet Repository

The NuGet feed is immediately updated as packages are deployed or deleted from the host repository. To rebuild the feed for a hosted NuGet repository you can manually schedule a 'Rebuild NuGet Feed' task.

NuGet Virtual Repositories

If you have deployed NuGet packages to a Maven repository in the past, you can expose them to Visual Studio by creating a virtual repository as documented in [confignx-sect-manage-repo] and setting the 'Provider' to NuGet. The setup displayed in A Virtual NuGet Repository for the Releases Repository shows a virtual repository configured to expose the content of the regular Maven 'Releases' repository as a NuGet repository, so that NuGet can access any NuGet packages deployed to the releases repository.

nuget virtual releases
Figure 5. A Virtual NuGet Repository for the Releases Repository

The NuGet feed is immediately updated as packages are deployed or deleted from the shadowed repository. To rebuild the feed for a virtual NuGet repository, you can manually schedule a 'Synchronize Shadow Repository' task.

NuGet Group Repositories

A repository group is the recommended way to expose all your NuGet repositories 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. This is possible for NuGet repositories by creating a new 'Repository Group' with the 'Provider' set to NuGet as documented in [repository-groups].

A typical, useful example would be to group the proxy repository that proxies the NuGet Gallery, a NuGet, hosted repository with internal software packages and another NuGet, hosted repository with third-party packages. The configuration for such a setup is displayed in A Public NuGet Group Combining a Proxy and Two Hosted Repositories.

nuget group
Figure 6. A Public NuGet Group Combining a Proxy and Two Hosted Repositories

Using the 'Repository Path' of the repository group as your NuGet repository URL in your client tool will give you access to the packages in all three repositories with one URL. Any new packages added as well as any new repositories added to the group will automatically be available.

Accessing Packages in Repositories and Groups

Once you have set up your hosted and proxy repositories for NuGet packages, and potentially created a repository group, you can access them with the nuget tool on the command line. Copy the 'Package Source' URL from the 'NuGet' tab of the repository/group configuration you want to access and add it to nuget on the command line with e.g.:

nuget sources add -name NuGetNexus -source http://localhost:8081/nexus/service/local/nuget/nuget-public

Replace localhost with the public hostname or URL of your repository manager and nuget-public with the name of the repository you want to proxy. Ideally, this will be your 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 Deploying Packages to NuGet Hosted Repositories.

Deploying Packages to NuGet Hosted Repositories

In order to authenticate a client against a NuGet repository, NuGet uses an API key for deployment requests. These keys are generated separately on request from a user account on the NuGet gallery and can be regenerated at any time. At regeneration, all previous keys generated for that user are invalid.

Creating a NuGet API-Key

For usage with the repository manager, NuGet API keys are only needed when packages are going to be deployed; therefore, API key generation is by default not exposed in the user interface to normal users. Only users with at least the 'Deployment' role have access to the API keys.

Other users that should be able to access and create an API key have to be given the 'Nexus API-Key Access' role in the 'Users' security administration.

In addition, the 'NuGet API-Key Realm' has to be activated. To do this, simply add the realm to the selected realms in the 'Security Settings' section of the 'Server' configuration available in the 'Administration' submenu of the left-hand navigation panel.

Once this is set up, you can view as well as reset the current 'Personal API Key' in the 'NuGet' tab of any NuGet proxy or hosted repository as visible in Viewing and Resetting the NuGet API Key in the NuGet Configuration Tab

nuget api key
Figure 7. Viewing and Resetting the NuGet API Key in the NuGet Configuration Tab

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.

Deployment with the NuPkg Upload User Interface

Manual upload of one or multiple packages is done on the 'NuPkg Upload' tab of the repository displayed in The NuPkg Upload Panel for a Hosted NuGet Repository. Press the 'Browse' button to access the package you want to upload on the file system and press 'Add Package'. Repeat this process for all packages you want upload, and press 'Upload Package(s)' to complete the upload.

Command line based Deployment to a Nexus NuGet Hosted Repository

Alternatively to manual uploads, the nuget command line tool allows you to deploy packages to a repository with the push command. The command requires you to use the 'API Key' and the 'Package Source' path. Both of them are available in the NuGet tab of the hosted NuGet repository to where you want to deploy. 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.

Integration of NuGet Repositories in Visual Studio

In order to access a NuGet repository or preferably all NuGet repositories exposed in a group from the repository manager, you provide the 'Name' and 'Source' to the Visual Studio configuration for the 'Package Sources' of the 'NuGet Package Manager' as displayed in Package Source Configuration for the NuGet Package Manager in Visual Studio.

nuget visualstudio packageoptions
Figure 8. 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.