What are PackageReferences and how will they help optimise the way I deal with NuGet packages?

Question

With version 9.1, Sitecore changed their NuGet library to no longer include NoReferences versions of their assemblies. This is also mentioned in How do I reference Sitecore binaries from NuGet?.

One alternative being brought up, is to shift to using PackageReferences (applicable only to VS2017 and above). What is that? And what would be involved in making the switch?

Answer 1

PackageReference is a new way to allow NuGet to manage your projects references. Before this, adding a NuGet package would update both the packages.config file and the .csproj file for your solution. The packages.config contains the package name and version, and the .csproj file contains a reference to the downloaded package on disk.

Enter PackageReference

From VS2017 you can now use the PackageReference node to manage NuGet dependencies directly within the .csproj file. This still uses other aspects of NuGet like the nuget.config file, all those settings are still applied.

Because of this, you get a lot more control over your NuGet dependencies. For example, you can use MSBuild conditions to choose package references per target framework, configuration, platform etc...

Adding a PackageReference

To add a package reference, you just need to add it to the project file like this:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Sitecore.Kernel" Version="12.0.0" />
    <!-- ... -->
</ItemGroup>

You can specify the version. If you specify a specific number, that means that it is >=12.0.0. The preference is on the lowest version that meets that requirement.

One very cool thing is Floating Versions. With floating version you can do things like "use the latest 12.0.x version". For example:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Sitecore.Kernel" Version="12.0.*" />
    <!-- ... -->
</ItemGroup>

Benefits of using PackageReference

• You can manage all your project dependencies in one place
• Easier to see your projects actual dependencies - With PackageReference, you only add direct dependencies to your .csproj file. If a NuGet package has dependencies, they do not clutter up your project file anymore.
• Performance - PackageReference packages are saved to a global-packages folder instead of a local solution folder. Uses less disk space, is a bit faster when you already have packages downloaded. See Managing the global packages and cache folders
• Control over dependencies and content flow using the MSBuild conditions as mentioned above

Packages.config is not being developed

One big benefit of moving to this way of handling NuGet packages is that the existing packages.config is no longer under active development, whereas PackageRefrence is https://github.com/NuGet/Home/issues/6763

Migrating to PackageReference

There is a way in VS to migrate existing packages.config setups to PackageReference. In your Solution Explorer, right-click on the References node or the packages.config file and click Migrate packages.config to PackageReference

This should migrate you over to PackageReference - but there are known issues with that. See here for details on the known issues Migrate from packages.config to PackageReference

There is also a NuGet PackageReference Updater tool on the VS market place: NuGet PackageReference Updater

Conclusion

PackageReference is the future and has a number of benefits over packages.config. Its worth looking into migrating your projects, but just be aware that there are some limitations with existing packages, especially Sitecore modules like Glass and Unicorn that include example config files. They will need updates to fully support that with PackageReference, so hopefully that will happen soon.

Some references:

• Migrate to PackageReference with 3 clicks
• Migrate from packages.config to PackageReference
• Package references (PackageReference) in project files