LibrarySites.Banner

Sitecore 9.1 NuGet Changes and You

Update March 4, 2019:

Based on community feedback, Sitecore 9.1 has been re-published to our NuGet feed using the public product release versioning, i.e. 9.1.0. We have still removed the NoReferences packages, but will no longer need to publish a feed per breaking release. Moving to PackageReference is still beneficial, and we'll still be working to release the NuGet packages concurrent with our releases.

---

Hello Sitecore Developer Community! Have you downloaded and installed Sitecore 9.1 yet?

It went a bit under the radar, but as far as I'm aware, this is the first time Sitecore has released platform NuGet packages concurrent with the platform release. We've changed how we release these, to simplify the process and ensure that what's released is what we've tested -- that is, the same packages that we use in our own internal development.

There are two major impacts of this however that will require you to refactor your NuGet references when upgrading to Sitecore 9.1:

  1. We are no longer publishing NoReferences packages. This would require modifying or recreating our packages before publishing them externally, which was what we were trying to avoid in the first place! More below on alternative approaches that achieve the same goal of avoiding large dependency lists.
  2. The package versions no longer match the product release versions. We use SemVer internally, so the package version will be the "technical" version, and for some packages may not even change with each Sitecore release. To determine the packages for a particular release, you can refer to the version meta package.

 

Feeds per Breaking Release

We know #2 has a big impact on you in your day-to-day development and upgrades. It's painful to refer to the meta package every time you want to add a NuGet reference, and for upgrades, doing this for reference in every project would be quite painful (especially when using a project-per-module Helix approach). Therefore moving forward, we are going to be publishing new feeds for each breaking release of the platform (9.1, 9.2, 9.3, etc). The feed will contain all the assemblies needed for the platform. You can see this already with the NuGet feed for 9.1.

There will also be feeds for other breaking releases of applications/services such as Publishing and Identity Server. The exact naming and structure of these is TBD.

Non-breaking product updates will remain on the same feed. This could mean that you still need to refer to the meta package if you need to add an assembly for a particular update level. However, given Sitecore's new release cadence and non-breaking update strategy, you should be moving to the latest update more easily/frequently, and thus will be able to take the latest from the NuGet feed for your current version.

Keep an eye out for scripts or tooling from us as well to validate that your references are correct for the specific version and update level you are targeting. The migration scripts below are a first step toward that.

 

Open 3rd Party References

Another noteworthy change is that 3rd party references no longer require an exact version match in our package dependencies. This allows you to upgrade them, though keep in mind that you will not be able to get support from Sitecore on any issues caused by that upgrade.

 

Ignoring Dependencies with NuGet

Even though we've removed the NoReferences packages, you can achieve similar behavior by using NuGet's builtin ability to ignore dependencies when installing or upgrading packages.

Adding Packages

NuGet Package Manager

Using the NuGet Package Manager in Visual Studio:

  1. Locate the package to be installed
  2. Change the Dependency Behaviour option to Ignore Dependencies
  3. Click Install

Package Manager Console

Using the Package Manager Console in Visual Studio, enter the command:
Install-Package -Id <package name> -IgnoreDependencies -ProjectName <project name>

Updating Packages

NuGet Package Manager

Using the NuGet Package Manager in Visual Studio:

  1. Select the Updates tag
  2. Change the Dependency Behaviour option to Ignore Dependencies
  3. Click Update

Package Manager Console

Using the Package Manager Console in Visual Studio, enter the command:
Update-Package -Id <package name> -IgnoreDependencies -ProjectName <project name>

 

Updating to the New Feed and Versions

In a large solution, it would be a lot of tedious effort to manually replace your existing NuGet references during an upgrade to 9.1. You might consider scripting this with some PowerShell. The platform meta package can even be used to automate this, by allowing you to programmatically look up the correct version of each package.

Not sure where to start? Here's an example that might work for you. Your mileage may vary depending on your project file structure. (If you're already using PackageReference, here's a similar example script.)

It's worth noting too that these scripts should work for future updates and upgrades, simply by changing the Target Version and potentially the NuGet feed URL.

 

Consider Updating to PackageReference

This change is a great opportunity to consider updating your Sitecore solutions to use the new PackageReference NuGet capability of Visual Studio 2017. There are many benefits to PackageReference, but a primary benefit here is that it uses transitive dependencies -- that is, a package's dependencies are not added directly to your project. This effectively gives you the same benefits of the now-retired NoReferences packages, with the benefits of a much cleaner project file and no packages.config file.

The downside is that PackageReference is currently not well supported by ASP.NET projects on .NET Framework. It does not support all the features of packages.config. The most notable for Sitecore development is that content in packages has been replaced with contentFiles, which themselves do not seem to be well supported in non-netcore ASP.NET projects. Though Microsoft is working on this, effectively it means that Sitecore modules which distribute via NuGet and include configuration patches (such as Unicorn) will need to instruct developers to manually copy the config patches into their projects when installing or upgrading.

This is probably why migrating ASP.NET projects to PackageReference is not supported yet in Visual Studio either, despite other project types having builtin support for this. You can "trick" Visual Studio by temporarily changing the ProjectTypeGuids in the project file, but be careful when doing this with the pre-9.1 Sitecore NuGet feed -- all the packages are flagged as developmentDependency, which results in the migration tool not including them in compilation by default (ugh). The most reliable method I've found to do the migration for ASP.NET projects is this Visual Studio Extension.

If you want to migrate, I recommend doing it before you update to Sitecore 9.1, since it will make moving to the new feed much easier. (Once again, here's an example script to assist in that move with PackageReference).

I know this seems like a lot of headache -- why bother? But I do think it's really worth the benefits. Both Habitat and Habitat.Home made the jump already, with few regrets. And it is the future for NuGet.

One final note on PackageReference: Given transitive dependencies, you may be tempted to just reference the meta package everywhere. Get the whole platform in one reference! Easy right? It would be, except the number of dependencies is huge, resulting in substantial increases in build time, and actually bogging down Visual Studio itself, especially with ReSharper enabled. You've been warned!

 

In Closing

Though it creates a bit of upgrade effort for 9.1, I'm excited that with these changes, we can now release our NuGet packages concurrent with each Sitecore release. The tips and example scripts above should help minimize the impact on your upgrades.

Have any feedback? Feel free to leave it below, or reach out to me on the Sitecore Community Slack or Twitter (@techphoria414).

 

Required Disclaimer: Scripts and direction provided within are provided as-is, without any warranty, and are not supported by Sitecore Product Support Services.