Migrate to PackageReference with 3 clicks
Karan Nandwani
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.
Light
Dark
1 comment
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 package had never been imported properly or that something happened during the conversion. Luckily this was not that difficult to fix.
4. There are two painful moments apart fomr not importing all the packages from packages.config. First there are various Import directives on the top of csproj files for couple of tools. As the location of the package is not longer <package_name>.<version> but rather <package_name>/<version> it was necessary to replace all these locations otherwise the project could not build
5. The only way we have found to keep this half-half solution where we do not remove all previous references, the purpose of which was not always completely clear, we had to run “dotnet restore –packages packages” and this would at least keep the packages in the same folder as with packages.configUnfortunately we gave up on using this tool in the end, as all these fixes are not acceptable on the solution as large as 180 projects. It looks as a simpler resolution to get the list of installed packages, remove them, convert csproj to contain PackageReference and the reinstall all packages. That way it is certain that no packages could be lost.Some packages would expect to have the location at packages folder as their internals (NuGetPack) would work from there. These packages must be removed manually. It is recomendable to make all these conversions into a separate repository. Once we have done this conversion, returning the project from another branch created a complete mess. In essence, do not count on git mechanism to have the same project with package.config and PackageReference placed in the same physical folder and freely switched one branch to another. That will not work.However, all problems unless you have 180 projects, are solvable manually. I guess I would accept to fix problem if there is no more than 30 projects. More than that… not really reliable.