Upgrade to CMS Core 12.17.0

Optimizely Content Management System (CMS) Core (EPiServer.CMS.Core) version 12.17.0 introduces a reliance on SixLabors ImageSharp for image manipulation.

❗️

Warning

Potential breaking change:
SixLabors ImageSharp v3 fixes WEBP issues in SixLabors ImageSharp v2, but there are binary-incompatible changes between v2 and v3. For partners, who use ImageSharp v2 directly in their code base, upgrading to CMS 12.17.0 could be a breaking change.

The image service's implementation was moved to a separate package, EPiServer.ImageLibrary.ImageSharp, and released independently from CMS Core. There are two major versions of the package:

• v1 of the package depends on ImageSharp v2
• v2 of the package depends on ImageSharp v3

🚧

Important

You should use v2 unless ImageSharp API is consumed directly in your code.

Projects with EPiServer.CMS umbrella package reference

When EPiServer.CMS 12.23.0 is out, which has reference to EPiServer.CMS.Core 12.17.0, update the umbrella package, and then you are done. The WEBP issues are fixed by updating EPiServer.ImageLibrary.ImageSharp.

<PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="2.0.0" />

If you are on EPiServer.CMS 12.22.x and below and still want to fix WEBP issues, include these package references:

<PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="2.0.0" />
<PackageReference Include="EPiServer.Hosting" Version="12.17.0" />
<PackageReference Include="EPiServer.CMS.AspNetCore.TagHelpers" Version="12.17.0" />
<PackageReference Include="EPiServer.CMS.AspNetCore.HtmlHelpers" Version="12.17.0" />

Projects with direct reference to CMS Core

Besides upgrading CMS Core to v12.17.0 and above, you also need an additional reference:

<PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="1.0.0" />

Missing this package would cause an exception to be thrown on startup that says, "It needs to either update EPiServer.CMS package to the latest version, which has dependency on EPiServer.ImageLibrary.ImageSharp package, or install EPiServer.ImageLibrary.ImageSharp package directly into your project."