Migrate from packages.config to PackageReference

Visual Studio 2017 Version 15.7 Preview 3 and later supports migrating a project from the packages.config management format to the PackageReference format.

Benefits of using PackageReference

  • Manage all project dependencies in one place: Just like project to project references and assembly references, NuGet package references (using the PackageReference node) are managed directly within project files rather than using a separate packages.config file.
  • Uncluttered view of top-level dependencies: Unlike packages.config, PackageReference lists only those NuGet packages you directly installed in the project. As a result, the NuGet Package Manager UI and the project file aren't cluttered with down-level dependencies.
  • Performance improvements: When using PackageReference, packages are maintained in the global-packages folder (as described on Managing the global packages and cache folders rather than in a packages folder within the solution. As a result, PackageReference performs faster and consumes less disk space.
  • Fine control over dependencies and content flow: Using the existing features of MSBuild allows you to conditionally reference a NuGet package and choose package references per target framework, configuration, platform, or other pivots.
  • PackageReference is under active development: See PackageReference issues on GitHub. packages.config is no longer under active development.

Limitations

  • NuGet PackageReference is not available in Visual Studio 2015 and earlier. Migrated projects can be opened only in Visual Studio 2017.
  • Migration is not currently available for C++ and ASP.NET project.
  • Some packages may not be fully compatible with PackageReference. For more information, see package compatibility issues.

Migration steps

Note

Before migration begins, Visual Studio creates a backup of the project to allow you to roll back to packages.config if necessary.

  1. Open a solution containing project using packages.config.

  2. In Solution Explorer, right-click on the References node or the packages.config file and select Migrate packages.config to PackageReference....

  3. The migrator analyzes the project's NuGet package references and attempts to categorize them into Top-level dependencies (NuGet packages that you installed directory) and Transitive dependencies (packages that were installed as dependencies of top-level packages).

    Note

    PackageReference supports transitive package restore and resolves dependencies dynamically, meaning that transitive dependencies need not be installed explicitly.

  4. (Optional) You may choose to treat a NuGet package classified as a transitive dependency as a top-level dependency by selecting the Top-Level option for the package. This option is automatically set for packages containing assets that do not flow transitively (those in the build, buildCrossTargeting, contentFiles, or analyzers folders) and those marked as a development dependency (developmentDependency = "true").

  5. Review any package compatibility issues.

  6. Select OK to begin the migration.

  7. At the end of the migration, Visual Studio provides a report with a path to the backup, the list of installed packages (top-level dependencies), a list of packages referenced as transitive dependencies, and a list of compatibility issues identified at the start of migration. The report is saved to the backup folder.

  8. Validate that the solution builds and runs. If you encounter problems, file an issue on GitHub.

How to roll back to packages.config

  1. Close the migrated project.

  2. Copy the project file and packages.config from the backup (typically <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) to the project folder.

  3. Open the project.

  4. Open the Package Manager Console using the Tools > NuGet Package Manager > Package Manager Console menu command.

  5. Run the following command in the Console:

    update-package -reinstall
    

Package compatibility issues

Some aspects that were supported in packages.config are not supported in PackageReference. The migrator analyzes and detects such issues. Any package that has one or more of the following issues may not behave as expected after the migration.

"install.ps1" scripts are ignored when the package is installed after the migration

Description With PackageReference, install.ps1 and uninstall.ps1 PowerShell scripts are not executed while installing or uninstalling a package.
Potential impact Packages that depend on these scripts to configure some behavior in the destination project might not work as expected.

"content" assets are not available when the package is installed after the migration

Description Assets in a package's content folder are not supported with PackageReference and are ignored. PackageReference adds support for contentFiles to have better transitive support and shared content.
Potential impact Assets in content are not copied into the project and project code that depends on the presence of those assets requires refactoring.

XDT transforms are not applied when the package is installed after the upgrade

Description XDT transforms are not supported with PackageReference and .xdt files are ignored when installing or uninstalling a package.
Potential impact XDT transforms are not applied to any project XML files, most commonly, web.config.install.xdt and web.config.uninstall.xdt, which means the project'sweb.config file is not updated when the package is installed or uninstalled.

Assemblies in the lib root are ignored when the package is installed after the migration

Description With PackageReference, assemblies present at the root of lib folder without a target framework specific sub-folder are ignored. NuGet looks for a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework and installs the matching assemblies into the project.
Potential impact Packages that do not have a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework may not behave as expected after the transition or fail installation during the migration

Found an issue? Report it!

If you run into a problem with the migration experience, please file an issue on the NuGet GitHub repository.