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.
