Change in package structure in CMS Core 12.17.0
Motivation
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.
Solution
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."
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?
Specifically, reading here https://github.com/SixLabors/ImageSharp/blob/main/LICENSE
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?
It will be a transitive dependency. For Optimizely it is a direct dependency, and we have obtained a commercial license to cover this.
Hello,
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.
@MagnusRahl 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@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.
@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.
@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.
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.
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: https://youtrack.jetbrains.com/issue/RIDER-87411
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).
Hi Son Dinh Nguyen,
Thanks for the tip with workaround - it worked :)
I'll relay this info to the Rider YouTrack, might help somebody :)