Last year, we introduced the option to make PackageReference the default package management format for managing NuGet dependencies when installing the first NuGet package for a newly created projects. With Visual Studio Version 15.7 Preview 3, we have introduced the capability to migrate existing projects that use the packages.config format to use PackageReference instead.
Benefits of using PackageReference include:
- Ability to manage all project dependencies from one place (the project file).
- An uncluttered view of top-level dependencies: the project file shows only those NuGet packages you directly installed in the project.
- Faster package install/update times.
- Better cache management with a global-packages folder instead of a solution-local packages folder.
- Fine control over dependencies and content flow such as conditionally referencing a NuGet package per target framework, configuration, platform, or other pivots.
- New features as we continue to invest in PackageReference.
Migrate your projects to PackageReference today!
To try out the new migration experience, download Visual Studio 2017 Preview, open a packages.config based project, right-click the References node in Solution Explorer, and select the Migrate packages.config to PackageReference…. command.
Note that the migrator does not presently support C++, JavaScript, and ASP.NET (.NET Framework) projects.
The migrator analyzes the project’s existing references, calculates the dependency graph, and categorizes them into top-level and transitive dependencies.
By using the Top-level option, you can change any package that’s categorized as a transitive dependency to be treated instead as a top-level dependency.
The migrator also displays warnings for any potential package incompatibilities.
Backup and roll back
Before the process begins, the migrator creates a backup of the project file and packages.config to <solution_root>\MigrationBackup\<unique_guid>\<project_name>\. The backup allows you to roll back to packages.config if necessary.
Set PackageReference as the default
In the NuGet options in Visual Studio (opened using the Tools > NuGet Package Manager > Package Manager Settings menu command), change the Default package management format” to PackageReference. When you then install a NuGet package into a project for the first time, NuGet uses the PackageReference format. Newly created projects that come with existing NuGet references using packages.config (such as WPF) must be migrated to PackageReference after project creation.
Limitations
Although we’re working to bring the PackageReference goodness to all project types and to make all packages compatible with PackageReference, migration is not presently supported for C++, JavaScript, and ASP.NET (.NET Framework) projects.
Also, some packages are not fully compatible with PackageReference.
Enhancements in the pipeline
We are actively working to enhance PackageReference with features such as locking the transitive dependencies, ability to consolidate package versions across projects in a solution, and more.
We want to hear your feedback!
We want NuGet to meet the evolving needs of our community. For feedback specific to the migration experience, use NuGet/Home#5877. For anything else, hit us up at feedback@NuGet.org, and as always, if you run into any issues or have an idea, open an issue on GitHub.
Pitfalls:
After trying out 180 projects that we have had, here is the list of problems that appeared. We more or less blindly converted everything (manually 180*(5-6) clicks) and then we jumped into these issues1. If you are ready to check each conversion and fix it later manually this is a nice way of doing it (probably)2. For 4000 entries that we've had the tool missed about 600 of them
3. Now, we are not sure what happened exactly during conversion but, Hint field in csproj was useless of course and in couple of places it looked like that either...