Overview:
- What’s new in Umbraco 12
- How to get started
- How to provide feedback
- What’s next?
Update May 23, 2023: Umbraco 12 RC2 is now available as are release candidates for Umbraco Forms 12 and Umbraco Deploy 12.
Update June 6, 2023: Umbraco 12 RC3 is now available. See the Umbraco 12 release notes for details on the latest fixes and improvements.
Update: June 27, 2023: Umbraco 12 RC5 is out including some minor fixes for the Content Delivery API, a new login screen, and more. See the Umbraco 12 release notes for details for more information.
What’s new in Umbraco 12
You can see the entire list of features, improvements, and breaking changes in the Umbraco 12 release notes. We appreciate all testing and common use cases that you have done with Umbraco previously. If you encounter any issues, please do raise an issue on the tracker - see below for more details. Let's take a look at some of the highlights and features that we are especially interested in getting feedback on.
Content Delivery API
The Content Delivery API allows you to retrieve Umbraco content items in a JSON format. Making a simple and effective API available as an alternative to the default content retrieval, and importantly a shortcut to adding headless capabilities. The new API is using a modified content model to ensure good performance, and is flexible and extendable.
To get started with the Content Delivery API, please read more in the documentation.
Swagger documentation is available for the Content Delivery API and can be helpful when testing. Note that it does not have full coverage of the APIs yet. See more in the documentation.
What to test?
For the release candidate, we will highly appreciate people testing out retrieving content with the new API, and especially existing solutions that have “real” content. Note there are some limitations listed in the documentation, and this will be updated as they are addressed.
Another area we are keen to get tested is custom and third-party Property Editors to ensure they all work with the fallback serialization. Or, opt-in to the specific property value conversion for the delivery API in cases where the model from the default property value converter does not make sense is also valuable to get tested. This can be done by implementing the IDeliveryApiPropertyValueConverter interface on your existing property value. converters.
Support for Entity Framework Core
Umbraco 12 supports that you can bring your own EF Core context and execute it in the same Scope/Transaction as the services you use from Umbraco.
To get started please see the new documentation for Creating Custom Database Tables with Entity Framework.
The main use case is to allow your custom database tables to be handled using EF Core, while having everything in one transaction, instead of forcing you to use NPoco .
It is important to note that Umbraco still uses NPoco and we do not consider our database structure as part of our Public API with regards to Semantic versioning. To interact with the Umbraco content, it is recommended to use the Umbraco services.
Updated Dependencies
As always, a new major version is a perfect opportunity to ensure our dependencies are up-to-date. Umbraco 12 does have some notable updates:
ImageSharp 3
ImageSharp has been released in a new version that is even more performant and supports even more features from the different file formats.
One of the highlights supported in ImageSharp 3 is HMAC image processing protection.
This feature prevents bad actors from manipulating processing parameters and potentially DOS your site by requesting a large amount of slightly different image URLs that all need to process the image.
ImageSharp 3 is the default implementation in Umbraco, but keep in mind that it has a new license. While you can still use it for free as a transitive dependency through Umbraco, you have to be aware of the licence and implications if you use ImageSharp directly in your code.
For the same reason, we also keep shipping an ImageSharp 2 implementation covering the needs in Umbraco. You can replace ImageSharp3 with the ImageSharp2 implementation by taking direct dependencies on:
- Umbraco.Cms.Imaging.ImageSharp2 (>= 12.0.0-rc)
- Umbraco.Cms.Persistence.Sqlite (>= 12.0.0-rc)
- Umbraco.Cms.Persistence.SqlServer (>= 12.0.0-rc)
- Umbraco.Cms.Targets (>= 12.0.0-rc)
Instead of the single dependency on the meta NuGet package `Umbraco.Cms`.
Other dependencies
NPoco and MailKit have also been updated to the latest versions including potential breaking changes. All other dependencies have only received patch updates.
New Documentation
All these exciting features and updates warrant some documenting. We already have extensive documentation for the Content Delivery API, a tutorial for how to use EF Core, and docs on how to get started with the RC. The Docs team has wrapped it all up nicely in the Umbraco 12 updates.
Breaking Changes
Aside from the breaking changes found in the updated third-party dependencies, Umbraco also has a few binary breaking changes.
The breaking change that potentially will make the most trouble is the fact our migrations now all run in their own transaction. This has been required to make SQLite migrations manageable. Furthermore, this also means that Post Migrations really make sense. Instead, we have added new notifications, so the same use cases can be solved.
Besides these changes, a couple of interfaces and abstract classes have new methods. But we do not expect many to have their own implementations for these. The full list can be found in the release notes.
Known issues
The API versioning configuration used by the Content Delivery API currently sets the global default API versioning configuration. This means it will potentially override yours if you use it, or you can accidentally override the default versioning for the delivery api. We will look into the possibility for us to not rely on the global API explorer and versioning options.
How to get started
Update May 23, 2023: Umbraco RC2 I is now available as are release candidates for Umbraco Forms 12 and Umbraco Deploy 12.
Update June 6, 2023: Umbraco 12 RC3 I is now available. See the Umbraco 12 release notes for details on the latest fixes and improvements.
Like release candidates for minor versions, this release candidate is available on NuGet.
First of all, please note that .NET SDK 7.0.203 is a prerequisite.
To use the new release candidate you can install the new Umbraco dotnet template:
dotnet new install Umbraco.Templates::12.0.0-rc3
Now that the Umbraco template is available, you can create a new Umbraco project using your favorite IDE (Integrated Development Environment) or continue using the CLI (Command Line Interface) commands:
dotnet new umbraco -n MyCustomUmbracoSolution
In CLI the project can be built by navigating to the newly created folder and running the build command:
cd MyCustomUmbracoSolution
dotnet build
At this point, the project is ready to be executed:
dotnet run
This will boot the project, and write the log to the console. The website is now running on the Kestrel server, and it will be available on the ports written in the console.
How to provide feedback
If you find issues that are not already reported, please report them on the GitHub tracker by following the link or selecting “🐛 Bug Report” when creating a new issue.
What’s next?
Even though this release is considered feature complete, there will be additional RC releases as we make progress and get feedback, although at this stage they should be minor bug fixes based on testing and addressing known issues.
We plan to make new release candidate versions available as bugs are fixed, and you can always try out the latest nightly build if you want to test fixes made since the RC.
Besides fixing potential bugs and known issues in the CMS, we will focus on making HQ Packages such as Umbraco Forms and Deploy available. We’re also focusing on ensuring that Umbraco 12 is available on Umbraco Cloud when released and continuing the efforts to document Umbraco 12.
All of this leads to the public release of Umbraco 12, which is targeted for June 29, 2023.
Now, go on and take the Umbraco 12 Release Candidate for a spin - we look forward to hearing your feedback 🙌
