Edit

Tutorial: Set up a vcpkg binary cache using a NuGet feed

  • Article

Note

This tutorial uses a NuGet feed hosted in Azure Artifacts but the same instructions can be used for other NuGet feed providers, for example: GitHub Packages, with some changes.

vcpkg supports using NuGet package feeds to upload and restore binary packages in a convenient way.

NuGet package feeds have access control capabilities which make them ideal to limit access to resources across your organization or workgroup. NuGet feeds are supported by several cloud-storage providers, such as, Azure Artifacts and GitHub package registry.

In this tutorial, you'll learn how to:

Prerequisites

  • A terminal
  • vcpkg
  • A NuGet packages feed, or if you don't, an Azure DevOps account to follow along
  • A terminal
  • vcpkg
  • A NuGet packages feed, or if you don't, an Azure DevOps account to follow along
  • The mono package installed in your system

1 - Set up a NuGet feed

Skip this step if you already have an existing NuGet packages feed.

Follow the instructions to set up an Azure Artifacts NuGet feed.

You can also use any other NuGet packages feed provider of your choice.

2 - Add a NuGet source

Note

On Linux you need mono to execute nuget.exe. You can install mono using your distribution's system package manager.

vcpkg acquires its own copy of the nuget.exe executable that it uses during binary caching operations. This tutorial uses the vcpkg-acquired nuget.exe. The vcpkg fetch nuget command outputs the location of the vcpkg-acquired nuget.exe, downloading the executable if necessary.

Run the following command to add your NuGet feed as a source, replace <feed name> with any name of your choosing and <feed url> with the URL to your NuGet feed.

.$(vcpkg fetch nuget) sources add -Name <feed name> -Source <feed url>

Execute the command below to fetch the path to the NuGet executable:

vcpkg fetch nuget

This will provide an output that looks something like C:\path\to\nuget.exe. Make a note of this path. Using the path obtained from the previous step, run the following command:

C:\path\to\nuget.exe sources add -Name <feed name> -Source <feed url>

mono `vcpkg fetch nuget | tail -n 1` sources add -Name <feed name> - Source <feed url>

Provide an API key

Some providers require that you push your NuGet packages to the feed using an API key. For example, GitHub Packages requires a GitHub PAT (Personal Access Token) as the API key; if you're using Azure Artifacts the API key is AzureDevOps instead.

Use the following command to set the API key for all the packages pushed to your NuGet feed, replace <apiKey> with your feed's API key.

.$(vcpkg fetch nuget) setapikey <apikey> -Source <feed url>

Execute the command below to fetch the path to the NuGet executable:

vcpkg fetch nuget

This will provide an output that looks something like C:\path\to\nuget.exe. Make a note of this path. Using the path obtained from the previous step, run the following command:

C:\path\to\nuget.exe setapikey <apikey> -Source <feed url>

mono `vcpkg fetch nuget | tail -n 1` sources setapikey <apiKey> - Source <feed url>

Provide authentication credentials

Your NuGet feed may require authentication to let you download and upload packages. If that's the case you can provide credentials by adding them as parameters to the nuget sources add command.

For example:

nuget sources add -Name my-packages -Source https://my.nuget.feed/vcpkg-cache/index.json -UserName myusername -Password mypassword -StorePasswordInClearText

Some providers like Azure Artifacts may require different authentication methods, read the Authenticate to private NuGet feeds article to learn more.

Use a nuget.config file

Alternatively, you can use a nuget.config file to configure your NuGet sources, following the template below:

nuget.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <config>
    <add key="defaultPushSource" value="<feed url>" />
  </config>
  <apiKeys>
    <add key="<feed url>" value="<apikey>" />
  </apiKeys>
  <packageSources>
    <clear />
    <add  key="<feed name>" value="<feed url>" />
  </packageSources>
  <packageSourcesCredentials>
    <<feed name>>
      <add key="Username" value="<username>" />
      <add key="Password" value="<password>" />
    </<feed name>>
  </packageSourcesCredentials>
</configuration>

Example nuget.config file :

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <config>
    <add key="defaultPushSource" value="https://contoso.org/packages/" />
  </config>
  <apiKeys>
    <add key="https://contoso.org/packages/" value="encrypted_api_key" />
  </apiKeys>
  <packageSources>
    <clear />
    <add key="Contoso" value="https://contoso.org/packages/" />
  </packageSources>
  <packageSourcesCredentials>
    <Contoso>
      <add key="Username" value="user" />
      <add key="Password" value="..." />
    </Contoso>
  </packageSourcesCredentials>
</configuration>

vcpkg requires that you set a defaultPushSource in your nuget.config file, use your NuGet feed's URL as the default source to push binary packages.

If you're uploading your packages to an Azure Artifacts NuGet feed, use AzureDevOps as your source's API Key. Otherwise, replace the value with your feed's proper API Key if you have one.

Add the <clear /> source to ignore other previously configured values. If you want, you can define multiple sources in this file, use a <add key="<feed name>" value="<feed url>" /> entry for each source.

Run the following command to add a NuGet source using a nuget.config file, replace <path to nuget.config> with the path to your nuget.config file:

.$(vcpkg fetch nuget) sources add -ConfigFile <path to nuget.config>

Execute the command below to fetch the path to the NuGet executable:

vcpkg fetch nuget

This will provide an output that looks something like C:\path\to\nuget.exe. Make a note of this path. Using the path obtained from the previous step, run the following command:

C:\path\to\nuget.exe sources add -ConfigFile <path to nuget.config>

mono `vcpkg fetch nuget | tail -n 1` sources add -ConfigFile <path to nuget.config>

3 - Configure vcpkg to use your NuGet feed

Set the VCPKG_BINARY_SOURCES environment variable as follows:

$env:VCPKG_BINARY_SOURCES="clear;nuget,<feed url>,readwrite"

If you're using a nuget.config file, instead do:

$env:VCPKG_BINARY_SOURCES="clear;nugetconfig,<path to nuget.config>"

set VCPKG_BINARY_SOURCES="clear;nuget,<feed url>,readwrite"

If you're using a nuget.config file, instead do:

set VCPKG_BINARY_SOURCES="clear;nugetconfig,<path to nuget.config>"

Note

Setting VCPKG_BINARY_SOURCES using the export command will only affect the current shell session. To make this change permanent across sessions, you'll need to add the export command to your shell's profile script (e.g., ~/.bashrc or ~/.zshrc).

export VCPKG_BINARY_SOURCES="clear;nuget,<feed url>,readwrite"

If you're using a nuget.config file, instead do:

export VCPKG_BINARY_SOURCES="clear;nugetconfig,<path to nuget.config>"

And that's it! vcpkg will now upload or restore packages from your NuGet feed.

Next steps

Authenticate to private NuGet feeds

Here are other tasks to try next: