On Thursday, June 29 2023 Umbraco 12 was released. Personally, I've been looking forward to this release for about 2 years as it's the first version of Umbraco that comes with an officially supported way to build a headless CMS using the core Umbraco product. In this article, you will learn everything you need to know in order to get up to speed with Umbraco 12.
This guide not only goes into detail about all of Umbraco 12's new features, it also contains step-by-step instructions on how to either install Umbraco 12 from scratch or upgrade your existing Umbraco site to v12. In essence, if you want to become a Umbraco 12 master, read on 🔥🔥🔥
We will start our journey by discussing what you need to know about v12. The first thing to note is that v12 is fully compatible with .NET 7. In terms of lifetime support, the v12 support window will mirror the .NET 7 release cadence. In case you didn't know Umbraco adopted the .NET release cadence as of v10. Each new version of .NET (and Umbraco) will be released as either a Long Term Support (LTS) release or a standard release.
Depending on what release types Umbraco gives a version, will depend on how long they will support it. If you visit the Umbraco release roadmap, you will see that Umbraco is planning to release another version of Umbraco this year. Umbraco 13 is planned for release on December 14, 2023. This release will be in line with .NET 8 which will be a LTS release.
In terms of new features, as well as offering all the classic Umbraco goodness that has been added to the CMS from all the previous releases you also get a few new ones. First, you can find a complete list of features from the official documentation page here. The big exciting new feature for me is the content delivery API.
Content delivery API is a fancy term for headless API. Using the content delivery API you can now build your Umbraco-powered website using a single-page-app, or a framework like NextJS. Previously this was possible, however, you would have had to build all the integrations and APIs yourself, which was not ideal!
Within this specific article, we will not look at how to create a headless website with Umbraco, however, I will be doing one or more videos on this topic which will be available from here.
By default the content delivery API will be turned off, so you will need to enable it in config. If you want to access preview/draft content via the API you will also need to create an API key. After enabling content delivery, you will get access to several new API end-points that will allow you to perform actions like, get by ID, or get multiple items. You can then use these endpoints to get any content and data created by content editors within Umbraco. In terms of figuring out how it all works, the good news is that Umbraco now ships with Swagger. Swagger is a tool that allows companies to document their APIs, so you can test out the API and understand how it works before you need to implement it in code.
Another new and noteworthy feature is support for Entity Framework core. This is handy if you need to work with custom database tables. This new integration will allow you to use an object mapper so you can work with C# objects when you need to communicate with your custom database tables. Having out-of-the-box support with Umbraco-related providers means working with entity-framework with Umbraco is now much easier. Working with entity framework was possible in earlier versions, however, you would have needed to install this package yourself manually and then configure it, which is a hassle
Other noteworthy features that are included within Umbraco 12 include:
ImageSharp has been upgraded to v3. The main benefits of moving to v3 over v2 are improved performance and security. v3 supports .NET 6 which means it processes things quicker. It also contains improved DDOS detection for added security. It might be worth noting that if you need to use it yourself in anger, you may need to purchase an ImageSharp license, however, all the out-the-box stuff is still free!
New Workflow 12 module. This improves on the new Workflow module added in Umbraco 11
Updates to Umbraco Forms and Deploy
How To Install Umbraco 12
Before you can install Umbraco v12, you will need to ensure you have the correct prerequisites setup. The main thing that you will need to decide upon is the database. When you install Umbraco, the installer will need to create a database somewhere. My recommendation is to create this CMS database within some flavor of MS SQL Server that runs locally on your machine. The default installation option will be for the installer to create an SQLite database that will live within your website's file structure. Using SQL Lite is not ideal if you want to convert your dev environment into a production database later on. You can't magically convert an SQLite file into a SQL server database!
This means that before you install Umbraco you will need to have SQL installed and configured to allow a database user to access a blank database. As I've created a video on how to set all this up previously, instead of me re-inventing the wheel, if you need step-by-step instructions on how to do this, I recommend you check out this video I created on Umrbaco 9 installation. The developer prerequisites haven't changed since that video!
My recommended way for you to install this new version of Umbraco is to install it via the terminal. It is possible to create a new website directly within Visual Studio, however, I find the terminal easier and quicker. Even if you have worked with previous versions of Umrbaco before, you will need to install the latest v12 template and in order to install this v12 template, you can run this command:
After installing the Umbraco installation template you can use it to create a new website. This is possible using this command:
After the project files have been created, you can run your website by switching to the base project folder and then running the normal .NET run commands, like this:
This should now launch your website and the Umbraco installation wizard should start. This wizard will allow you to define the database set-up and define an admin user. One useful thing to note is that you can access the backend by adding /umbraco to the end of the URL.
Upgrade To Umbraco 12
Instead of creating a new website, you might want to upgrade your existing Umbraco instance instead. In order to upgrade you need to do two things. First, you need to make sure the target framework for your website project is set to .NET 7.0. If your project is set to use .NET 6 or below, you will encounter an error when you upgrade. Remember, you can set the target framework, by right-clicking on your project, selecting Properties from the context menu, and changing the value in the Target Framework dropdown!
Upgrading the Umbraco package can be done in NuGet via the CLI, however, I tend to find it easier to use the UI instead. To use the UI, open your Umbraco project within Visual Studio. Right-click on your solution within solution explorer and select Properties, then Manage NuGet Packages for Solution...
From the UI that pops up, go to the tab labeled Installed. The package you need to update is called Umbraco.Cms. Select 12.0.0 or higher from the version drop-down, then click the Install button. If you use class libraries in your project, then you may also need to upgrade packages like:
Umbraco.CMS.Core
Umbraco.Cms.Infrastructure
Umbraco.CMS.Web.Common
Umbraco.Cms.Web.Website
At this point, it is also worth going to the Updates tab and making sure you upgrade any of your .NET core packages from v6 to v7.
After upgrading and building this site, I encountered a few errors in Startup.cs. Two of the DI registration methods that I was using had been moved. These missing methods were AddUmbraco() and UseUmbraco(). These types of breaking changes can happen with major upgrades and to find out what might have changed for you when upgrading, you can visit this upgrading version-specific page
In my case, I had to add two using statements to my class, Umbraco.Cms.Core.DependencyInjection and Umbraco.Extensions. After you make sure your project builds, launch your site. This should fire up your website. When your website loads you might encounter a maintenance error, but do not worry. Go to /umbraco and log in. This will force the upgrade wizard to run and your site will be updated.
After my site loaded, my page tree wasn't loading as expected. To fix this I did a hard refresh and delete cookies using Clear Cookie and Reload. After the refresh, everything worked as expected and my site was upgraded!!!!!
Happy Coding 🤘
