Migrate from packages.config to PackageReference
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
PackageReferencenode) 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
packagesfolder 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.
- NuGet PackageReference is not available in Visual Studio 2015 and earlier. Migrated projects can be opened only in Visual Studio 2017 and later.
- Migration is not currently available for C++ and ASP.NET projects.
- Some packages may not be fully compatible with PackageReference. For more information, see package compatibility issues.
In addition, there are some differences in how PackageReferences work compared to packages.config. For example, constraining upgrade versions is not supported by PackageReference, but PackageReference adds support for Floating Versions.
Migrate packages.config to PackageReference...option is not available in the right-click context menu
When a project is first opened, NuGet may not have initialized until a NuGet operation is performed. This causes the migration option to not show up in the right-click context menu on
Perform any one of the following NuGet actions:
- Open the Package Manager UI - Right-click on
Manage NuGet Packages...
- Open the Package Manager Console - From
Tools > NuGet Package Manager, select
Package Manager Console
- Run NuGet restore - Right-click on the solution node in the Solution Explorer and select
Restore NuGet Packages
- Build the project which also triggers NuGet restore
You should now be able to see the migration option. Note that this option is not supported and will not show up for ASP.NET and C++ project types.
Before migration begins, Visual Studio creates a backup of the project to allow you to roll back to packages.config if necessary.
Open a solution containing project using
In Solution Explorer, right-click on the References node or the
packages.configfile and select Migrate packages.config to PackageReference....
The migrator analyzes the project's NuGet package references and attempts to categorize them into Top-level dependencies (NuGet packages that you installed directly) and Transitive dependencies (packages that were installed as dependencies of top-level packages).
PackageReference supports transitive package restore and resolves dependencies dynamically, meaning that transitive dependencies need not be installed explicitly.
(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
analyzersfolders) and those marked as a development dependency (
developmentDependency = "true").
Review any package compatibility issues.
Select OK to begin the migration.
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.
Validate that the solution builds and runs. If you encounter problems, file an issue on GitHub.
How to roll back to packages.config
Close the migrated project.
Copy the project file and
packages.configfrom the backup (typically
<solution_root>\MigrationBackup\<unique_guid>\<project_name>\) to the project folder. Delete the obj folder if it exists in the project root directory.
Open the project.
Open the Package Manager Console using the Tools > NuGet Package Manager > Package Manager Console menu command.
Run the following command in the Console:
Create a package after migration
Once the migration is complete, we recommend that you add a reference to the nuget.build.tasks.pack nuget package, and then use msbuild -t:pack to create the package. Although in some scenarios you could use
dotnet.exe pack instead of
msbuild -t:pack, it is not recommended.
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
contentfolder are not supported with PackageReference and are ignored. PackageReference adds support for
contentFilesto have better transitive support and shared content.
Potential impact: Assets in
contentare 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
.xdtfiles are ignored when installing or uninstalling a package.
Potential impact: XDT transforms are not applied to any project XML files, most commonly,
web.config.uninstall.xdt, which means the project's
web.configfile 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
libfolder 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.