Move your packages to the cloud

Last Update: 3/31/2017

Team Services | TFS 2017

Visual Studio Team Services provides hosted NuGet feeds as a service. If you're using NuGet packages as a part of your continuous delivery flow, Team Services Package Management can eliminate your dependencies on on-premises file shares and hosted instances of NuGet.Server. Team Services Package Management works with any CI system that supports authenticated NuGet feeds. This walkthrough assumes that you're using Team Services Team Build (not XAML Build).

Before you start

Team Services NuGet service provides a number of benefits compared to file shares. However, some of these benefits may require changes to your existing workflows.

  • Indexing: Team Services maintains an index of all the packages in each feed, which enables fast nuget list operations. List operations on your file shares require the client to open every nupkg and examine the nuspec for metadata unless your file share has been configured to provide an index that the NuGet client understands.
  • Immutability: A package version (e.g. MyPackage.1.0.0.0.nupkg) can only be pushed to a feed once. This ensures that any dependencies on that version are guaranteed to remain valid. However, if you have workflows that publish packages with newer binaries without changing the version number, those workflows will break when moved to Team Services NuGet feeds. Learn more about Immutability in Team Services.
  • Well-formedness: Team Services validates all pushed packages to ensure they're well-formed. This prevents invalid packages from entering your development and build environments. However, any workflow that publishes malformed packages will break when moving to Team Services NuGet feeds.

The Package Management service recommends NuGet 3.5 and NuGet 4. However, Package Management also supports legacy NuGet 2.x clients. For a complete list of the latest clients, see the NuGet distribution page.

Authentication and authorization

If you're using Active Directory-backed file shares, you and your on-prem build agents are likely authenticating automatically using Windows NTLM. Moving your packages to Team Services will require a few changes:

  • Authentication: You need to provide the NuGet client with credentials in order to restore and push packages.
    • Visual Studio 2015 users: Credential acquisition happens automatically, as long as you've updated the NuGet Package Manager extension to version 3.3 or higher by going to the Tools menu and using the Extensions and Updates window.
    • nuget.exe 3.x users: Credential acquisition happens automatically after you install the Team Services Credential Provider.
  • Authorization: Ensure that any principal (user, service account, group, etc.) that needs access to your packages has the appropriate permissions. See the permissions section for details.

Move your packages

Moving your packages to the cloud is a 4-step process:

  1. Inventory your existing package sources
  2. Make a plan for permissions
  3. Set up your feeds
  4. Use your feeds

Inventory your existing package sources

Before making any configuration changes, find your existing NuGet file shares by checking:

  • Any nuget.config files in your codebase, likely in the same folder as your .sln file
  • The global nuget.config file at
    • Command Prompt: %APPDATA%\NuGet\NuGet.Config
    • PowerShell: $env:APPDATA\NuGet\NuGet.Config

Look for any lines with a UNC path (like <add key="SMBNuGetServer" value="\\server\share\NuGet" />) and note the path. You'll use the list of paths in the migrate section later.

Make a plan for permissions

When setting up your new feeds, you can either:

  • Set up your feed permissions to match your existing file share permissions
  • Align your feed permissions with existing Team Services teams and groups

If you want to match your existing file share permissions, note the permissions on each share that contains packages. Specifically, note the principals with:

  • Full control
  • Modify or write
  • Read & execute, List folder contents, or Read

Set up your feeds

Now that you've inventoried your existing package sources, it's time to set up the feeds that will replace them. For this walkthrough, we'll assume a 1:1 mapping of feeds to SMB shares.

Create your feeds

For each SMB share, create a feed using the instructions here. In the create dialog:

  • Use the name of the SMB share folder as the Feed name
  • Leave the defaults for Who can read and Who can contribute

For each feed you've created, edit the feed and set permissions. There are a set of common identities that you should consider when setting up feed permissions.

If you've chosen to set up your new feed permissions to match your existing file share permissions, use the following table to give your principals the appropriate group membership:

SMB permission Feed group
Full control Owners
Modify, Write Contributors
Read & execute, List folder contents, Read Readers

Use your feeds

Get your feed's NuGet source URL

For each feed, click the Connect to feed button and copy the Source URL in the Connect with NuGet section. Use the Source URL in the migrate and update sections.

Migrate your packages

Once you've set up your feeds, you can do a bulk push from each SMB share to its corresponding feed. To do so:

  1. If you haven't already, open a PowerShell window in the repo where you installed the Team Services NuGet tools and run init.ps1. This sets up your environment to allow you to work with nuget.exe and Team Service's NuGet feeds.
  2. For each share, push all packages in the share to the new feed: nuget push {your package path}\*.nupkg -Source {your NuGet package source URL} -ApiKey VSTS

For larger teams, you should consider marking each share as read-only before doing the nuget push operation to ensure no one adds or updates packages during your migration.

Update your NuGet configuration

Now, return to each of the nuget.config files you found in the inventory section. For each share, find the corresponding <add key="SMBNuGetServer" value="\\server\share\NuGet" /> and replace the value with the new feed's source URL.

Add the Team Services NuGet tools to your repo

The Team Services NuGet bootstrap package can automate the process of acquiring the right NuGet tools and credentials to use feeds. This is especially helpful for users of Visual Studio 2013 (or earlier) or NuGet 2.x, which don't have built-in support for Team Services auth.

Integrate with your builds

Update your builds to ensure they have the right credentials to consume and publish packages in feeds. Team Build has NuGet Installer and NuGet Publisher tasks; see the Team Build page for details.