Don't miss out Virtual Happy Hour this Friday (April 26).

Try our conversational search powered by Generative AI!

Son Dinh Nguyen
Aug 17, 2023
(5 votes)

Change in package structure in CMS Core 12.17.0


As of today, EPiServer.CMS.Core relies on SixLabors ImageSharp v2 to do image manipulations under the hood. There have been quite a few WEBP issues being raised lately, which have their root in this library. In order to fix them, we need to upgrade the library to v3. But there are binary incompatible changes between v2 and v3. For partners, who also use ImageSharp v2 directly in their code base, this upgrade could be a breaking change.


We move the image service's implementation to a separate package, EPiServer.ImageLibrary.ImageSharp, and release it independently from CMS Core. There are two major versions of the package. v1 of the package depends on ImageSharp v2, and v2 of the package depends on ImageSharp v3. You are encouraged to use EPiServer.ImageLibrary.ImageSharp v2 unless ImageSharp API is consumed directly in your code.

What needs to be done

1. For 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, just update the umbrella package, then you are done. The WEBP issues will be fixed by updating EPiServer.ImageLibrary.ImageSharp

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

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.1" />
<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" />

2. For projects with direct reference to CMS Core, e.g. not install EPiServer.CMS

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, saying, "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."

Aug 17, 2023


Vladimir Vedeneev
Vladimir Vedeneev Aug 17, 2023 10:07 AM

What about license change in ImageSharp v3?

Unlike v2, It is not "free" anymore.

So if we consume v3 through EPiServer dependency - can be use it without separate license for the ImageSharp v3?

Vladimir Vedeneev
Vladimir Vedeneev Aug 17, 2023 10:12 AM

Specifically, reading here

Works in Source or Object form are licensed to You under the Apache License, Version 2.0 if.


- You are consuming the Work as a Transitive Package Dependency.

So if we pay for DXP, and having transitive reference to ImageSharp v3 through episerver libraries - we are granted the license by Optimizely?

Magnus Rahl
Magnus Rahl Aug 17, 2023 11:05 AM

It will be a transitive dependency. For Optimizely it is a direct dependency, and we have obtained a commercial license to cover this.

Karol Berezicki
Karol Berezicki Sep 3, 2023 05:48 PM


Will you keep the EPiServer.ImageLibrary.ImageSharp aligned with ImageSharp releases?
The ImageSharp has released 3.0.1 and 3.0.2, which contain bugfixes and security patch respectively, but EPiServer.ImageLibrary.ImageSharp in version 2.0.1 resolves to ImageSharp 3.0.0.

Of course, it possible to install ImageSharp in v3.0.2 directly, but it will be no longer transitive dependency.

Karl-Johan Sjögren
Karl-Johan Sjögren Sep 5, 2023 07:47 AM


You are encouraged to use v2 unless ImageSharp API is consumed directly in your code.

Is this because of licensing or the breaking changes? We use ImageSharp directly to resize some images in a background job, would that caes still be covered under your license if we got the ImageSharp library through EPiServer.ImageLibrary.ImageSharp?

/ Karl-Johan

Magnus Rahl
Magnus Rahl Sep 5, 2023 09:37 AM

@Karol This is a grey area and I am not a lawyer... I think the intent of the transitive dependency clause would permit you to reference it directly if you do it only to force the nuget dependency resolution. Perhaps using central package management is a way to get out of that grey area, I haven't tested.

@Karl-Johan I wonder if that sentence is actually a typo, that you are encouraged to use v3 unless you call the API directly. It is more reasonable to keep v2 if you actually call it, both from a breaking changes perspective and in a licensing perspective. Calling the API directly might puts you at "risk" of having to carry your own license.

Son Dinh Nguyen
Son Dinh Nguyen Sep 5, 2023 11:01 AM

@Karol: In addition to Magnus' answer with central package management, that would be possible with transitive pinning enabled.

@Magnus: Updated to make it less confused.

Magnus Rahl
Magnus Rahl Sep 5, 2023 11:13 AM

@Son, thanks for the clarification, it makes sense now that it is clear which package the version refers to. And yes, transitive pinning is what I had in mind.

Karol Berezicki
Karol Berezicki Sep 5, 2023 12:26 PM

Hi Magnus Rahl and Son Dinh Nguyen,

Thanks for the response and suggestion, I'll try the transitive pinning.
However, while it may work for me, not every project will use the CPM, and
probably, not everybody will be aware, that there may be some bug or exploit in ImageSharp that should be patched using transitive pinning - that's why I've asked if the package will keep up with ImageSharp releases.
I'm not a lawyer either, but I think installing the package directly will count as direct dependency.

Karol Berezicki
Karol Berezicki Sep 19, 2023 08:05 PM

I've tested the transitive pinning, and in fact it does work, but currently only in Visual Studio.
For Rider users - unfortunately there's a bug and package is not resolved correctly, see:

Son Dinh Nguyen
Son Dinh Nguyen Sep 20, 2023 06:44 AM

Transitive pinning support was shipped with .NET SDK 6.0.300, so that shouldn't be an issue with dotnet build. For JetBrains Rider, I had to change restore engine to Console as a workaround (go to Settings > Build, Execution, Deployment > NuGet > Restore).

Karol Berezicki
Karol Berezicki Sep 20, 2023 07:53 PM

Hi Son Dinh Nguyen,

Thanks for the tip with workaround - it worked :) 
I'll relay this info to the Rider YouTrack, might help somebody :)

Please login to comment.
Latest blogs
Solving the mystery of high memory usage

Sometimes, my work is easy, the problem could be resolved with one look (when I’m lucky enough to look at where it needs to be looked, just like th...

Quan Mai | Apr 22, 2024 | Syndicated blog

Search & Navigation reporting improvements

From version 16.1.0 there are some updates on the statistics pages: Add pagination to search phrase list Allows choosing a custom date range to get...

Phong | Apr 22, 2024

Optimizely and the never-ending story of the missing globe!

I've worked with Optimizely CMS for 14 years, and there are two things I'm obsessed with: Link validation and the globe that keeps disappearing on...

Tomas Hensrud Gulla | Apr 18, 2024 | Syndicated blog

Visitor Groups Usage Report For Optimizely CMS 12

This add-on offers detailed information on how visitor groups are used and how effective they are within Optimizely CMS. Editors can monitor and...

Adnan Zameer | Apr 18, 2024 | Syndicated blog