Overview:
Update 15-02-2022: Added information to the Umbraco logo in the backoffice feature.
Umbraco 9.3 provides a number of new and improved features that make it easier to configure and work with Umbraco 9. The emphasis is on developer experience so many of the additions will be noticeable when you are creating functionality in specific areas. This in turn makes it easier to provide value and functionality for your Umbraco projects.
You also find bug fixes and smaller improvements that help make things a little more smooth. Here are some of the highlights of the release:
Umbraco 9 uses ASP.NET Core Identity for all authentication, both for backoffice Users and for Members, and this brings a host of options for developers to customize and extend. A popular use case is to add external login providers to provide a better authentication experience in an Umbraco installation. Having the ability to use an OAuth service, e.g. your Google account, to log in to the Member section on an Umbraco powered website not only makes it a lot easier but also more secure. It can also be a requirement to use a specific service, such as Okta or Microsoft 365 to log in to an internal site or intranet.
Umbraco 9 was already a big improvement on earlier Member authentication, going from a custom Membership provider to ASP.NET Core Identity, and with Umbraco 9.3 you get even more options to work with. If you’re familiar with adding external login providers to backoffice Users, you’ll be right at home.
All that is required to get up and running is a bit of dependency injection, using AddMemberExternalLogins on IUmbracoBuilder, to configure the service you want to integrate with and then register the configuration in Startup.cs. You can find a complete example in the External login providers documentation which has been updated with the new Member features.
If you want an example of how to implement this in your authentication flows you can use the Macro snippets for Login and Edit Profile. They have been updated for Umbraco 9.3 to show all external login providers registered with this pattern.
Aside from adding the option to authenticate with OAuth providers, you might also need to link account creation and synchronization to an external service. This is also a lot easier in Umbraco 9.3 with new auto-linking options allowing to create new a Member or link existing accounts to update Member data based on the external login provider.
Again, this works similar to what was already implemented for users, so if you’ve tried that it should be familiar ground. Detailed explanations for both Users and the new auto-linking options for Members can be found in the Linking External Login Provider accounts documentation.
The last big update to Member authentication in Umbraco 9.3 is new features for adding 2FA to Member login flow. Enabling two-factor authentication is a great way to increase the security of a system. With Umbraco 9.3 it is a lot easier to enable for Umbraco Members. You can set up 2FA to use an authentication service (available from many vendors such as Microsoft, Google and many more) or even create your own codes and send them via email/SMS. Using an authentication app/service is viewed as the more secure option and the recommended approach unless you have specific requirements.
You find an all-new interface, ITwoFactorProvider, for adding 2FA via dependency injection as well as detailed documentation of the new improvements. It’s also worth mentioning that you can find examples of adding 2FA to your Member UI in the Login and Edit Profile Macro snippets.
There are cases where you’d want to store files uploaded to the Media Library in a different path than the default location ~/media. This can easily be configured in Umbraco 9 via the UmbracoMediaPath property in appsettings.json or via a composer. If you want to store all your Media Library files in a different folder, this can be updated by adding:
That’s all well and good but a few things have been addressed in Umbraco 9.3 to provide more control over where the Media is stored and how files are served. First off, the above change will also change the URL Media is served from to “hostname/assets/…” which might not be intended. Secondly, it would require you to move any previously uploaded files to the new location.
In Umbraco 9.3 you’ll find a new configuration option that can be a useful alternative - say hi to UmbracoMediaPhysicalRootPath. This allows you to configure the physical location exclusively while preserving the standard URL for Media:
So in this case the files would be stored in “X:/Shared/Media” and served from “hostname/media/…”. Only changing the physical path and not the URL also allows for easy configuration of store files outside the wwwroot folder, in the above example this is shown as a network drive - easy and friendly 🙂
Another big improvement is that Media and App_Plugins files have been merged into the default WebRootProvider that's used by the whole ASP.NET Core framework. This provider is used to serve all static files using a single UseStaticFiles() call that adds a single StaticFileMiddelware, making it easier to configure. You can find examples of this here:
This currently only works for the PhysicalFileSystem. We'll release an updated version of Umbraco.StorageProviders.AzureBlob to ensure you get the same behavior on Umbraco Cloud.
If you’ve been looking for ways to run custom code based on the Umbraco runtime starting, stopping or restarting there’s great news. In addition to the existing UmbracoApplicationStartingNotification and UmbracoApplicationStoppingNotification two new notifications have been added in Umbraco 9.3:
These are specifically tied to the Umbraco runtime, which can differ from the generic ASP.NET Core host application lifetime. All of the notifications have a new IsRestarting property to indicate whether the starting/started/stopping/stopped notification is published as part of a restart. Examples and details can be found in the original PRs linked above.
The Umbraco logo has been re-introduced to the backoffice and the Umbraco logo font has been added to the login screen (previously only showed the logo).
Logo + logo font on the Umbraco login screen
This has been done to increase brand awareness, or in plain speak, let people know they are using Umbraco CMS. The logo is in the same position in the backoffice as on the login screen.
Umbraco logo in the backoffice
Clicking the logo in the backoffice shows the current version number and a link to the umbraco.com website.
Raising brand awareness is important for everyone working with Umbraco. For many, it can be a big help to know the system they are using. It allows users of the backoffice to find information, documentation, engage with, or maybe even become regular contributors in the Umbraco community.
Update 15-02-2022: We have been made aware that this functionality was not included in the release candidate and was introduced late in the process which has resulted in limited time for user feedback. That is a mistake on our part. We should not be introducing new functionality or features, small or large, during the RC phase. This should only be for addressing issues before the public release.
Furthermore, there is a proposed additional ability to hide the logo in the backoffice, should that be a requirement. This is targeted for Umbraco 9.4 (March 24th) and Umbraco 8.18 (February 24th). You can see all the details on the PR: https://github.com/umbraco/Umbraco-CMS/pull/11999.
There are also 2 performance improvements regarding property data that silently made their way into this release (they got merged up from the latest Umbraco 8 branch and are also part of the 8.18 release candidate).
Prune focal point and cropping values
The Image Cropper and Media Picker (v3) editors store their values into the database as JSON, but previously included indentation and redundant data. The default focal point and empty crops are now cleaned up and the crop width/height isn't stored as property data anymore (as they were already retrieved from the data type configuration). These savings can add up significantly, especially when you have a large number of images in your Media section (and even more if you have a lot of different crops configured). Our internal tests showed cases where we were able to reduce the data to only 7,5% of the original size. More information can be found on the PR: https://github.com/umbraco/Umbraco-CMS/pull/11805
Streamlined JSON data
During our testing, we also noticed a lot of other editors that stored indented JSON and some even empty values (empty strings or JSON arrays). Umbraco already skips adding database rows for property data values that are NULL, so we now take advantage of that by ensuring these empty values are converted to NULL. This again reduces the amount of stored property data significantly, as we expect most installations will have empty values in optional textboxes, tags (eg. for SEO keywords). Check out the PR, including our testing method: https://github.com/umbraco/Umbraco-CMS/pull/11806.
Both these improvements will only be applied when saving/publishing items from the backoffice, so you won't see any savings right away. In the case of content, you might want to configure a cleanup policy (released in Umbraco 9.1) to remove older content versions. You can find more on how to set this up in the Content Version Cleanup documentation.
Because this data is stored in the Umbraco content cache/NuCache (the cmsContentNu database table, local files and memory) and both the ExternalIndex/InternalIndex of Examine, this should have a compounding, positive impact on CPU, memory and disk space usage.
Umbraco 9.3 also includes the following dependency updates
A couple of the changes in this release did not make it into the 9.3 release candidate. These are performance enhancements and the addition of the logo and logo font to the backoffice and login screen.
Of the 27 bug fixes and feature additions in 9.3.0, a total of 13 of them have been contributed by the community, by 7 unique contributors.
We’re welcoming two brand new contributors who have made their first pull request for Umbraco CMS; they’re marked with a star below. Welcome to the contributor club Johannes and Maarten! 🏆
⭐ = First pull request to any Umbraco repository
And of course, as a thank you, we’ve just added another bunch of trees to our growing plot for today’s 9.3.0 release to celebrate your contributions! 🌳🌲🌴
As always, from today, all new Umbraco 9 projects on Umbraco Cloud will be running 9.3. For all our Umbraco Cloud customers with existing projects, this upgrade is only 2 minutes away:
We’ve wrapped it all up for you, so all you have to do now is follow these steps:
As always, installation and release notes can be found on Our: https://our.umbraco.com/contribute/releases/930
This release is also available from Nuget: https://www.nuget.org/packages/Umbraco.Cms/9.3.0
Developer experience is at the forefront of Umbraco 9.3 with improvements to Members such as 2FA and auto-linking of external accounts, and better support for serving assets/media outside the wwwroot folder. You try this and a whole lot more in the Umbraco 9.3 release candidate.