NuGet 2.7 Package Restore Tips
Since the release of NuGet 2.7 with Automatic Package Restore and implicit consent, many developers have adopted the new approach and provided some great feedback on their experiences. Based on that feedback, we have collected a set of tips to help you start using the new restore features.
Using Automatic Package Restore
Even though package restore consent is on by default, users still need to choose to omit their packages from source control before package restore is engaged. By default, source control systems will include the packages folder in your repository, and you need to take action to omit the packages from source control.
Use the .gitignore file to ignore the packages folder. Adding a line that simply has “packages” on it will do the trick.
TF Version Control
Use a .nuget\NuGet.Config file to disable source control integration for the solution, as explained on the NuGet Config Settings document under the “Source control integration” section. Using this approach, rather than cloaking the packages folder or otherwise ignoring it, NuGet knows to completely skip the call into Visual Studio to pend changes to the packages folder.
Here is what your .nuget\NuGet.Config file should look like to disable this integration. Note that you won’t be able to create the .nuget folder using File Explorer because it prevents the creation of folders that begin with a dot. You will need to create the folder from a command prompt.
<?xml version="1.0" encoding="utf-8"?>
<add key="disableSourceControlIntegration" value="true" />
Migrating from MSBuild-Integrated Package Restore
If you have a solution that has previously enabled the MSBuild-Integrated Package Restore approach and you would like to migrate to use Automatic Package Restore, there are just a few steps you can take to smoothly make the switch. The full walk-through is documented on the NuGet Docs site and it explains how to remove the unnecessary files from your solution and how to clean up your project files.
Package Restore with Team Foundation Build
Whether you’re using TFS on-premises or you’re using the Team Foundation Service, you can configure your Team Foundation Build to automatically restore packages as part of the build. This can work with either Git or TF version control.
The documentation for how to configure your build can be found here: http://docs.nuget.org/docs/reference/package-restore-with-team-build
Package Restore Consent Errors
Some users reported that they were still seeing build errors indicating that package restore consent had not been given. When we made the package restore changes in NuGet 2.7, we identified one scenario where this would happen but determined we couldn’t implement a fix and would rather have to document the scenario, cause and solution.
Scenario and Cause
In order to hit this problem, there’s a specific scenario you must be in. The scenario isn’t extremely common, but we have already heard reports of it.
- Using a freshly built machine or a machine where Visual Studio was freshly installed
- NuGet has been upgraded to 2.7
- An existing solution is opened where the MSBuild-integrated package restore has already been enabled
- The MSBuild-integrated package restore was enabled before NuGet 2.7 was released
In this scenario, the solution contains a .nuget folder that has nuget.exe version 2.6 or earlier. In those versions of nuget.exe, package restore consent was OFF by default (hard-coded to false when not present in nuget.config). When building this solution in Visual Studio, NuGet identifies that the MSBuild-integrated package restore is enabled and therefore automatic package restore is skipped. Then the old nuget.exe kicks in for the package restore and it does not find package restore consent to be given, yielding the following build error:
Package restore is disabled by default. To give consent, open the Visual Studio Options dialog, click on Package Manager node and check ‘Allow NuGet to download missing packages during build.’ You can also give consent by setting the environment variable ‘EnableNuGetPackageRestore’ to ‘true’.
As explained on the Package Restore documentation, there are three ways to address this situation.
- Force save your NuGet settings with consent given. To do this, open Visual Studio’s options and under Package Manager, choose General. Uncheck and then re-check the boxes for consent and click OK. This forces your %AppData%\NuGet\NuGet.config file to be saved with consent explicitly given, allowing NuGet 2.6 and earlier to see that you’ve given consent.
- Update the version of nuget.exe in your .nuget folder. To do this, run
nuget.exe update -selffrom your .nuget folder, which will download the latest version of nuget.exe and replace the version in the .nuget folder. The latest version of nuget.exe will infer consent to be ON even when not explicitly saved in the NuGet.config file.
- Migrate to Automatic Package Restore. For this approach, you would migrate from the MSBuild-integrated package restore to the Automatic Package Restore approach, following the documented walk-through.