[Breaking change]: Separating ImageSharp and SQL Server dependencies

[ronaldbarendse]

Description

In PR umbraco/Umbraco-CMS#12907 we separated the ImageSharp and SQL Server dependencies by:

• Introducing a new Umbraco.Cms.Imaging.ImageSharp project that contains the SixLabors.ImageSharp and SixLabors.ImageSharp.Web dependencies and moving all related code from Umbraco.Cms.Infrastructure and Umbraco.Cms.Web.Common to this project;
• Moving the NPoco.SqlServer dependency from Umbraco.Cms.Infrastructure to Umbraco.Cms.Persistence.SqlServer and updating/moving all related code to this project;
• Introducing a new Umbraco.Cms.Targets project that only contains the required dependencies and build targets and make Umbraco.Cms a metapackage that also includes the optional dependencies (thereby keeping existing behaviour when referencing this page).

Version

Umbraco 11

Previous behavior

You were required to reference Umbraco.Cms in your website project to get all required dependencies and build targets, but this also included 'optional' dependencies like ImageSharp (for image manipulation), SQL Server and SQLite (for database provider/persistence support).

Note
Even though some dependencies are 'optional', you will either need to provide your own implementation or reference at least one implementation for Umbraco to function as expected.

New behavior

All required dependencies and build targets have moved to Umbraco.Cms.Targets and Umbraco.Cms references this package in addition to these 'optional' packages:

• Umbraco.Cms.Imaging.ImageSharp
• Umbraco.Cms.Persistence.Sqlite
• Umbraco.Cms.Persistence.SqlServer

This means the existing package reference (and installation/upgrade instructions) can stay the same as before:

<ItemGroup>
  <PackageReference Include="Umbraco.Cms" Version="11.0.0" />
</ItemGroup>

This is also the same as using the following package references, although you can now replace or remove some of the 'optional' package references:

<ItemGroup>
  <PackageReference Include="Umbraco.Cms.Targets" Version="11.0.0" />
  <PackageReference Include="Umbraco.Cms.Imaging.ImageSharp" Version="11.0.0" />
  <PackageReference Include="Umbraco.Cms.Persistence.Sqlite" Version="11.0.0" />
  <PackageReference Include="Umbraco.Cms.Persistence.SqlServer" Version="11.0.0" />
</ItemGroup>

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

This change was introduced because of the following reasons:

• Create a better, clean/layered architecture;
• Make swapping out dependencies (implementations/services) easier, including the possibility of upgrading to newer major versions;
• Avoid issues with license changes, like those announced in ImageSharp v3.

Note
The licence change in ImageSharp v3 won't directly impact users of Umbraco, because it's a transitive package dependency and therefore still licensed under the Apache License 2.0.

Recommended action

Users that extended the functionality of ImageSharp or depend on specific SQL Server implementations/references might need to update their code to account for the moved classes and dependencies.

Affected APIs

A list of all breaking changes is available on PR umbraco/Umbraco-CMS#12907 (comment).