1 of 100

13.latest (LTS)

Umbraco CMS Documentation

Your main resource when building and managing an Umbraco CMS website.

Umbraco CMS is a flexible and editor-friendly Content Management System (CMS) that allows you to create beautiful and modern websites. Use the latest version of .NET, integrate with your favorite services, and help your customers launch a website tailored to their specific needs.

Learn more about Umbraco CMS and get an overview of the top features on Umbraco.com.

The documentation for Umbraco CMS provides information for experienced Umbraco and .NET developers. It also offers guides and high-level articles for people starting out with the CMS.

Legacy Documentation

Resources and links for older versions of Umbrco CMS.

This documentation platform covers only major versions of the Umbraco CMS since Umbraco 9. If you are using an older version of Umbraco CMS, you will need to go elsewhere.

The documentation for Umbraco 7 and 8 lives on our.umbraco.com.

Fundamentals

Get to know Umbraco

All the fundamentals of using Umbraco - from making a local installation to extending the backend.

In this part of the Umbraco CMS documentation, you can get to know the product and the default functionality. It is here you start your Umbraco journey with the installation, setup, and basics of working with the CMS.

Setup

Information on the requirements to setup, install & upgrade Umbraco

How to install and configure your Umbraco installation.

Requirements

Defines the system requirements to run Umbraco.

Installation

Umbraco installation steps and guidelines.

Upgrade your project

Covers the steps to upgrade your copy of Umbraco to a newer version.

Server setup

Information about server setup for Umbraco including information about permissions and load balancing.

Configuration

How to configure your Umbraco installation. Includes information about all of Umbraco's configuration files and options.

Installing Nightly Builds

How to install the latest nightly builds.

Requirements

Browsers

The Umbraco UI works in all modern browsers:

Chrome (Latest)
Edge (Chromium)
Firefox (Latest)
Safari (Latest)

Local Development

Below you can find the minimum requirements to run Umbraco 13 on your machine:

.NET 8.0 and higher
One of the .NET 8 - Supported OS versions
One of the following .NET Tools or Editors:
- Visual Studio Code with the IISExpress extension
- Microsoft Visual Studio 2022 version 17.8 or higher.
  - Optional: JetBrains Rider version 2022.3 and higher
- .NET Core CLI
SQL connection string (SQL Server)

When using Visual Studio as your primary Integrated Development Environment (IDE) we recommend finding and downloading the Software Development Kits (SDKs) for Visual Studio.

Hosting

Recommendation requirements to run Umbraco

As Umbraco releases are aligned to the .NET release cadence, it's also aligned with Microsoft's Long-term support policy for the underlying framework. For the best experience, we would recommend that you ensure to be on the latest and supported Microsoft versions to run and host Umbraco CMS:

For the above, as Umbraco version 13 is based on .NET 8 you will need to follow the .NET 8 supported versions.

For more information, see the Host and deploy ASP.NET Core applications article in the Microsoft documentation.

You can use Umbraco Cloud to manage the hosting infrastructure. All Umbraco Cloud plans are hosted on Microsoft Azure, which gives your site a proven and solid foundation.

Other recommendation

Ability to set file permissions to include create/read/write (or better) for the user that "owns" the Application Pool for your site. This would typically be NETWORK SERVICE.

Database Account Roles

The database account used in the connection string will need permission to read and write from tables. It will also require permission to create schema during installs and upgrades:

The db_owner role has full permissions on the database.
To use an account with more restricted permissions, the db_datareader and db_datawriter roles will be needed for normal use to read from and write to the database. The db_ddladmin role, which can modify the database schema, is required for installs and upgrades of the CMS and/or any packages that create database tables.

For more information on the Database-level roles, see the Microsoft documentation.

For more information on how to create a database user via SQL, you can check the Microsoft documentation.

Installation

Instructions on installing Umbraco on various platforms using various tools.

Install Umbraco using CLI

The fastest way to get the latest version of Umbraco up and running is using the command line (CLI).

Open your command line.
Install the Umbraco templates:

dotnet new install Umbraco.Templates::13.*

Create a new project:

dotnet new umbraco --name MyProject

Navigate to the newly created project folder. It will be the folder containing the .csproj file:

cd MyProject

Build and run the newly created Umbraco site:

dotnet run

The console will output a message similar to: [10:57:39 INF] Now listening on: https://localhost:44388
Open your browser and navigate to that URL.
Follow the instructions to finish up the installation of Umbraco.

Members of the Umbraco Community have created a website that makes the installation of Umbraco a lot easier for you. You can find the website at https://psw.codeshare.co.uk. On the website, you can configure your options to generate the required script to run. Click on the Install Script tab to get the commands you need to paste into the terminal. This tab also includes the commands for adding a starter kit or unattended install which creates the database for you.

Alternative Methods for Installing Umbraco

There are numerous ways to install Umbraco. Below, you can find links to different installation methods that will help you easily install and set up Umbraco projects.

.NET CLI installation

.NET CLI, included with the .NET Software Development Kit (SDK), can be used to install or uninstall .NET templates from NuGet. This can be done by using the dotnet new command on any OS. The underlying Template Engine enables the creation of custom templates which make new project bootstrapping much faster. With a few steps you can have an Umbraco project running without the need for a code editor.

Visual Studio installation

Visual Studio is used to write native code and managed code supported by .NET and many others. Its built-in tools provide the ability to develop and execute applications for any platform. Developers will be able to install Umbraco without ever having to leave Visual Studio.

Run Umbraco on IIS

Learn how to run an already installed local installation of Umbraco.

VS Code installation

Visual Studio Code is an editor with an embedded webserver (through the IIS Express extension). A fast way to get you up and running with Umbraco.

Installing Nightly Builds

From Umbraco v9 and above you can use the Nightly Builds to get the latest version to use and test before it is released. Learn how to install the Nightly builds to get started.

Running Umbraco on Linux/macOS

Since Umbraco 9 it has been possible to run Umbraco CMS natively on Linux or macOS High Sierra. To get Umbraco running you will need to follow some steps.

Install Umbraco unattended

Use the Unattended installs when spinning up Umbraco instances on something like Azure Web Apps to avoid having to run through the installation wizard.

Install using .NET CLI

We have made custom Umbraco templates that are available for use with dotnet new. The steps below will demonstrate the minimum amount of actions required to get you going and set up an Umbraco project from the command line using .NET templates.

Video Tutorial

Install the template

Install the latest .NET SDK.
Run dotnet new install Umbraco.Templates to install the project templates. The solution is packaged up into the NuGet package Umbraco.Templates and can be installed into the dotnet CLI.

Once that is complete, you can see that Umbraco was added to the list of available projects types by running dotnet new --list:

Templates                    Short Name               Language          Tags
------------------------------------------------------------------------------------------------------
Umbraco Project              umbraco                  [C#]              Web/CMS/Umbraco
Umbraco Package              umbracopackage           [C#]              Web/CMS/Umbraco/Package/Plugin

In some cases the templates may silently fail to install (usually this is an issue with NuGet sources). If this occurs you can try specifying the NuGet source in the command by running dotnet new install Umbraco.Templates --nuget-source "https://api.nuget.org/v3/index.json".

To get help on a project template with dotnet new run the following command:

dotnet new umbraco -h

From that command's output, you will get a better understanding of what are the default template options, as well as those command-line flags specific to Umbraco that you can use (as seen below):

Umbraco Project (C#)
Author: Umbraco HQ
Description: An empty Umbraco project ready to get started.
Options:
  -v|--version                       The version of Umbraco.Cms to add as PackageReference.
                                     string - Optional
                                     Default: 10.0.0

  --use-https-redirect               Adds code to Program.cs to redirect HTTP to HTTPS and enables the UseHttps setting.
                                     bool - Optional
                                     Default: false

  --no-restore                       If specified, skips the automatic restore of the project on create.
                                     bool - Optional
                                     Default: false

  --exclude-gitignore                Whether to exclude .gitignore from the generated template.
                                     bool - Optional
                                     Default: false

  --minimal-gitignore                Whether to only include minimal (Umbraco specific) rules in the .gitignore.
                                     bool - Optional
                                     Default: false

  --connection-string                Database connection string used by Umbraco.
                                     string - Optional

  --connection-string-provider-name  Database connection string provider name used by Umbraco.
                                     string - Optional
                                     Default: Microsoft.Data.SqlClient

  --development-database-type        Database type used by Umbraco for development.
                                         None       - Do not configure a database for development.
                                         SQLite     - Use embedded SQLite database.
                                         LocalDB    - Use embedded LocalDB database (requires SQL Server Express with Advanced Services).
                                     Default: None

  --friendly-name                    Used to specify the name of the default admin user when using unattended install on development (stored as plain text).
                                     string - Optional

  --email                            Used to specify the email of the default admin user when using unattended install on development (stored as plain text).
                                     string - Optional

  --password                         Used to specify the password of the default admin user when using unattended install on development (stored as plain text).
                                     string - Optional

  --no-nodes-view-path               Path to a custom view presented with the Umbraco installation contains no published content.
                                     string - Optional

  -p|--PackageTestSiteName           The name of the package project this should be a test site for.
                                     string - Optional

Create an Umbraco project

Create a new empty Umbraco solution: dotnet new umbraco -n MyCustomUmbracoProject

You will now have a new project with the name MyCustomUmbracoProject, or the name you chose to use. The new project can be opened and run using your favorite IDE or you can continue using the CLI commands.

If you want to create a solution file as well you can run the commands below. dotnet new sln dotnet sln add MyCustomUmbracoProject

Run Umbraco

Navigate to the newly created project folder: cd MyCustomUmbracoProject
Build and run the new Umbraco .Net Core project: dotnet build dotnet run

The project is now running on the Kestrel server and has assigned a free available port to run it on. Look in the terminal window after the dotnet run command to see the URLs.

The next step is to run through the Umbraco CMS installation. If you chose to use MS SQL Server/Azure you will need to add your connection string during this setup process to get access to the Umbraco backoffice.

Install using Visual Studio

A guide to install Umbraco CMS using Visual Studio.

Prerequisites

Install the newest .
- In Visual Studio 2022, the .NET CLI templates are enabled to appear, by default. For information on how to enable .NET CLI templates in Visual Studio 2019, see the article.
Check the to ensure you have everything you need to start your Umbraco project.

Quick Start

This is an abbreviated version of the installation steps. Jump to the section for a more thorough guide.

Open Visual Studio.
Go to File > New > Project, search for Umbraco.
Choose Umbraco Project (Umbraco HQ) then click Next.
Choose or specify the parameters, leave the default or leave them all empty.
Click Create.
Use CTRL+F5 to run the project and start the Umbraco installer.

Video Tutorial

Create a new Umbraco project

To install Umbraco we first need to install Umbraco's dotnet new templates.

Create the Visual Studio project

Go to File > New > Project and search for Umbraco in the Search for templates field.

Once you select Umbraco Project (Umbraco HQ) navigate to the next step by clicking Next.

Configure project

In this step, you will be able to give your project a name specific to the project you are creating.

Refrain from changing the Solution name, as this will cause a namespace conflict with the CMS itself.

Additional information

In the next step, you are able to specify some additional parameters like the Target framework. The rest are optional.

You can then click the Create button and your Umbraco Project will be ready for you.

Running the site

You can now run the site through Visual Studio using F5 or the Debug button.

Follow the installation wizard and after a few steps, you will get a message saying the installation was a success.

Next steps

You are now ready to start building your Umbraco project. Have a look below for different resources on the next steps.

Local IIS With Umbraco

This article describes how to run an Umbraco 9 site on a local IIS server.

This is a quick guide on getting your Umbraco website running locally on IIS.

The guide will assume you already have IIS configured and know your way around it, as well as having a local website you wish to host.

Setting up prerequisites

First, you need to ensure you have "Development time IIS support installed". To check this, go to the Visual Studio installer, click modify and check on the right side under "ASP.NET and web development":

Once that is installed you should set up a new IIS site - and make sure to add the hostname to your hosts file as well. Here is my setup for an example:

For the path you want to point it at the root of your site - where the .csproj file is.

Add permissions to NuGet cache folder

You might need to change permissions for the NuGet cache folder - C:\users\<username>\.nuget\packages. The user or group (IIS_IUSRS) that the IIS site is running on requires Read permissions on this folder because this is where some of the files for Umbraco and Umbraco packages are being served from during development. If the IIS user or group does not have permission to read from the NuGet cache folder, you could run into a DirectoryNotFoundException while running the site.

Add new launch profile

At this point you can go to your Visual Studio solution of the site and in the Properties folder there is a launchSettings.json file, that looks like this:

You can add a new profile called IIS, and point it at your local domain. Here it is with my example domain:

At this point IIS will be added to the launch profiles, and you can run the site from Visual Studio by choosing IIS in the dropdown:

And finally the site is running from your local IIS:

Install using Visual Studio Code

Follow these steps to set up an Umbraco project with VS Code. The benefit of using VS Code is that it is super quick to get up and running.

Installing and setting up VS Code

Go to and download VS Code for free.
Once installed, launch VS Code.
Click the extensions menu at the bottom on the left side. Then search for C# and install it.

Creating your Umbraco project

Configure VS Code to run the Umbraco project

Open your project folder in VS Code, your project will look something like this:

Now we need to tell VS Code how to run your project.

Open the command palette, you can use the shortcut Ctrl+Shift+P, and type in Tasks: Configure and select the Tasks: Configure Task option:

Select "Create task.json from template"

Now select ".NET Core" as your template.

After this VS Code will have created a folder called .vscode that contains a file called tasks.json, it's this file that tells VS Code how to build your project.

Now that we've told VS Code how to build your project, we need to tell it how to launch it. VS Code can do this for you. First, select the little play button in the left side menu, and then select the "create a launch.json file" link.

This will prompt a menu to appear, select .NET 5+ and .NET Core:

If .NET 5+ and .NET Core is missing in the drop-down menu:

Press Ctrl + Shift + P (on Windows/Linux) or Cmd + Shift + P (on macOS) to open the Command Palette.
Search for the command .NET: Generate Assets for Build and Debug. This command will generate the necessary assets for building and debugging your .NET application.

Now you'll see a green play button appear with a dropdown where ".NET Core Launch (web)" is selected.

If you navigate to the Files section, a new launch.json file is created in the .vscode folder. When you press F5, the launch.json file tells VS Code to build your project, run it, and then open a browser .

With that, you're ready to run the project! Press F5, or click the little green play button in the Run and Debug section to run your brand new Umbraco site locally.

Umbraco Web Installer

This section continues from where we left off but covers the installation and configuration of Umbraco inside your web browser when you run Umbraco for the first time.

You will see the install screen where you will need to fill in some data before Umbraco can be installed.

When the installer is done, you will be logged into the backoffice.

Congratulations, you have installed an Umbraco site!

You can log into your Umbraco site by entering the following into your browser: http://yoursite.com/umbraco/.

Installing Nightly Builds

Instructions on installing nightly builds of Umbraco.

In this article, we'll explain how you can get the latest builds of Umbraco. You can do this in three steps:

Adding the nightly feed as a NuGet source

The NuGet feed containing the nightly builds is https://www.myget.org/F/umbraconightly/api/v3/index.json.

You can either add this feed through the command line or use an IDE of your choice. In this article, we'll provide steps for:

Option 1: Using the command line

To add the nightly feed using the command line:

Open a command prompt of your choice.
Run the following command:

Now the feed is added as a source named Umbraco Nightly.

Option 2: Using Visual Studio

To add the nightly feed using Visual Studio:

Open Visual Studio.
Go to Tools > NuGet Package Manager > Package Manager Settings.

The Options window open.
Select the Package Sources option in the NuGet Package Manager section.
Click the + icon.
A new Package source will be added automatically and highlighted.
Enter the desired name for the feed in the Name field.
Enter the link https://www.myget.org/F/umbraconightly/api/v3/index.json into the Source field.
Click OK.

Now the feed is added as a source named Umbraco Nightly.

Option 3: Using Rider

To add the nightly feed using Rider:

Open Rider.
Go to View > Tool Windows > NuGet.
Go to Sources tab.
Choose the C:\Users\Úmbraco\AppData\Roaming\NuGet\NuGet.Config to add the feed globally.
Cick the green + button in the New Feed field.

The New feed dialog opens.
Enter the desired name in the Name field.
Enter https://www.myget.org/F/umbraconightly/api/v3/index.json in the URL field.

Leave the User, Password fields empty, and the Enabled checkbox ticked.

Click OK.

Now the feed is added as a source named Umbraco Nightly.

Finding the latest nightly version

In the previous steps, we've added the feed and are now ready to install the nightly build.

However, which version should we install? This is, in particular, an issue if we want to create a new site using the dotnet template. The dotnet command does not allow us to use wildcard characters to install the newest version.

Using IDE, we can see a list of available versions in both Visual Studio and Rider. We can then use that version to install the template.

Here we're going to assume that you want to create a brand new site with the dotnet template. The approach is the same if you're updating an existing site. You'll click the Update button for the Umbraco.Cms package instead of installing the template through the terminal.

Let's look at how we can find the latest version of the nightly build:

Option 1: Using Visual Studio

You can use the package manager in Visual Studio to browse the available template versions.

Open Visual Studio.
Go to Tools > NuGet Package Manager > Manage NuGet Packages For Solution...

Select Umbraco Nightly from the Package source dropdown in the NuGet - Solution window.

Check the Include prerelease checkbox.
Search for Umbraco.Templates in the Browse field.
Choose that package.
Click on the Version dropdown and see the available nightly builds.
Choose the applicable version and note down the version number.

Option 2: Using Rider

You can use the NuGet window in Rider to browse the available template versions.

Open Rider.
Go to the Packages tab in the NuGet window..
Select Umbraco Nightly from the All Feeds dropdown.

Check the Prerelase checkbox.
Search for Umbraco.Templates in the Search field.
Choose that package.
Click on the Version drop down and see the available nightly builds.
Choose the applicable version and note down the version number

Installing the latest nightly version template

Now that our feed is added and we know the exact version we're ready to install our template.

To install the latest nightly version template:

Open your command prompt.
Run the following command using the latest version:

With that, we've successfully installed the latest nightly build of Umbraco.

All we have to do now is to create a site using the dotnet new umbraco -n MyAwesomeNightlySite command.

Running Umbraco on Linux/macOS

Since Umbraco 9 it has been possible to run Umbraco CMS natively on Linux or macOS High Sierra 10.13 and newer.

With Umbraco CMS on .NET Core, Linux and macOS is natively supported with SQLite as the database.

In the below section, we describe how to get started with running Umbraco CMS on Linux or macOS.

How to get started running Umbraco CMS on Linux or macOS

To get started with Umbraco CMS first have a look at the .

Once you've made sure you meet the requirements it is time to install the Umbraco Templates on your system.

To do this follow the guide.

With the templates installed on your system, it is now possible to create Umbraco projects.

To create a project, there are two options:

Continue creating projects using the .NET CLI.
Create new projects using Visual Studio (only macOS).

To create new projects using Visual Studio, you can use the guide.

Once you create a new project it will use SQLite by default on Linux/macOS.

If you want to use an SQL server database, you will need to .

Unattended Installs

In some cases, you might need to install Umbraco instances automatically without having to run through the installation wizard to configure the instance.

You can use the Unattended installs feature to allow for quick installation and set up of Umbraco instances on something like Azure Web Apps.

This article will give you the details you need to install Umbraco unattended.

Get clean install of Umbraco

In order to get a clean instance of Umbraco, follow our installation guide for how to .

Configure your database

As you will not be running through the installation wizard when using this feature, you need to manually tell Umbraco which database to use.

Set up and configure a new database - see for details.
Add the connection string using configuration.

Umbraco can create an SQL Server database for you during the unattended install process. The user specified by the credentials in your connection string needs to have the CREATE DATABASE permission granted and the global setting is set to true.

If your connection string is for SQLite or SQL Server Express LocalDB it is assumed that a database should be created when missing. This is regardless of the value of the InstallMissingDatabase setting.

SQL Server Example in appsettings.json

SQLite Example in appsettings.json

A value is configured for the keyumbracoDbDSN_ProviderName to ensure usage of the Microsoft.Data.SQLite ADO.NET provider.

It is recommended that you make use of the values shown below for the Cache, Foreign Keys and Pooling keywords on your connection string.

Enable the unattended installs feature

The unattended installs feature is disabled by default. In order to enable it, you need to add the following JSON object to a JSON configuration source.

Remember to set the value of InstallUnattended to true.

The keys for this would then be as follows:

Initialize the unattended install

After completing the steps above you can now initialize the installation by booting up the Umbraco instance.

Once it has completed, you should see the following when visiting the frontend of the site.

Configuration options

Depending on your preferences, you can use any type of configuration to specify the connection string and login information, as well as enable unattended install. With the extending configuration functionality, it is possible to read from all kinds of sources. One example can be using a JSON file or environment variables.

Program.cs has a condition, which if met, an appsettings.Local.json file will be added and configured as a configuration source.

Having intellisense will help you to add your connection string and information needed for the unattended install.

More support

We have added support for unattended installs with Name, Email and Password, and Connection String as CLI params, which are also available in Visual Studio. There you can fill in your information as follows:

CLI

Visual Studio

Upgrade your project

This is the guide for upgrading existing installations in general.

In this article, you will find everything you need to upgrade your Umbraco CMS project.

You will find instructions on how to upgrade to a new minor or major version as well as how to run upgrades unattended.

Before you upgrade

The following lists a few things to be aware of before initiating an upgrade of your Umbraco CMS project.

Sometimes there are exceptions to general upgrade guidelines. These are listed in the . Be sure to read this article before moving on.
Check if your setup meets the for the new versions you will be upgrading your project to.
Things may go wrong for different reasons. Be sure to ALWAYS keep a backup of both your site's files and the database. This way you can always return to a version that you know works.
Before upgrading to a new major version, check if the packages you're using are compatible with the version you're upgrading to. On the package's download page, in the Project compatibility area, click View details to check version-specific compatibility.

It is necessary to run the upgrade installer on each environment of your Umbraco site. This means that you need to repeat the steps below on each of your environments in order to complete the upgrade.

Legacy Umbraco

The steps outlined in this article apply to modern Umbraco from version 10 and later versions.

Are you upgrading to a minor for Umbraco 6, 7, or 8 you can find the appropriate guide below:

Upgrade to a new Major

You can upgrade to a new major of Umbraco CMS directly by using NuGet.

Switching to a new major of Umbraco CMS also means switching to a new .NET version. You need to make sure that any packages used on your site are compatible with this version before upgrading.

The package compatibility can be checked on the package's download page. Locate the Project compatibility area and select View details to check version-specific compatibility.

Choose the correct .NET version

Use the table below to determine which .NET version to upgrade to when going through the steps below.

Upgrade your project using Visual Studio

It's recommended that you upgrade the site offline and test the upgrade fully before deploying it to the production environment.

Stop your site in IIS to prevent any changes from being made while you are upgrading.
Open your Umbraco project in Visual Studio.
Right-click on the project name in the Solution Explorer and select Properties.
Select the .NET version from the Target Framework drop-down.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
Go to the Installed tab in the NuGet Package manager.
Upgrade Umbraco.Cms.
a. Select the correct version from the Version drop-down.
b. Click Install to upgrade your project.

Make sure that your connection string has TrustServerCertificate=True in order to complete the upgrade successfully:

Restart your site in IIS, then build and run your project to finish the installation.

If you have added custom code to the startup.cs file, we recommend moving the code into a Composer after upgrading.

Upgrade to a new Minor

NuGet installs the latest version of the package when you use the dotnet add package command unless you specify a package version:

dotnet add package Umbraco.Cms --version <VERSION>

Add a package reference to your project by executing the dotnet add package Umbraco.Cms command in the directory that contains your project file.

Run dotnet restore to install the package.

For v9: If you are using SQL CE in your project you will need to run dotnet add package Umbraco.Cms.SqlCe --version <VERSION> before running the dotnet restore command. From v10, SQL CE has been replaced with SQLite so a dotnet restore should be sufficient. If this is not working then you will need to run dotnet add package Umbraco.Cms.Persistence.Sqlite --version <VERSION> and then dotnet restore.

When the command completes, open the .csproj file to make sure the package reference was updated:

Run an unattended upgrade

When upgrading your Umbraco project, it is possible to enable the upgrade to run unattended. This means that you will not need to run through the installation wizard when upgrading.

Below you will find the steps you need to take in order to upgrade your project unattended.

Are you running a load balanced setup with multiple servers and environments?

Enable the unattended upgrade feature

Add the Umbraco:Cms:Unattended:UpgradeUnattended configuration key.
Set the value of the key to true.

Run the upgrade

With the correct configuration applied, the project will be upgraded on the next boot.

Boot order

The Runtime level will use Run instead of Upgrade to allow the website to continue to boot up directly after the migration is run. This happens instead of initiating the otherwise required restart.

The upgrade is run after Composers but before Components and the UmbracoApplicationStartingNotification. This is because the migration requires services that are registered in Composers and Components require that Umbraco and the database are ready.

Unattended upgrades in a load balanced setup

Follow the steps outlined below to use unattended upgrades in a load balanced setup.

Deploy to all environments.
Set the Umbraco:CMS:Unattended:UpgradeUnattended configuration key to true for the Main server only.
Boot the Main server and the upgrade will run automatically.
Wait for the upgrade to complete.
Boot the Read-Only servers and make sure they do not show the “upgrade required” screen.

Upgrade from Umbraco 8 to the latest version

Learn how to upgrade your Umbraco 8 project to Umbraco 10.

It is currently not possible to upgrade directly from Umbraco 8 to the latest version.

The recommended approach for upgrading from version 8 to the latest version is to use this guide to upgrade from Umbraco 8 to Umbraco 10. Umbraco 10 contains the database migrations that must be upgraded from Umbraco 8. You can then use the Upgrading to Major steps to upgrade from Umbraco 10 to the latest version.

Since the underlying framework going from Umbraco 8 to the latest version has changed, there is no direct upgrade path. That said, it is possible to re-use the database from your Umbraco 8 project on your new project in order to maintain the content.

It is not possible to migrate the custom code as the underlying web framework has been updated from ASP.NET to ASP.NET Core. All templates and custom code will need to be reimplemented.

You also need to make sure that the packages you are using are available on the latest version.

Prerequisites

A Umbraco 8 project running the latest version of Umbraco 8.
A backup of your Umbraco 8 project database.
A clean installation of the latest version of Umbraco.

If you use Umbraco Forms, then on the clean installation of Umbraco, you will need to install Umbraco.Forms package as well.

Video Tutorial

The video below shows how to complete the upgrade on an Umbraco Cloud project. Most of the process is the same, however, the video does contain some Cloud-specific elements.

Step 1: Content Migration

If you use Umbraco Forms, make sure to have StoreUmbracoFormsInDbsetto True before step 1.

Create a backup of the database from your Umbraco 8 project (after you have upgraded to the latest version of v8). For this, you can use the database backup guide.
Import the database backup into SQL Server Management Studio.
Update the connection string in the new projects appsettings.json file so that it connects to the Umbraco 8 database:

"ConnectionStrings": {
    "umbracoDbDSN": "Server=YourLocalSQLServerHere;Database=NameOfYourDatabaseHere;User Id=NameOfYourUserHere;Password=YourPasswordHere;TrustServerCertificate=True"
}

You can also add the connection details if you spin up a clean installation.

Run the new project and login to authorize the upgrade.
Select "Upgrade" when the upgrade wizard appears.
Once the upgrade has been completed, it's recommended to login to the backoffice to verify if your project is upgraded to new version.

This is only content migration and the database will be migrated.

You need to manually update the view files and custom code implementation. For more information, see Step 3 of this guide.

Step 2: File Migration

The following files/folders need to be copied from the Umbraco 8 project into the new project:
- ~/Views - Do not overwrite the default Macro and Partial View Macro files unless changes have been made to these.
- ~/Media - Media folder from v8 needs to be copied over into the wwwroot - media folder
- Any files/folders related to Stylesheets and JavaScript.
Migrate custom configuration from the Umbraco 8 configuration files (.config) into the appsettings.json file on the new project.
- As of Umbraco version 9, the configuration no longer lives in the Web.Config file and has been replaced by the appsettings.json file. Learn more about this in the Configuration article.
Migrate Umbraco Forms data to the database, if relevant.
- As of Umbraco Forms version 9, it is only possible to store Forms data in the database. If Umbraco Forms was used on the Umbraco 8 project, the files need to be migrated to the database.
Run the new project.
- It will give you an error screen on the frontend as none of the Template files have been updated. Follow Step 3 to resolve the errors.

Step 3: Custom Code in the latest version

The latest version of Umbraco is different from Umbraco 8 in many ways. With all the files and data migrated it is now time to rewrite and re-implement all custom code and templates.

Examples of changes

One of the changes is how published content is rendered through Template files. Due to this, it will be necessary to update all the Template files (.cshtml) to reflect these changes.

Read more about these changes in the IPublishedContent section of the Umbraco CMS documentation.

Template files need to inherit from Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ContentModels.HomePage> instead of Umbraco.Web.Mvc.UmbracoViewPage<ContentModels.HomePage>
Template files need to use ContentModels = Umbraco.Cms.Web.Common.PublishedModels instead of ContentModels = Umbraco.Web.PublishedModels

For more information on the correct namespaces or custom code, you can find the references in the API Documentation article.

Depending on the extent of the project and the amount of custom code and implementations, this step is going to require a lot of work.

Once the new project runs without errors on a local setup it is time to deploy the website to production.

This concludes this tutorial. Find related information and further reading in the section below.

Minor upgrades for Umbraco 8

This article provides details on how to upgrade to the next minor version when using Umbraco 8.

Sometimes there are exceptions to these guidelines, which are listed in the version-specific guide.

Note

It is necessary to run the upgrade installer on each environment of your Umbraco site. If you want to update your staging and live site you need to repeat the steps below. Make sure you click through the install screens so that your upgrade is complete.

In this article you will find instructions for 3 different ways of upgrading:

Upgrade using NuGet
Upgrade manually from a Zip file
Run an unattended upgrade (v8.12+)

Upgrade using NuGet

Open up the Package Console and type: Update-Package UmbracoCms
Choose "No to All" by pressing the "L" when prompted.
- If there are any specific configuration changes required for the version you are upgrading to then they will be noted in the version-specific guide.

Alternatively, you can use the Visual Studio NuGet Package Manager to upgrade:

Open the NuGet Package Manager and select the Updates pane to get a list of available updates.
Choose the package called UmbracoCms and select update.

The upgrade will run through all the files and make sure you have the latest changes while leaving files you have updated.

Upgrade manually from a zip file

Download the .zip file for the new version you are upgrading to from https://our.umbraco.com/download

Copy the following folders from inside the .zip file over the existing folders in your site:

/bin
/Umbraco

There are hosting providers (we know of one: RackSpace Cloud) that require proper casing of file and folder names. Normally on Windows this is not a problem. If your hosting provider however forces proper casing, you will need to verify that the folder and file names are in the same casing as in the newest version you're upgrading to.

Merge configuration files

You can expect some changes to the following configuration files:

Any file in the /Config folder
The /Global.asax file
The web.config file in the root of your site (Important: make sure to copy back the version number, and the connection string as they were.)
In rare cases, the web.config file in the /Views folder

Use a tool like WinMerge to check changes between all of the config files. Depending on when you last did this there may have been updates to few of them.

There's also the possibility that some files in the /Config folder are new or some have been removed (we do make a note of this in the release notes). WinMerge (and other diff tools) can compare folders as well so you can spot these differences.

Merge UI.xml and language files

Some packages like Umbraco Forms add dialogs to the UI.xml. Make sure to merge those changes back in from your backup during the upgrade so that the packages continue to work. This file can be found in: /Umbraco/Config/Create/UI.xml.

Packages like Umbraco Forms and Courier also make changes to the language files located in: /Umbraco/Config/Lang/*.xml (typically en.xml).

Finalize

After copying the files and making the config changes, you can open your site. You should see the installer which will guide you through the upgrade.

The installer will do two things:

Update the version number in the web.config
Upgrade your database in case there are any changes

We are aware that, currently, the installer is asking you for the database details of a blank database while upgrading. In the near future this will be pre-filled with your existing details and the wording will be updated. So no need to be scared. Enter the details of your existing database and Umbraco will upgrade it to the latest version when necessary.

Run an unattended upgrade

When upgrading your Umbraco project to Umbraco v8.12+ it is possible to enable the upgrade to run unattended. This means that you will not need to run through the installation wizard when upgrading.

Below you will find the steps you need to take in order to upgrade your project unattended.

Are you running a load balanced setup with multiple servers and environments?

Check out the section about Unattended upgrades in a load balanced setup.

Enable the feature

Add the Umbraco.Core.RuntimeState.UpgradeUnattended key to appSettings in your web.config file.
Set the value of the key to true.

    <add key="Umbraco.Core.RuntimeState.UpgradeUnattended" value="true" />

Check the `ConfigurationStatus`

In order to trigger the actual upgrade, the correct version number needs to be set.

It is important to use the version number of the version that you are upgrading to. If this is not set, the upgrade will not run even if the UpgradeUnattended key has been set to true.

Locate the ConfigurationStatus key in the appSettings section in your web.config file.
Update the value to match the Umbraco version that you are upgrading to.

<add key="Umbraco.Core.ConfigurationStatus" value="x.x.x"/>

Run the upgrade

With the correct configuration applied, the project will be upgraded on the next boot.

While the upgrade processes are running, any requests made to the site will be "put on hold", meaning that no content will be returned before the upgrade is complete.

Boot order

The Runtime level will use Run instead of Upgrade in order to allow the website to continue to boot up directly after the migration is run, instead of initiating the otherwise required restart.

The upgrade is run after Composers but before Components. This is because the migration requires services that are registered in Composers and Components requires that Umbraco and the database is ready.

Unattended upgrades in a load balanced setup

Follow the steps outlined below to use run unattended upgrades in a load balanced setup.

Upgrade Umbraco via NuGet in Visual Studio. Make sure the Umbraco.Core.ConfigurationStatus key in appSetting in the web.config file is updated to match the target version.
Deploy to all environments, including the updated appSetting for Umbraco.Core.ConfigurationStatus.
Set the Umbraco.Core.RuntimeState.UpgradeUnattended key in appSetting in the web.config to true for the Main server only.
Request a page on the Main server and the upgrade will run automatically.
Wait for the upgrade to complete.
Browse the Read-Only servers and make sure they do not show the “upgrade required” screen.

Post installation

One important recommendation is to always remove the install folder immediately after upgrading Umbraco and never to upload it to a live server.

Potential issues and gotchas

Browser cache

Google Chrome has notoriously aggressive caching, so if something doesn't seem to work well in the backoffice, make sure to clear cache and cookies thoroughly (for other browsers as well). Normally the browser cache problem is automatically handled in an Umbraco upgrade by modifying the config/ClientDependency.config version number. If you however wish to re-force this update you can increment this version number which will ensure that any server-side cache of JavaScript and stylesheets gets cleared as well.

One way to nudge the cache in Chrome is to open the developer tools (F12) and go to the settings (the cog icon). There will be a checkbox that says "Disable cache (while DevTools is open)". Once this checkbox is on you can refresh the page and the cache should be invalidated. To force it even more, the "reload" button next to your address bar now has extra options when you right-click it. It should have "Normal reload", "Hard reload" and "Empty cache and hard reload" now. The last option is the most thorough and you might want to try that.

Upgrade to Umbraco 7

This document should be used as a reference, not a step by step guide. Upgrading will largely depend on what version of Umbraco you are currently running, what packages you have installed and the many

The still apply to this process as well.

Backup

It is critical that you back up your website and database before upgrading. There are database changes made during installation and you cannot revert an Umbraco 7 database to an Umbraco 6 database.

.Net 4.5

Umbraco 7 is built on .Net 4.5 and your development environment will require this version installed in order to operate. Visual Studio users may require 2012 or higher.

HTML 5 browser support

Umbraco 7 requires browsers with proper HTML 5 support, these include Chrome, Firefox, IE10+

Breaking changes

Before you upgrade be sure to read the list of breaking changes. This is especially recommended if you have removed or modified code in the core or if one of these breaking changes directly affects your installation.

for more details.

Examine

It is recommended to rebuild all Examine indexes after completing the upgrade.

Xml Cache rebuild

You should re-generate the XML cache. This can be done by following the prompts when visiting the following URL:

your-domain.com/umbraco/dialogs/republish.aspx?xml=true

Configuration changes

It is recommended that you use a Diff tool to compare the configuration file changes with your own current configuration files.

/web.config updates
- You will need to compare the new Umbraco 7 web.config with your current web.config. Here is a quick reference of what needs to change:
  - Remove the section name="BaseRestExtensions" section
  - Remove the section name="FileSystemProviders" section
  - Remove the sectionGroup name="system.web.webPages.razor" section
  - Remove the <FileSystemProviders> element
  - Remove the BaseRestExtensions element
  - Remove the add key="umbracoUseMediumTrust" element
  - Remove the system.web.extensions element
  - Removes the xhtmlConformance element
  - Remove the system.codedom element
  - Remove the compilation assemblies, /compilation
  - Remove the system.web.webPages.razor element
  - New: sectionGroup name="umbracoConfiguration" section
  - New: umbracoConfiguration element
  - Ensure that the targetFramework="4.5" is added to the httpRuntime element
  - Add add key="ValidationSettings:UnobtrusiveValidationMode" value="None" to the appSettings element
/config/clientdependency.config changes
- remove add name="CanvasProvider" element
/views/web.config updates
New macroscripts/web.config
config/umbracoSettings.config
- Remove the EnableCanvasEditing element
- Remove the webservices element
Removed xsltExtensions.config
/config/applications.config and /config/trees.config have some icon paths and names updated. You need to merge the new changes into your existing config files.
/config/tinyMceConfig.config
- The inlinepopups is compatible and supported in Umbraco 7. You need to remove these elements: plugin loadOnFrontend="true", inlinepopups/plugin;
- The plugins element that is shipped with Umbraco 7 looks like this:
  - You need to merge the changes from the new tinyMceConfig file into yours. The command elements that have changed are: JustifyCenter, JustifyLeft, JustifyRight, JustifyFull, umbracomacro, umbracoembed, mceImage, subscript, superscript, styleselect
  - Remove the command: mceSpellCheck
/config/dashboard.config
- You need to merge the changes from the new dashboard.config into yours. Some of the original dashboard entries that were shipped with Umbraco 6 have been replaced or removed.

Medium Trust

Umbraco 7+ will no longer support medium trust environments. There are now some assemblies used in the core that do not support medium trust but are used extensively. Plugin scanning now also allows for scanning Umbraco's internal types which requires full trust.

Events

Tree events

Content, Media, Members, and Data Type trees will no longer raise the legacy tree events (based on BaseTree). It is recommended to change all tree event handlers to use the new tree events that fire for every tree in Umbraco including legacy trees. The new tree events are static events and are found in the class Umbraco.Web.Trees.TreeControllerBase:

MenuRendering
RootNodeRendering
TreeNodesRendering

Legacy business logic events

The Content, Media, Member, and Data Type editors have been re-created and are solely using the new Umbraco Services data layer. This means that operations performed in the backoffice will no longer raise the legacy business logic events (for example, events based on umbraco.cms.businesslogic.web.Document). It is recommended to change your event handlers to subscribe to the new Services data layer events. These are static events and are found in the services. For example: Umbraco.Core.Services.ContentService.Saved.

Property Editors

Legacy property editors (pre-Umbraco 7) will not work with Umbraco 7. During the upgrade installation process, Umbraco will generate a report showing you which legacy property editors are installed. These will all be converted to a readonly Label property editor. No data loss will occur but you'll need to re-assign your existing data types to use a new compatible Umbraco 7 property editor.

Most Umbraco core property editors shipped will be mapped to their equivalent Umbraco 7 editors. The Image cropper editor has not been completed for v7.0.

Since the Related Links property is an advanced property editor, the data format has changed from XML to JSON. This should not have any effect when retrieving the data from razor. If you are outputting Related Links data with XSLT you will need to update your XSLT snippet. Making use of the new library method umbraco.library:JsonToXml and taking into account that the xml structure has also slightly changed.

GUID -> Alias mapping

One of the database changes made in Umbraco 7 is the change of referencing a property editor from a GUID to a string alias. In order to map a legacy property editor to a new Umbraco 7 version you can add your custom "GUID -> Alias" map during application startup. To do this you would add your map using this method: Umbraco.Core.PropertyEditors.LegacyPropertyEditorIdToAliasConverter.CreateMap

Parameter Editors

Legacy parameter editors (pre-Umbraco 7) will not work with Umbraco 7. If Umbraco detects legacy parameter editor aliases that do not map to a Umbraco 7 parameter editor it will render a textbox in its place. You will need to update your macros to use a compatible Umbraco 7 parameter editor as those that aren't supported.

Previously, parameter editors were registered in an Umbraco database table: cmsMacroPropertyType which no longer exists. Parameter editors in Umbraco 7 are plugins like property editors. During the Umbraco 7 upgrade installation process it will update the new cmsMacroProperty.editorAlias column with the previous parameter editor alias. During this process it will look into the Umbraco.Core.PropertyEditors.LegacyParameterEditorAliasConverter for a map between a legacy alias to a new Umbraco 7 alias.

Custom legacy parameters can be mapped to new Umbraco 7 parameter editor aliases during installation. This can be done by modifying the mapping during application startup using this method: Umbraco.Core.PropertyEditors.LegacyParameterEditorAliasConverter.CreateMap.

Database changes

All database changes will be taken care of during the upgrade installation process.

For database change details see (including all child tasks):

Packages

You should check with the package creator for all installed packages to ensure they are compatible with Umbraco 7.

For package developers

We see common errors that we cannot fix for you, but we do have recommendations you can follow to fix them:

TypeFinder

The TypeFinder has been deprecated since 4.10 and is now found under Umbraco.Core.TypeFinder.

While you need to have JavaScript inside menu actions to trigger a response, it is highly recommended that you use the recommended UmbClientMgr methods. You should not try to override parent.right.document and similar tricks to get to the right-hand frame.

Use the recommended Umbraco uicontrols

If you have a webforms page, it is recommended to use the built-in ASP.NET controls to render panels, properties and so on. If you use the raw HTML or try to style it to match the backoffice, you will get out of sync. Follow the guidelines set by Umbraco's internal editors and use the ASP.NET custom controls for UI.

Minor upgrades for Umbraco 7

This article provides details on how to upgrade to the next minor version when using Umbraco 7.

Sometimes there are exceptions to these guidelines, which are listed in the .

Note

It is necessary to run the upgrade installer on each environment of your Umbraco site. If you want to update your staging and live site then you need to repeat the steps below and make sure that you click through the install screens to complete the upgrade.

In this article you will find instructions for 2 different ways of upgrading:

Upgrade using NuGet

Open up the Package Console and type: Update-Package UmbracoCms
Choose "No to All" by pressing the "L" when prompted.
- If there are any specific configuration changes required for the version you are upgrading to then they will be noted in the .

Alternatively, you can use the Visual Studio NuGet Package Manager to upgrade:

Open the NuGet Package Manager and select the Updates pane to get a list of available updates.
Choose the package called UmbracoCms and select update.

The upgrade will run through all the files and make sure you have the latest changes while leaving the files you have updated.

Upgrades to versions lower than 7.2.0

You will be asked to overwrite your web.config file and the files in /config, make sure to answer No to those questions.

For some inexplicable reason, the installation will fail if you click "No to All" (in the GUI) or answer "L" (in the package manager console) to the question: "File 'Web.config' already exists in project 'MySite'. Do you want to overwrite it?" So make sure to only answer "No" (in the GUI) or "N" (in the package manager console).

We will overwrite the web.config file. We'll back it up so don't worry. You can find the backup in App_Data\NuGetBackup\20140320-165450\. The 20140320-165450 bit is the date and time when the backup occurred, which varies. You can then merge your config files and make sure they're up to date.

Upgrade manually from a zip file

Copy the following folders from inside the .zip file over the existing folders in your site:

/bin
/Umbraco
/Umbraco_Client

There are hosting providers (we know of one: RackSpace Cloud) that require proper casing of file and folder names. Generally, on Windows, this is not a problem. Is your hosting provider forcing proper casing? You'll then need to verify that folders and files are named in the same casing as the version you're upgrading to.

Merge configuration files

You can expect some changes to the following configuration files:

Any file in the /Config folder
The /Global.asax file
The web.config file in the root of your site (Important: make sure to copy back the version number, and the connection string as they were.)
In rare cases, the web.config file in the Views folder

There's also the possibility that files in the /Config folder are new or have been removed(we note this in the release notes). WinMerge (and other diff tools) is able to compare folders as well so you can spot these differences.

Up until version 6.0.0 it was necessary to change the version number in ClientDependency.config. This was to clear the cached HTML/CSS/JS files in the backoffice. Change the current version number to one that's higher than that. Make sure not to skip this step as you might get strange behavior in the backoffice otherwise.

Merge UI.xml and language

Some packages (like Contour and Umbraco Forms) add dialogs to the UI.xml. Make sure to merge those changes back in from your backup during the upgrade so that the packages continue to work. This file can be found in: /Umbraco/Config/Create/UI.xml.

Packages like Contour, Umbraco Forms, and Courier also make changes to the language files located in: /Umbraco/Config/Lang/*.xml (typically en.xml).

Finalize

After copying the files and making the config changes, you can open your site. You should see the installer which will guide you through the upgrade.

The installer will do two things:

Update the version number in the web.config
Upgrade your database in case there are any changes

Post installation

One important recommendation is to always remove the install folder immediately after upgrading Umbraco and never to upload it to a live server.

Potential issues and gotchas

Browser cache

Google Chrome has notoriously aggressive caching. If something doesn't seem to work well in the backoffice, make sure to clear cache and cookies thoroughly (for other browsers as well). Normally the browser cache problem is automatically handled in an Umbraco upgrade by modifying the config/ClientDependency.config version number. If you wish to re-force this update you can increment this version number. This will ensure that any server-side cache of JavaScript and stylesheets gets cleared as well.

Server setup

This section describes different ways of setting up servers for use with Umbraco

This section describes different ways of setting up servers for use with Umbraco

Secure Sockets Layer (SSL) and HTTPS

We strongly encourage the use of HTTPS with Umbraco installations especially in production environments. Using HTTPS will greatly enhance the security of your website, see the for more information.

To ensure a stable and smoothly running Umbraco installation, these permissions need to be set correctly.

Information about hosting a v9 application using IIS.

Information on how to deploy Umbraco in a Load Balanced scenario and other details to consider when setting up Umbraco for load balancing.

Best practices for running Umbraco on Azure Web Apps.

The runtime mode setting optimizes Umbraco for the best development experience or optimal production environment.

Umbraco in Load Balanced Environments

Information on how to deploy Umbraco in a Load Balanced scenario and other details to consider when setting up Umbraco for load balancing

Information on how to deploy Umbraco in a Load Balanced scenario and other details to consider when setting up Umbraco for load balancing.

Overview

Configuring and setting up a load balanced server environment requires planning, design and testing. This document should assist you in setting up your servers, load balanced environment and Umbraco configuration.

This document assumes that you have a fair amount of knowledge about:

Umbraco
IIS 10+
Networking & DNS
Windows Server
.NET5+

It is highly recommended that you setup your staging environment to also be load balanced so that you can run all of your testing on a similar environment to your live environment.

Design

These instructions make the following assumptions:

All web servers can communicate with the database where Umbraco data is stored
You are running Umbraco 9.0.0 or above
You will designate a single server to be the backoffice server for which your editors will log into for editing content. Umbraco will not work correctly if the backoffice is behind the load balancer.

There are three design alternatives you can use to effectively load balance servers:

Each server hosts copies of the load balanced website files and a file replication service is running to ensure that all files on all servers are up to date
The load balanced website files are located on a centralized file share (SAN/NAS/Clustered File Server/Network Share)

You will need a load balancer to do your load balancing.

How Umbraco load balancing works

In order to understand how to host your site it is best to understand how Umbraco's flexible load balancing works.

The following diagram shows the data flow/communication between each item in the environment:

The process is as follows:

Administrators and editors create, update, delete data/content on the backoffice server
These events are converted into data structures called "instructions" and are stored in the database in a queue
Each front-end server checks to see if there are any outstanding instructions it hasn't processed yet
When a front-end server detects that there are pending instructions, it downloads them and processes them and in turn updates it's cache, cache files and indexes on its own file system
There can be a delay between content updates and a front-end server's refreshing, this is expected and normal behaviour.

Scheduling and server role election

Although there is a backoffice server designated for administration, by default this is not explicitly set as the "Scheduling server". In Umbraco there can only be a single scheduling server which performs the following 3 things:

Keep alive service - to ensure scheduled publishing occurs
Scheduled tasks - to initiate any configured scheduled tasks
Scheduled publishing - to initiate any scheduled publishing for documents

Automatic Server Role Election

Umbraco will automatically elect a "Scheduling server" to perform the above services. This means that all of the servers will need to be able to resolve the URL of either: itself, the Backoffice server, the internal load balancer, or the public address.

There are two server roles:

SchedulingPublisher - Usually this is the backoffice instance.
Subscriber - These are the scalable front-end instances - not recommended to be used for backoffice access.

These new terms replace 'Master and Replica', in Umbraco versions 7 and 8.

Each instance will be allocated a role by the automatic server role election process, but they can also be set explicitly (recommended)

For example, In the following diagram the node f02.mysite.local is the elected "Scheduling server". In order for scheduling to work it needs to be able to send requests to itself, the Backoffice server, the internal load balancer or the public address. The address used by the "Scheduling server" is called the "umbracoApplicationUrl".

By default, Umbraco will set the "umbracoApplicationUrl" to the address made by the first accepted request when the AppDomain starts. It is assumed that this address will be a DNS address that the server can resolve.

For example, if a public request reached the load balancer on www.mysite.com, the load balancer may send the request on to the servers with the original address: www.mysite.com. By default the "umbracoApplicationUrl" will be www.mysite.com. However, load balancers may route the request internally under a different DNS name such as "f02.mysite.local" which by default would mean the "umbracoApplicationUrl" is "f02.mysite.local". In any case the elected "Scheduling server" must be able to resolve this address.

In many scenarios this is fine, but in case this is not adequate there's a few of options you can use:

Common load balancing setup information

The below section applies to all ASP.NET load balancing configurations.

Server Configuration

This section describes the configuration options depending on your hosting setup:

Data Protection

The replacement for Machine Keys in ASP.NET Core are called Data Protection. You will need to setup data protection to the same keys on all servers, without this you will end up with view state errors, validation errors and encryption/decryption errors since each server will have its own generated key.

Session State and Distributed Cache

Because Umbraco in some cases uses TempData, your setup needs to be configured with a distributed cache.

Logging

There are some logging configurations to take into account no matter what type of load balancing environment you are using.

Testing

Your staging environment should also be load balanced so that you can see any issues relating to load balancing in that environment before going to production.

You'll need to test this solution a lot before going to production. You need to ensure there are no windows security issues, etc... The best way to determine issues is have a lot of people testing this setup and ensuring all errors and warnings in your application/system logs in Windows are fixed.

Ensure to analyze logs from all servers and check for any warnings and errors.

Unattended upgrades

When upgrading it is possible to run the upgrades unattended.

FAQs

Here's some common questions that are asked regarding Load Balancing with Umbraco:

Question> Why do I need to have a single web instance for Umbraco admin?

TL:DR You must not load balance the Umbraco backoffice, you will end up with data integrity or corruption issues.

The reason you need a single server is because there is no way to guarantee transactional safety between servers. This is because we don't currently use database level locking, we only use application (c#) level locks to guarantee transactional data integrity which is only possible to work on one server. If you have multiple admins saving and publishing at once between servers then the order in which this data is read and written to the database absolutely must be consistent otherwise you will end up with data corruption.

Additionally, the order in which cache instructions are written to the cache instructions table is important for LB, this order is guaranteed by having a single admin server.

Question> Can my SchedulingPublisher backoffice admin server also serve front-end requests?

Yes. There are no problems with having your SchedulingPublisher backoffice admin server also serve front-end request.

However, if you wish to have different security policies for your front-end servers and your back office servers, you may choose to not do this.

Load Balancing Azure Web Apps

Ensure you read the and general documentation before you begin - you will need to ensure that your ASP.NET Core & logging configurations are correct.

Azure Requirements

2 x App service plans with 1 x web app in each:
- One for the backoffice (Administrative) environment
- One for your scalable public-facing environment (Public)
1 x SQL server that is shared with these 2 web apps

The setup above will allow for the proper scaling of the Administrative and Public web apps.

The App Service plan with the Administrative web app should only be scaled up. The reason for this is that the web app needs to stay as a single instance.

The App Service plan with the Public web app can be scaled both out and up.

Lucene/Examine configuration

Umbraco TEMP files

When an instance of Umbraco starts up it generates some 'temporary' files on disk. In a normal IIS environment, these would be created within the folders of the Web Application. In an Azure Web App, we want these to be created in the local storage of the actual server that Azure happens to be used for the Web App. So we set this configuration setting to 'true' and the temporary files will be located in the environment temporary folder. This is required for both the performance of the website as well as to prevent file locks from occurring due to the nature of Azure Web Apps shared files system.

Host synchronization

When a host restarts, the current host 'winds down' while another host is started. This means there can be more than one live host during a restart. Restarts can occur in many scenarios including when an Azure Web App auto-transitions between hosts, you scale the instances or you utilize slot swapping.

Some file system based services in Umbraco such as the Published Cache and Lucene files can only be accessed by a single host at once. Umbraco manages this synchronization by an object called IMainDom.

By default Umbraco v9.4 & 9.5 uses a system-wide semaphore locking mechanism. This mechanism only works on Windows systems and doesn't work with multi-instance Azure Web Apps. We need to swap it out for an alternative file system based locking mechanism by using the following appSetting. With Umbraco v10+ FileSystemMainDomLock is the default setting.

Apply this setting to both the SCHEDULINGPUBLISHER Administrative server and the SUBSCRIBER scalable public-facing servers.

Steps to set-up an environment

Create an Azure SQL database
Install Umbraco on your backoffice administrative environment and ensure to use your Azure SQL Database
Install Umbraco on your scalable public-facing environment and ensure to use your Azure SQL Database
Test: Perform some content updates on the administrative environment, ensure they work successfully in that environment, then verify that those changes appear on the scalable public-facing environment

Ensure all Azure resources are in the same region to avoid connection lag.

Scaling

Do not scale your backoffice administrative environment this is not supported and can cause issues.

The public-facing subscriber Azure Web Apps can be manually or automatically scaled up or down and is supported by Umbraco's load balancing.

Deployment considerations

Since you have 2 x web apps, when you deploy you will need to deploy to both places - There are various automation techniques you can use to simplify the process. That is outside the scope of this article.

This also means that you should not be editing templates or views on a live server as SchedulingPublisher and Subscriber environments do not share the same file system. Changes should be made in a development environment and then pushed to each live environment.

Standalone File System

No file replication is configured, deployment handles updating files on the different servers.

If the file system on your servers isn't performing any file replication then no Umbraco configuration file changes are necessary. However Media will need to be configured to use a shared location such as Blob storage or S3.

Depending on the configuration and performance of the environment's local storage you might need to consider and the .

Synchronised File System

The servers are performing file replication, updates to a file on one server, updates the corresponding file on any other servers.

If the file system on your servers is performing file replication then the Umbraco temporary folder (~/umbraco/Data/TEMP) must be excluded from replication.

If the file system on your servers is located on shared storage you will need to configure Umbraco to locate the Umbraco temporary folder outside of the shared storage.

Replication techniques

A common way to replicate files on Windows Server is to use [DFS](https://msdn.microsoft.com/en-us/library/windows/desktop/bb540031(v=vs.85), which is included with Windows Server.

Additional DFS resources:

There are other alternatives for file replication out there, some free and some licensed. You'll need to decide which solution is best for your environment.

Non-replicated files

When deploying Umbraco in a load balanced scenario using file replication, it is important to ensure that not all files are replicated - otherwise you will experience file locking issues. Here are the folders and files that should not be replicated:

~/umbraco/Data/TEMP/*

Achieve this by changing the value of the LuceneDirectoryFactory setting to 'TempFileSystemDirectoryFactory' in the appsettings.json. The downside is that if you need to view temporary files you'll have to find it in the temp files. Locating the file this way isn't always clear.

Below is shown how to do this in a Json configuration source.

~/umbraco/Logs/*
- This is optional and depends on how you want your logs configured (see below)

If for some reason your file replication solution doesn't allow you to not replicate specific files folders (which it should!!) then you can use an alternative approach by using virtual directories.

The following is not the recommended setup but it is a viable alternative:

Copy the ~/umbraco/Data/TEMP directory to each server, outside of any replication areas or to a unique folder for each server.
Create a virtual directory (not a virtual application) in the ~/umbraco/Data/ folder, and name it TEMP. Point the virtual directory to the folder you created in step 2.
You may delete the ~/umbraco/Data/TEMP folder from the file system - not IIS as this may delete the virtual directory - if you wish.

IIS Setup

IIS configuration is pretty straightforward with file replication. IIS is only reading files from its own file system like a normal IIS website.

Mixture of standalone & synchronised

In some scenarios you have a mixture of standalone and synchronised file systems. An example of this is Azure Web Apps where the file system isn't replicated between backoffice and front end servers but is replicated between all front end servers, in this configuration you should follow the steps for synchronised file systems.

Examine Directory Factory Options

The TempFileSystemDirectoryFactory allows Examine to store indexes directly in the environment temporary storage directory, and should be used instead of SyncTempEnvDirectoryFactory mentioned above.

The SyncedTempFileSystemDirectoryFactory enables Examine to sync indexes between the remote file system and the local environment temporary storage directory, the indexes will be accessed from the temporary storage directory. This setting is needed because Lucene has issues when working from a remote file share so the files need to be read/accessed locally. Any time the index is updated, this setting will ensure that both the locally created indexes and the normal indexes are written to. This will ensure that when the app is restarted or the local environment temp files are cleared out that the index files can be restored from the centrally stored index files.

Advanced techniques

Advanced Techniques With Flexible Load Balancing

This describes some more advanced techniques that you could achieve with flexible load balancing

The election process that runs during the startup of an Umbraco instance determines the server role that instance will undertake.

There are two server roles to be aware of for flexible load balancing:

SchedulingPublisher - The Umbraco instance usually used for backoffice access, responsible for running scheduled tasks.
Subscriber - A scalable instance that subscribes to content updates from the SchedulingPublisher server, not recommended to be used for backoffice access.

These new terms replace 'Master and Replica', in Umbraco versions 7 and 8.

Explicit SchedulingPublisher server

It is recommended to configure an explicit SchedulingPublisher server since this reduces the amount of complexity that the election process performs.

The first thing to do is create a couple of small classes that implement IServerRoleAccessor one for each of the different server roles:

public class SchedulingPublisherServerRoleAccessor : IServerRoleAccessor
{
    public ServerRole CurrentServerRole => ServerRole.SchedulingPublisher;
}

public class SubscriberServerRoleAccessor : IServerRoleAccessor
{
    public ServerRole CurrentServerRole => ServerRole.Subscriber;
}

then you'll need to replace the default IServerRoleAccessor for the your custom registrars. You'll can do this by using the SetServerRegistrar() extension method on IUmbracoBuilder from a Composer.

// This should be executed on your single `SchedulingPublisher` server
builder.SetServerRegistrar<SchedulingPublisherServerRoleAccessor>();

// This should be executed on your `Subscriber` servers
builder.SetServerRegistrar<SubscriberServerRoleAccessor>();

By setting your SchedulingPublisher server to use your custom SchedulingPublisherServerRoleAccessor class, it will always be deemed the 'SchedulingPublisher' and will always be the one that executes all task scheduling.

Subscriber servers - Read-only database access

This description pertains only to Umbraco database tables

In some cases infrastructure admins will not want their front-end servers to have write access to the database. By default front-end servers will require write full access to the following tables:

umbracoServer
umbracoNode

This is because by default each server will inform the database that they are active and more importantly it is used for task scheduling. Only a single server can execute task scheduling and these tables are used for servers to use a server role election process without the need for any configuration. So in the case that a subscriber server becomes the SchedulingPublisher task scheduler, it will require write access to all of the Umbraco tables.

In order to have read-only database access configured for your front-end servers, you need to implement the Explicit SchedulingPublisher server configuration mentioned above.

Now that your subscriber servers are using your custom SubscriberServerRoleAccessor class, they will always be deemed 'Subscriber' servers and will not attempt to run the automatic server role election process or task scheduling. Because you are no longer using the default ElectedServerRoleAccessor they will not try to ping the umbracoServer table.

If using SqlMainDomLock on Azure WebApps then write-permissions are required for the following tables for all server roles including 'Subscriber'.

umbracoLock
umbracoKeyValue

SQL Server Replica databases cannot be used as they are read-only without replacing the default MainDomLock with a custom provider.

Controlling how often the load balancing instructions from the database are processed and pruned

The configurations can be adjusted to control how often the load balancing instructions from the database are processed and pruned.

Below is shown how to do this from a JSON configuration source.

{
    "Umbraco": {
        "CMS": {
            "Global": {
                "DatabaseServerMessenger": {
                    "MaxProcessingInstructionCount": 1000,
                    "TimeBetweenPruneOperations": "00:01:00",
                    "TimeBetweenSyncOperations": "00:00:05",
                    "TimeToRetainInstructions": "2.00:00:00"
                }
            }
        }
    }
}

Options:

TimeToRetainInstructions - The timespan to keep instructions in the database; records older than this number will be pruned.
MaxProcessingInstructionCount - The maximum number of instructions that can be processed at startup; otherwise the server cold-boots (rebuilds its caches)
TimeBetweenSyncOperations - The timespan to wait between each sync operations
TimeBetweenPruneOperations - The timespan to wait between each prune operation

These setting would normally be applied to all environments as they are added to the global app settings. If you need these settings to be environment specific, we recommend using environment specific appSetting files.

Logging With Load Balancing

Umbraco v8+ uses Serilog for logging. When load balancing Umbraco consideration should be given as to how the log files from each server will be accessed.

There are many Serilog Sinks available. One of these may be appropriate to store logs for all servers in a central repository such as Azure Application Insights or Elmah.io.

For more information, see SeriLog Provided Sinks.

Backoffice

Learn more about the Umbraco backoffice which is the admin side of your Umbraco website.

In this article you can learn more about the common terms and concepts that are used throughout the Umbraco backoffice.

When you go to the backoffice for the first time, you're presented with the login screen.

Section

A section in Umbraco is where you do specific tasks related to that section. For example Content, Settings and Users. You can navigate between the different sections of the backoffice by clicking the corresponding icon in the section menu.

The Section menu is the horizontal menu located on the top of the backoffice.

Tree

A tree is a hierarchical list of items related (and usually restricted) to a specific concept, like for example content or media.

Node

A node is an item in a tree. Media section items appear as nodes in the Media tree, while pages and content are displayed in the Content tree, and so on.

Dashboards

A dashboard is the main view you are presented with when entering a section within the backoffice. It can be used to show valuable information to the users of the system.

Default dashboard in the content section

Editor

An editor is what you use to edit different items within the backoffice. There are editors specific to editing stylesheets, there are editors for editing Macros, and so forth.

Content

Content is what you find in the Content section. Each item in the tree is called a content node. Each content node in the content tree consists of different fields, and each of them is defined by a Document Type.

Document Type

Document Types define the types of content nodes that backoffice users can create in the content tree. Each Document Type contains different properties. Each property has a specific Data Type for example text or number.

Properties

Every Document Type has properties. These are the fields that the content editor is allowed to edit for the content node.

Data Type

Each Document Type property has a Data Type that defines the type of input of that property. Data Types reference a Property Editor and are configured in the Umbraco backoffice in the Settings section. A Data Type can be something basic (text string, number, true/false) or more complex (multi-node tree picker, image cropper, etc).

Property Editors

A property editor is a view used by Data Types to insert content into Umbraco. An example of a property editor is the Textarea. It's possible to have many Textarea Data Types with different settings that all use the Textarea property editor.

Media

Media items are used to store assets like images and video within the Media section and can be referenced from your content.

Media Types

Media Types are similar to Document Types in Umbraco, except they are specifically for media items in the Media section.

Umbraco comes with 3 default Media Types: File, Folder, and Image.

Members

A member is someone who has access to signup, register, and login into your public website and is not to be confused with Users.

Member Types

Similar to a Document Type and a Media Type. You are able to define custom properties to store on a member such as Twitter username or website URL.

Templates

A Template is where you define the HTML markup of your website and also where you output the data from your content nodes.

Packages

A package is the Umbraco term for an add-on or plugin used to extend the core functionalities in Umbraco. The packages can be found on the Umbraco Marketplace, and the can also be browsed directly in the backoffice of the Umbraco CMS.

Macros

A macro is a reusable piece of functionality that you can reuse throughout your site. Macros can be configured with parameters and used on content nodes that have a Rich Text Editor, a Grid editor, or a Macro Picker property. You can define what macros are available for your editors to use. When an editor inserts a macro it will prompt them to fill out any of the defined parameters for the macro.

Macro Parameter Editor

A parameter editor defines the usage of a property editor for use as a parameter for Macros.

Users

A user is someone who has access to the Umbraco backoffice and is not to be confused with Members. When Umbraco has been installed a user will automatically be generated with the login (email) and password entered during installation. Users can be created, edited, and managed in the User section.

Content Templates

Content Templates provide a blueprint for content nodes based on an existing node.

Sections

In this article you can learn more about the various sections you can find within the Umbraco Backoffice.

A section in Umbraco is where you perform specific tasks related to a particular area of Umbraco. For example Content, Settings and Users are all sections. You can navigate between the different sections by clicking the corresponding icon in the section menu which is positioned at the top of the Backoffice.

The Section menu is the horizontal menu located at the top of the Umbraco Backoffice.

There are eight default sections that come with Umbraco:

Content

The Content section contains the content of the website. Content is displayed as nodes in the content tree. Nodes can also show content state:

Grayed out nodes have not been published

In order to create content, you must define it using Document Types.

Media

The Media section contains the media for the website. By default, you can create folders and upload media files (images and PDFs). You can customize the existing media types or define your own from the Settings section.

Settings

The Settings section is where you can work with the website layout files, languages, and define media and content types. In this section, you can also find the Log Viewer to browse through your log files.

The Settings tree consists of:

Document Types
Media Types
Member Types
Data Types
Macros
Relation Types
Log Viewer
Languages
Content Templates
Templates (.cshtml files)
Partial views (.cshtml files)
Partial View Macro Files (.cshtml files)
Stylesheets (.css files)
Scripts (.js files)

The Settings section of the Umbraco backoffice has its own set of default dashboards. For more information, see the Settings Dashboards article.

Packages

In this section, you can browse and install packages into your Umbraco solution. You can also get an overview of all the installed packages as well as uninstall packages you no longer need.

Users

Manage, create, and customize Backoffice users and user groups.

Members

Manage, create, and customize members and member groups.

Forms

You can install Umbraco Forms directly from the Backoffice by clicking the install button. Once installed, this section is where you create and manage your forms.

Translation

This is the section where you create and manage your dictionary items.

Help sections

In the top-right corner, you'll find a search tool, which is also accessible by hitting CTRL + Space on your keyboard.

Next to the search tool, there is a help section. In the help section you can find Backoffice tours and links to Umbraco resources such as documentation and UmbracoTV.

There is also a small 'user section' with shortcuts to edit the currently logged in user, and view their most recent activities.

Custom Sections

Along with the default sections that come with Umbraco, you can create your own Custom Sections.

Access based on User Group

A User can access a particular section based on the User Group permissions.

Learn more about how to configure the permissions in the article about backoffice users.

Property Editors

Learn more about the default property editors that ships with an Umbraco installation.

A Property Editor is the editor that a Data Type references. A Data Type is defined by a user in the Umbraco backoffice and references a Property Editor. In Umbraco a Property Editor is defined in a JSON manifest file and associated JavaScript files.

When creating a Data Type, specify the property editor for the Data Type to use by selecting from the "Property editor" list (as shown below).

Built-in Property Editors in Umbraco

Umbraco comes pre-installed with many useful property editors.

More information

Customizing Data Types

Tutorials

How to create a custom Property Editor

Built-in Property Editors

Checkbox List

Alias: Umbraco.CheckBoxList

Returns: IEnumerable<string>

Displays a list of preset values as a list of checkbox controls. The text saved is an IEnumerable collection of the text values.

Unlike other property editors, the Prevalue IDs are not directly accessible in Razor.

Data Type Definition Example

You can use dictionary items to translate the values of a Checkbox List property editor in a multilingual setup. For more details, see the Creating a Multilingual Site article.

Content Example

MVC View Example

Without Modelsbuilder

@{
    if (Model.HasValue("superHeros"))
    {
        <ul>
            @foreach (var item in Model.Value<IEnumerable<string>>("superHeros"))
            {
                <li>@item</li>
            }
        </ul>
    }
}

With Modelsbuilder

@{
    if (Model.SuperHeros.Any())
    {
        <ul>
            @foreach (var item in Model.SuperHeros)
            {
                <li>@item</li>
            }
        </ul>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.

@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@using Newtonsoft.Json
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'superHeros'.
    content.SetValue("superHeros", JsonConvert.SerializeObject(new[] { "Umbraco", "CodeGarden"}));

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234);
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;
@{

// Set the value of the property with alias 'superHeros'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor,x => x.SuperHeros).Alias, JsonConvert.SerializeObject(new[] { "Umbraco", "CodeGarden"}));
}

Content Picker

Alias: Umbraco.ContentPicker

Returns: IPublishedContent

The content picker opens a panel to pick a specific page from the content structure. The value saved is the selected nodes UDI

Data Type Definition Example

Content Example

MVC View Example

Without Modelsbuilder

@{
    IPublishedContent typedContentPicker = Model.Value<IPublishedContent>("featurePicker");
    if (typedContentPicker != null)
    {
        <p>@typedContentPicker.Name</p>
    }
}

With Modelsbuilder

@{
    IPublishedContent typedContentPicker = Model.FeaturePicker;
    if (typedContentPicker != null)
    {
        <p>@typedContentPicker.Name</p>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core.Services;

@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Get the page you want to assign to the content picker 
    var page = Umbraco.Content("665d7368-e43e-4a83-b1d4-43853860dc45");
    
    // Create an Udi of the page
    var udi = Udi.Create(Constants.UdiEntityType.Document, page.Key);

    // Set the value of the property with alias 'featurePicker'. 
    content.SetValue("featurePicker", udi.ToString());

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@using Umbraco.Cms.Core;

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
    // Set the value of the property with alias 'featurePicker'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.FeaturePicker).Alias, udi.ToString());
}

DateTime

Alias: Umbraco.DateTime

Returns: DateTime

Displays a calendar UI for selecting dates which are saved as a DateTime value.

Data Type Definition Example

There are two settings available for manipulating the DateTime property.

One is to set a format. By default the format of the date in the Umbraco backoffice will be YYYY-MM-DD HH:mm:ss, but you can change this to something else. See MomentJS.com for the supported formats.

The second setting is "Offset time". When enabling this setting the displayed time will be offset with the servers timezone. This can be useful in cases where an editor is in a different timezone than the hosted server.

Content Example

MVC View Example - displays a datetime

With Modelsbuilder

@Model.DatePicker

Without Modelsbuilder

@Model.Value("datePicker")

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'datePicker'
    content.SetValue("datePicker", DateTime.Now);

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{

    // Set the value of the property with alias 'datePicker'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.DatePicker).Alias, DateTime.Now);
}

Date

Returns: Date

Displays a calendar UI for selecting dates which are saved as a DateTime value.

Data Type Definition Example

The only setting that is available for manipulating the Date property is to set a format. By default the format of the date in the Umbraco backoffice will be YYYY-MM-DD, but you can change this to something else. See MomentJS.com for the supported formats.

Content Example

MVC View Example - displays a datetime

Typed

@(Model.Content.GetPropertyValue<DateTime>("datePicker").ToString("dd MM yyyy"))

Dynamic (Obsolete)

See Common pitfalls for more information about why the dynamic approach is obsolete.

@{
    @CurrentPage.datePicker.ToString("dd-MM-yyyy")
}

Decimal

Alias: Umbraco.Decimal

Returns: decimal

Data Type Definition Example

In the example above the possible values for the input field would be [8, 8.5, 9, 9.5, 10]

All other values will be removed in the content editor when saving or publishing.

If the value of Step Size is not set then all decimal values between 8 and 10 is possible to input in the content editor.

Content Example

MVC View Example

With Modelsbuilder

@Model.MyDecimal

Without Modelsbuilder

@Model.Value("MyDecimal")

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'myDecimal'. 
    content.SetValue("myDecimal", 3);

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;
@{
    // Set the value of the property with alias 'myDecimal'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MyDecimal).Alias, 3);
}

Email Address

In this article you can learn how to use the build in email property editor

Alias: Umbraco.EmailAddress

Returns: String

Displays an email address.

Settings

The Email Address Property Editor does not come with any further configuration. The property can be configured once it has been added to a Document Type.

Content Example

MVC View Example

Without Modelsbuilder

@if (Model.HasValue("email"))
{
    var emailAddress = Model.Value<string>("email");
    <p>@emailAddress</p>
}

With Modelsbuilder

@if (!string.IsNullOrWhiteSpace(Model.Email))
{
    <p>@Model.Email</p>
}

Add value programmatically

See the example below to learn how a value can be added or changed programmatically to an Email-address property. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core.Services;

@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of your page
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");

    // Get the page using the GUID you've just defined
    var content = contentService.GetById(guid);
    // Set the value of the property with alias 'email'
    content.SetValue("email", "jpk@umbraco.dk");

    // Save the change
    contentService.Save(content);
}

The value sent to an EmailAddress property needs to be a correct email address, For example: name@domain.com.

It is recommended that you set up validation on this property, in order to verify whether the value added is in the correct format.

Eye Dropper Color Picker

Alias: Umbraco.ColorPicker.EyeDropper

Returns: string

The Eye Dropper Color picker allows you to choose a color from the full color spectrum using HEX and RGBA.

Data Type Definition Example

Content Example

Example with Modelsbuilder

Example without Modelsbuilder

Add values programmatically

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

File Upload

Alias: Umbraco.UploadField

Returns: string

Adds an upload field, which allows documents or images to be uploaded to Umbraco.

You can define which file types should be accepted through the upload field.

For uploading and adding files and images to your Umbraco project, we recommend using the Media Picker.

Find the full documentation for the property in the article.

Data Type Definition Example

Content Example

In code, the property is a string, which references the location of the file.

Example: "/media/o01axaqu/guidelines-on-remote-working.pdf"

MVC View Example

Without Modelsbuilder

With Modelsbuilder

Add values programmatically

The samples in this section have not been verified against the latest version of Umbraco.

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

Label

Alias: Umbraco.Label

Returns: String

Label is a non-editable control and can only be used to display a pre-set value.

Data Type Definition Example

Value type

If you want to set a value other than a String, you can define the data using one of the other available Data Types. These include Decimal, Date/time, Time, Integer, and Big integer.

There is also a Value Type: Long string if you need to set a long string value for your Label.

Content Example

MVC View Example

Without ModelsBuilder

With ModelsBuilder

Add values programmatically

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

Version Specific Upgrades

This document covers specific upgrade steps if a version requires them. Most versions do not require specific upgrade steps and you will be able to upgrade directly from your current version.

Use the information below to learn about any potential breaking changes and common pitfalls when upgrading your Umbraco CMS project.

If any specific steps are involved with upgrading to a specific version they will be listed below.

Use the general upgrade guide to complete the upgrade of your project.

Breaking changes

Umbraco 13

Below you can find the list of breaking changes introduced in Umbraco 13.

You can find more information about all breaking changes for v13.0.0 on Our Umbraco website.

Note: You need to be aware of some things if you are using EF Core, and have installed the Microsoft.EntityFrameworkCore.Design 8.0.0 package:

This package has a transient dependency to Microsoft.CodeAnalysis.Common which clashes with the same transient dependency from Umbraco.Cms 13.0.0. This happens because Microsoft.EntityFrameworkCore.Design 8.0.0 requires Microsoft.CodeAnalysis.CSharp.Workspaces in v4.5.0 or higher.
If there are no other dependencies that need that package then it installs it in the lowest allowed version (4.5.0). That package then has a strict dependency on Microsoft.CodeAnalysis.Common version 4.5.0. The problem is Umbraco.Cms through its own transient dependencies that require the version of Microsoft.CodeAnalysis.Common to be >= 4.8.0.
This can be fixed by installing Microsoft.CodeAnalysis.CSharp.Workspaces version 4.8.0 as a specific package instead of leaving it as a transient dependency. This is because it will then have a strict transient dependency on Microsoft.CodeAnalysis.Common version 4.8.0, which is the same that Umbraco has.

Umbraco 12

Umbraco 12 does not include many binary breaking changes, but there are some.

Most notable is a functional breaking change in Migrations, that from Umbraco 12. Each translation will be executed in its own transactions instead of all migrations in one big transaction. This change has been made to ease the support for Sqlite.

A type, enum, record, or struct visible outside the assembly is missing in the compared assembly when required to be present.

PagedModel has moved namespace from Umbraco.New.Cms.Core.Models to Umbraco.Cms.Core.Models
Umbraco.Cms.Infrastructure.Migrations.PostMigrations.ClearCsrfCookies is removed. The functionality can be archived by implementing a notification handler for the new UmbracoPlanExecutedNotification.
Umbraco.Cms.Core.Cache.DistributedCacheBinder is now divided into separate files for each notification handler
Umbraco.Cms.Infrastructure.Migrations.PostMigrations.DeleteLogViewerQueryFile was a no-op method removed.
Umbraco.Cms.Infrastructure.Migrations.PostMigrations.RebuildPublishedSnapshot replaced with a RebuildCache flag on the MigrationBase

A member that is visible outside of the assembly is missing in the compared assembly when required to be present.

Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor.Execute(Umbraco.Cms.Infrastructure.Migrations.MigrationPlan,System.String) replaced with Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor.ExecutePlan(Umbraco.Cms.Infrastructure.* * Migrations.MigrationPlan,System.String) that returns an rich object instead of a string
Umbraco.Cms.Infrastructure.Migrations.IMigrationContext.AddPostMigration``1 Removed and replaced with notification
Umbraco.Cms.Infrastructure.Migrations.MigrationPlan.AddPostMigration``1
Removed and replaced with notification
Umbraco.Cms.Infrastructure.Migrations.MigrationPlan.get_PostMigrationTypes removed.
Umbraco.Cms.Infrastructure.Migrations.Upgrade.Upgrader.Execute(Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor,Umbraco.Cms.Core.Scoping.IScopeProvider,Umbraco.Cms.Core.Services.IKeyValueService) was obsolete and is replaced by method taking a ICoreScopeProvider instead of a IScopeProvider

An abstract member was added to the right side of the comparison to an unsealed type.

PublishedPropertyBase now requires inheritors to implement GetDeliveryApiValue(System.Boolean,System.String,System.String)

A member was added to an interface without a default implementation.

Umbraco.Cms.Core.Events.IEventAggregator.Publish2(System.Collections.Generic.IEnumerable{0})
Umbraco.Cms.Core.Events.IEventAggregator.PublishAsync2(System.Collections.Generic.IEnumerable{0},System.Threading.CancellationToken)
Umbraco.Cms.Core.Models.PublishedContent.IPublishedProperty.GetDeliveryApiValue(System.Boolean,System.String,System.String)
Umbraco.Cms.Core.Models.PublishedContent.IPublishedPropertyType.ConvertInterToDeliveryApiObject(Umbraco.Cms.Core.Models.PublishedContent.IPublishedElement,Umbraco.Cms.Core.PropertyEditors.PropertyCacheLevel,System.Object,System.Boolean,System.Boolean)
Umbraco.Cms.Core.Models.PublishedContent.IPublishedPropertyType.ConvertInterToDeliveryApiObject(Umbraco.Cms.Core.Models.PublishedContent.IPublishedElement,Umbraco.Cms.Core.PropertyEditors.PropertyCacheLevel,System.Object,System.Boolean)
Umbraco.Cms.Core.Models.PublishedContent.IPublishedPropertyType.DeliveryApiCacheLevel
Umbraco.Cms.Core.Scoping.ICoreScope.Locks
Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor.ExecutePlan(Umbraco.Cms.Infrastructure.Migrations.MigrationPlan,System.String)
Umbraco.Cms.Infrastructure.Search.IUmbracoIndexingHandler.RemoveProtectedContent
Umbraco.Cms.Infrastructure.Examine.IUmbracoIndex.SupportProtectedContent

Umbraco 11

Most breaking changes are introduced due to updated dependencies. The breaking changes in .NET 7 and ASP.NET Core 7 are documented by Microsoft.

Besides the documented changes, we have also seen a few method signatures that are changed to support Nullable-Reference-Types.

If you are using TinyMCE plugins or custom TinyMCE configuration you need to migrate to the latest version. Learn more about this in the Rich Text Editor documentation.

The breaking changes in TinyMCE are also documented in the official migration guides for version 4 to 5 and from version 5 to 6.

The breaking changes in Umbraco 11 are mainly the removal of classes, methods, and so on, marked as obsolete in Umbraco 9.

A few methods and classes have also been moved and changed namespace. Decoupled dependencies are documented on the Umbraco Announcements repository.

The full list of API-breaking changes can be found below.

Obsolete code removed

The following have been removed after having been obsoleted since Umbraco 9.

Umbraco.Extensions

Umbraco.Extensions.ServiceCollectionExtensions.AddUnique<TImplementing>(Microsoft.Extensions.DependencyInjection.IServiceCollection)

Umbraco.Extensions.EnumExtensions.HasFlagAll<T>(T, T)

Umbraco.Extensions.FriendlyImageCropperTemplateExtensions.GetLocalCropUrl(Umbraco.Cms.Core.Models.MediaWithCrops, string, string?)

Umbraco.Cms.Core

Umbraco.Cms.Core.Constants.Conventions.Member.IsApproved
Umbraco.Cms.Core.Constants.Conventions.Member.IsApprovedLabel
Umbraco.Cms.Core.Constants.Conventions.Member.IsLockedOut
Umbraco.Cms.Core.Constants.Conventions.Member.IsLockedOutLabel
Umbraco.Cms.Core.Constants.Conventions.Member.LastLoginDate
Umbraco.Cms.Core.Constants.Conventions.Member.LastLoginDateLabel
Umbraco.Cms.Core.Constants.Conventions.Member.LastPasswordChangeDate
Umbraco.Cms.Core.Constants.Conventions.Member.LastPasswordChangeDateLabel
Umbraco.Cms.Core.Constants.Conventions.Member.LastLockoutDate
Umbraco.Cms.Core.Constants.Conventions.Member.LastLockoutDateLabel
Umbraco.Cms.Core.Constants.Conventions.Member.FailedPasswordAttempts
Umbraco.Cms.Core.Constants.Conventions.Member.FailedPasswordAttemptsLabel

Umbraco.Cms.Core.WebAssets.IRuntimeMinifier.Reset()

Umbraco.Cms.Core.Services.IExternalLoginService

Umbraco.Cms.Core.Services.ExternalLoginService.ExternalLoginService(
    Umbraco.Cms.Core.Scoping.ICoreScopeProvider,
    Microsoft.Extensions.Logging.ILoggerFactory,
    Umbraco.Cms.Core.Events.IEventMessagesFactory,
    Umbraco.Cms.Core.Persistence.Repositories.IExternalLoginRepository)

Umbraco.Cms.Core.Services.ExternalLoginService.GetExternalLogins(int)

Umbraco.Cms.Core.Services.ExternalLoginService.GetExternalLoginTokens(int)

Umbraco.Cms.Core.Services.ExternalLoginService.Save(int,
    System.Collections.Generic.IEnumerable<Umbraco.Cms.Core.Security.IExternalLogin>)

Umbraco.Cms.Core.Services.ExternalLoginService.Save(int,
    System.Collections.Generic.IEnumerable<Umbraco.Cms.Core.Security.IExternalLoginToken>)

Umbraco.Cms.Core.Services.ExternalLoginService.DeleteUserLogins(int)

Umbraco.Cms.Core.Services.IMacroWithAliasService

Umbraco.Cms.Core.Services.ITwoFactorLoginService2

Umbraco.Cms.Core.Services.LocalizedTextService.LocalizedTextService(
    System.Collections.Generic.IDictionary<System.Globalization.CultureInfo, System.Collections.Generic.IDictionary<string, System.Collections.Generic.IDictionary<string, string>>>,
    Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Core.Services.LocalizedTextService>)

Umbraco.Cms.Core.Services.ServiceContext.ServiceContext(
    System.Lazy<Umbraco.Cms.Core.Services.IPublicAccessService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IDomainService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IAuditService>?,
    System.Lazy<Umbraco.Cms.Core.Services.ILocalizedTextService>?,
    System.Lazy<Umbraco.Cms.Core.Services.ITagService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IContentService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IUserService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMemberService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMediaService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IContentTypeService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMediaTypeService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IDataTypeService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IFileService>?,
    System.Lazy<Umbraco.Cms.Core.Services.ILocalizationService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IPackagingService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IServerRegistrationService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IEntityService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IRelationService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMacroService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMemberTypeService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMemberGroupService>?,
    System.Lazy<Umbraco.Cms.Core.Services.INotificationService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IExternalLoginService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IRedirectUrlService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IConsentService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IKeyValueService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IContentTypeBaseServiceProvider>?)

Umbraco.Cms.Core.Services.ServiceContext.CreatePartial(
    Umbraco.Cms.Core.Services.IContentService?,
    Umbraco.Cms.Core.Services.IMediaService?,
    Umbraco.Cms.Core.Services.IContentTypeService?,
    Umbraco.Cms.Core.Services.IMediaTypeService?,
    Umbraco.Cms.Core.Services.IDataTypeService?,
    Umbraco.Cms.Core.Services.IFileService?,
    Umbraco.Cms.Core.Services.ILocalizationService?,
    Umbraco.Cms.Core.Services.IPackagingService?,
    Umbraco.Cms.Core.Services.IEntityService?,
    Umbraco.Cms.Core.Services.IRelationService?,
    Umbraco.Cms.Core.Services.IMemberGroupService?,
    Umbraco.Cms.Core.Services.IMemberTypeService?,
    Umbraco.Cms.Core.Services.IMemberService?,
    Umbraco.Cms.Core.Services.IUserService?,
    Umbraco.Cms.Core.Services.ITagService?,
    Umbraco.Cms.Core.Services.INotificationService?,
    Umbraco.Cms.Core.Services.ILocalizedTextService?,
    Umbraco.Cms.Core.Services.IAuditService?,
    Umbraco.Cms.Core.Services.IDomainService?,
    Umbraco.Cms.Core.Services.IMacroService?,
    Umbraco.Cms.Core.Services.IPublicAccessService?,
    Umbraco.Cms.Core.Services.IExternalLoginService?,
    Umbraco.Cms.Core.Services.IServerRegistrationService?,
    Umbraco.Cms.Core.Services.IRedirectUrlService?,
    Umbraco.Cms.Core.Services.IConsentService?,
    Umbraco.Cms.Core.Services.IKeyValueService?,
    Umbraco.Cms.Core.Services.IContentTypeBaseServiceProvider?)

Umbraco.Cms.Core.Services.TwoFactorLoginService.TwoFactorLoginService(
    Umbraco.Cms.Core.Persistence.Repositories.ITwoFactorLoginRepository,
    Umbraco.Cms.Core.Scoping.ICoreScopeProvider,
    System.Collections.Generic.IEnumerable<Umbraco.Cms.Core.Security.ITwoFactorProvider>,
    Microsoft.Extensions.Options.IOptions<Microsoft.AspNetCore.Identity.IdentityOptions>,
    Microsoft.Extensions.Options.IOptions<Umbraco.Cms.Core.Security.BackOfficeIdentityOptions>)

Umbraco.Cms.Core.Routing.DefaultUrlProvider.DefaultUrlProvider(
    Microsoft.Extensions.Options.IOptionsMonitor<Umbraco.Cms.Core.Configuration.Models.RequestHandlerSettings>,
    Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Core.Routing.DefaultUrlProvider>,
    Umbraco.Cms.Core.Routing.ISiteDomainMapper,
    Umbraco.Cms.Core.Web.IUmbracoContextAccessor,
    Umbraco.Cms.Core.Routing.UriUtility)

Umbraco.Cms.Core.Persistence.Repositories.IExternalLoginRepository

Umbraco.Cms.Core.Persistence.Repositories.IMacroWithAliasRepository

Umbraco.Cms.Core.Persistence.Repositories.IMemberRepository.SetLastLogin(string, System.DateTime)

Umbraco.Cms.Core.Notifications.UmbracoApplicationComponentsInstallingNotification

Umbraco.Cms.Core.Notifications.UmbracoApplicationMainDomAcquiredNotification


Umbraco.Cms.Core.Notifications.UmbracoApplicationStartingNotification.UmbracoApplicationStartingNotification(Umbraco.Cms.Core.RuntimeLevel)

Umbraco.Cms.Core.Notifications.UmbracoApplicationStoppingNotification.UmbracoApplicationStoppingNotification()

Umbraco.Cms.Core.Models.IContentTypeWithHistoryCleanup

Umbraco.Cms.Core.Models.Language.Language(Umbraco.Cms.Core.Configuration.Models.GlobalSettings, string)

Umbraco.Cms.Core.Models.RelationType.RelationType(string, string, bool, System.Nullable<System.Guid>, System.Nullable<System.Guid>)

Umbraco.Cms.Core.Models.PublishedContent.PublishedContentType.PublishedContentType(int, string,
    Umbraco.Cms.Core.Models.PublishedContent.PublishedItemType,
    System.Collections.Generic.IEnumerable<string>,
    System.Collections.Generic.IEnumerable<Umbraco.Cms.Core.Models.PublishedContent.PublishedPropertyType>,
    Umbraco.Cms.Core.Models.ContentVariation,
    bool)

Umbraco.Cms.Core.Models.PublishedContent.PublishedContentType.PublishedContentType(int, string,
    Umbraco.Cms.Core.Models.PublishedContent.PublishedItemType, System.Collections.Generic.IEnumerable<string>,
    System.Func<Umbraco.Cms.Core.Models.PublishedContent.IPublishedContentType,
    System.Collections.Generic.IEnumerable<Umbraco.Cms.Core.Models.PublishedContent.IPublishedPropertyType>>,
    Umbraco.Cms.Core.Models.ContentVariation,
    bool)

Umbraco.Cms.Core.Models.Mapping.ContentTypeMapDefinition.ContentTypeMapDefinition(
    Umbraco.Cms.Core.Models.Mapping.CommonMapper,
    Umbraco.Cms.Core.PropertyEditors.PropertyEditorCollection,
    Umbraco.Cms.Core.Services.IDataTypeService,
    Umbraco.Cms.Core.Services.IFileService,
    Umbraco.Cms.Core.Services.IContentTypeService,
    Umbraco.Cms.Core.Services.IMediaTypeService,
    Umbraco.Cms.Core.Services.IMemberTypeService,
    Microsoft.Extensions.Logging.ILoggerFactory,
    Umbraco.Cms.Core.Strings.IShortStringHelper,
    Microsoft.Extensions.Options.IOptions<Umbraco.Cms.Core.Configuration.Models.GlobalSettings>,
    Umbraco.Cms.Core.Hosting.IHostingEnvironment)

Umbraco.Cms.Core.Models.ContentEditing.UserGroupPermissionsSave.Validate(System.ComponentModel.DataAnnotations.ValidationContext)

Umbraco.Cms.Core.Install.InstallSteps.TelemetryIdentifierStep.TelemetryIdentifierStep(
    Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Core.Install.InstallSteps.TelemetryIdentifierStep>,
    Microsoft.Extensions.Options.IOptions<Umbraco.Cms.Core.Configuration.Models.GlobalSettings>,
    Umbraco.Cms.Core.Configuration.IConfigManipulator)

Umbraco.Cms.Core.IO.ViewHelper.ViewHelper(Umbraco.Cms.Core.IO.IFileSystem)

Umbraco.Cms.Core.HealthChecks.Checks.Security.BaseHttpHeaderCheck.BaseHttpHeaderCheck(
    Umbraco.Cms.Core.Hosting.IHostingEnvironment,
    Umbraco.Cms.Core.Services.ILocalizedTextService,
    string,
    string,
    string,
    bool)

Umbraco.Cms.Core.DependencyInjection.UmbracoBuilderExtensions.AddOEmbedProvider<T>(Umbraco.Cms.Core.DependencyInjection.IUmbracoBuilder)

Umbraco.Cms.Core.DependencyInjection.UmbracoBuilderExtensions.OEmbedProviders(Umbraco.Cms.Core.DependencyInjection.IUmbracoBuilder)

Umbraco.Cms.Core.Configuration.Models.RequestHandlerSettings.CharCollection.get
Umbraco.Cms.Core.Configuration.Models.RequestHandlerSettings.CharCollection.set

Umbraco.Cms.Core.Composing.IUserComposer

Umbraco.Cms.Core.Security.BackOfficeUserStore.BackOfficeUserStore(
    Umbraco.Cms.Core.Scoping.ICoreScopeProvider,
    Umbraco.Cms.Core.Services.IUserService,
    Umbraco.Cms.Core.Services.IEntityService,
    Umbraco.Cms.Core.Services.IExternalLoginService,
    Microsoft.Extensions.Options.IOptions<Umbraco.Cms.Core.Configuration.Models.GlobalSettings>,
    Umbraco.Cms.Core.Mapping.IUmbracoMapper,
    Umbraco.Cms.Core.Security.BackOfficeErrorDescriber,
    Umbraco.Cms.Core.Cache.AppCaches)

Umbraco.Cms.Core.Security.MemberUserStore.MemberUserStore(
    Umbraco.Cms.Core.Services.IMemberService,
    Umbraco.Cms.Core.Mapping.IUmbracoMapper,
    Umbraco.Cms.Core.Scoping.ICoreScopeProvider,
    Microsoft.AspNetCore.Identity.IdentityErrorDescriber,
    Umbraco.Cms.Core.PublishedCache.IPublishedSnapshotAccessor,
    Umbraco.Cms.Core.Services.IExternalLoginService)

Umbraco.Cms.Core.Logging.Viewer.ILogViewer.GetLogLevel()

Umbraco.Cms.Core.Logging.Viewer.SerilogLogViewerSourceBase.SerilogLogViewerSourceBase(
    Umbraco.Cms.Core.Logging.Viewer.ILogViewerConfig,
    Serilog.ILogger)

Umbraco.Cms.Core.Logging.Viewer.SerilogLogViewerSourceBase.GetLogLevel()

Umbraco.Cms.Core.Configuration.JsonConfigManipulator.JsonConfigManipulator(Microsoft.Extensions.Configuration.IConfiguration)

Umbraco.Cms.Infrastructure

Umbraco.Cms.Infrastructure.Persistence.Repositories.Implement.MemberRepository.SetLastLogin(string, System.DateTime)

Umbraco.Cms.Infrastructure.Packaging.PackageMigrationBase.PackageMigrationBase(
    Umbraco.Cms.Core.Services.IPackagingService,
    Umbraco.Cms.Core.Services.IMediaService,
    Umbraco.Cms.Core.IO.MediaFileManager,
    Umbraco.Cms.Core.PropertyEditors.MediaUrlGeneratorCollection,
    Umbraco.Cms.Core.Strings.IShortStringHelper,
    Umbraco.Cms.Core.Services.IContentTypeBaseServiceProvider,
    Umbraco.Cms.Infrastructure.Migrations.IMigrationContext)

Umbraco.Cms.Infrastructure.Migrations.Install.DatabaseSchemaCreator.DatabaseSchemaCreator(
    Umbraco.Cms.Infrastructure.Persistence.IUmbracoDatabase?,
    Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Infrastructure.Migrations.Install.DatabaseSchemaCreator>,
    Microsoft.Extensions.Logging.ILoggerFactory,
    Umbraco.Cms.Core.Configuration.IUmbracoVersion,
    Umbraco.Cms.Core.Events.IEventAggregator)

Umbraco.Cms.Infrastructure.Migrations.Install.DatabaseSchemaCreatorFactory.DatabaseSchemaCreatorFactory(
    Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Infrastructure.Migrations.Install.DatabaseSchemaCreator>,
    Microsoft.Extensions.Logging.ILoggerFactory,
    Umbraco.Cms.Core.Configuration.IUmbracoVersion,
    Umbraco.Cms.Core.Events.IEventAggregator)

Umbraco.Cms.Infrastructure.HostedServices.RecurringHostedServiceBase.RecurringHostedServiceBase(
    System.TimeSpan,
    System.TimeSpan)

Umbraco.Cms.Infrastructure.HostedServices.ReportSiteTask.ReportSiteTask(
    Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Infrastructure.HostedServices.ReportSiteTask>,
    Umbraco.Cms.Core.Configuration.IUmbracoVersion,
    Microsoft.Extensions.Options.IOptions<Umbraco.Cms.Core.Configuration.Models.GlobalSettings>)

Umbraco.Cms.Web

Umbraco.Cms.Web.Common.Security.ConfigureIISServerOptions

Umbraco.Cms.Web.Common.RuntimeMinification.SmidgeRuntimeMinifier.Reset()

Umbraco.Cms.Web.Common.Middleware.UmbracoRequestMiddleware.UmbracoRequestMiddleware(
    Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Web.Common.Middleware.UmbracoRequestMiddleware>,
    Umbraco.Cms.Core.Web.IUmbracoContextFactory,
    Umbraco.Cms.Core.Cache.IRequestCache,
    Umbraco.Cms.Core.Events.IEventAggregator,
    Umbraco.Cms.Core.Logging.IProfiler,
    Umbraco.Cms.Core.Hosting.IHostingEnvironment,
    Umbraco.Cms.Core.Routing.UmbracoRequestPaths,
    Umbraco.Cms.Infrastructure.WebAssets.BackOfficeWebAssets,
    Microsoft.Extensions.Options.IOptionsMonitor<Smidge.Options.SmidgeOptions>,
    Umbraco.Cms.Core.Services.IRuntimeState,
    Umbraco.Cms.Core.Models.PublishedContent.IVariationContextAccessor,
    Umbraco.Cms.Core.PublishedCache.IDefaultCultureAccessor)

Umbraco.Cms.Web.Website.Controllers.UmbLoginController.UmbLoginController(
    Umbraco.Cms.Core.Web.IUmbracoContextAccessor,
    Umbraco.Cms.Infrastructure.Persistence.IUmbracoDatabaseFactory,
    Umbraco.Cms.Core.Services.ServiceContext,
    Umbraco.Cms.Core.Cache.AppCaches,
    Umbraco.Cms.Core.Logging.IProfilingLogger,
    Umbraco.Cms.Core.Routing.IPublishedUrlProvider,
    Umbraco.Cms.Web.Common.Security.IMemberSignInManager)

Umbraco.Cms.Web.BackOffice.Trees.MemberTypeAndGroupTreeControllerBase.MemberTypeAndGroupTreeControllerBase(
    Umbraco.Cms.Core.Services.ILocalizedTextService,
    Umbraco.Cms.Core.UmbracoApiControllerTypeCollection,
    Umbraco.Cms.Core.Trees.IMenuItemCollectionFactory,
    Umbraco.Cms.Core.Events.IEventAggregator)

Umbraco.Cms.Web.BackOffice.Controllers.CurrentUserController.CurrentUserController(
    Umbraco.Cms.Core.IO.MediaFileManager,
    Microsoft.Extensions.Options.IOptions<Umbraco.Cms.Core.Configuration.Models.ContentSettings>,
    Umbraco.Cms.Core.Hosting.IHostingEnvironment,
    Umbraco.Cms.Core.Media.IImageUrlGenerator,
    Umbraco.Cms.Core.Security.IBackOfficeSecurityAccessor,
    Umbraco.Cms.Core.Services.IUserService,
    Umbraco.Cms.Core.Mapping.IUmbracoMapper,
    Umbraco.Cms.Core.Security.IBackOfficeUserManager,
    Microsoft.Extensions.Logging.ILoggerFactory,
    Umbraco.Cms.Core.Services.ILocalizedTextService,
    Umbraco.Cms.Core.Cache.AppCaches,
    Umbraco.Cms.Core.Strings.IShortStringHelper,
    Umbraco.Cms.Web.Common.Security.IPasswordChanger<Umbraco.Cms.Core.Security.BackOfficeIdentityUser>)

Umbraco.Cms.Web.BackOffice.Controllers.EntityController.GetUrlsByUdis(Umbraco.Cms.Core.Udi[], string?)

Umbraco.Cms.Web.BackOffice.Controllers.HelpController.HelpController(Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Web.BackOffice.Controllers.HelpController>)

Umbraco.Cms.Web.BackOffice.Controllers.LanguageController.LanguageController(
    Umbraco.Cms.Core.Services.ILocalizationService,
    Umbraco.Cms.Core.Mapping.IUmbracoMapper,
    Microsoft.Extensions.Options.IOptionsSnapshot<Umbraco.Cms.Core.Configuration.Models.GlobalSettings>)

Umbraco.Cms.Web.BackOffice.Controllers.LogViewerController.LogViewerController(Umbraco.Cms.Core.Logging.Viewer.ILogViewer)
Umbraco.Cms.Web.BackOffice.Controllers.LogViewerController.GetLogLevel()

Umbraco.Cms.Web.BackOffice.Controllers.MediaController.GetPagedReferences(int, string, int, int)

Umbraco.Cms.Web.BackOffice.Controllers.MemberTypeController.GetAllTypes()

Umbraco.Cms.Web.BackOffice.Controllers.TemplateController.TemplateController(
    Umbraco.Cms.Core.Services.IFileService,
    Umbraco.Cms.Core.Mapping.IUmbracoMapper,
    Umbraco.Cms.Core.Strings.IShortStringHelper)

Umbraco.Cms.Tests

Umbraco.Cms.Tests.Common.Testing.TestOptionAttributeBase.ScanAssemblies

Code moved to new assemblies and namespaces

The following have been moved to new assemblies and their namespaces have been updated accordingly.

Umbraco.Extensions

Umbraco.Extensions.NPocoDatabaseExtensions.ConfigureNPocoBulkExtensions()

Umbraco.Extensions.UmbracoBuilderExtensions.AddUmbracoImageSharp(Umbraco.Cms.Core.DependencyInjection.IUmbracoBuilder)

Umbraco.Cms.Web

Umbraco.Cms.Web.Common.Media.ImageSharpImageUrlGenerator

Umbraco.Cms.Web.Common.ImageProcessors.CropWebProcessor

Umbraco.Cms.Web.Common.DependencyInjection.ConfigureImageSharpMiddlewareOptions
Umbraco.Cms.Web.Common.DependencyInjection.ConfigurePhysicalFileSystemCacheOptions

Umbraco.Cms.Infrastructure

Umbraco.Cms.Infrastructure.Persistence.LocalDb
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.RetryPolicyFactory
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.ThrottlingMode
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.ThrottlingType
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.ThrottledResourceType
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.ThrottlingCondition
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.Strategies.NetworkConnectivityErrorDetectionStrategy
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.Strategies.SqlAzureTransientErrorDetectionStrategy

New interface methods

A few interfaces have been merged, adding new members to the original interfaces.

Umbraco.Cms.Core

Umbraco.Cms.Core.Services.IMacroService.GetAll(params string[])

Umbraco.Cms.Core.Persistence.Repositories.IMacroRepository.GetByAlias(string)
Umbraco.Cms.Core.Persistence.Repositories.IMacroRepository.GetAllByAlias(string[])

Umbraco.Cms.Core.Services.ITwoFactorLoginService.DisableWithCodeAsync(string, System.Guid, string)
Umbraco.Cms.Core.Services.ITwoFactorLoginService.ValidateAndSaveAsync(string, System.Guid, string, string)

Umbraco.Cms.Core.Models.IContentType.HistoryCleanup

Umbraco.Cms.Core.Media.IImageDimensionExtractor.SupportedImageFileTypes

No-Operation methods removed

A method not doing anything for the last couple of major releases have been removed.

Umbraco.Cms.Core

Umbraco.Cms.Core.Services.IMembershipMemberService<T>.SetLastLogin(string, System.DateTime)

Changes due to models made immutable

A single model have been made immutable, so the default constructor and the setters are not available anymore.

Umbraco.Cms.Infrastructure

Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.ContentData()
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.Name.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.UrlSegment.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.VersionId.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.VersionDate.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.WriterId.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.TemplateId.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.Published.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.Properties.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.CultureInfos.set

Classes that does not inherit from base type anymore

The following classes now directly inherit from OEmbedProviderBase instead of EmbedProviderBase.

Umbraco.Cms.Core

Umbraco.Cms.Core.Media.EmbedProviders.DailyMotion
Umbraco.Cms.Core.Media.EmbedProviders.Flickr
Umbraco.Cms.Core.Media.EmbedProviders.GettyImages
Umbraco.Cms.Core.Media.EmbedProviders.Giphy
Umbraco.Cms.Core.Media.EmbedProviders.Hulu
Umbraco.Cms.Core.Media.EmbedProviders.Issuu
Umbraco.Cms.Core.Media.EmbedProviders.Kickstarter
Umbraco.Cms.Core.Media.EmbedProviders.Slideshare
Umbraco.Cms.Core.Media.EmbedProviders.Soundcloud
Umbraco.Cms.Core.Media.EmbedProviders.Ted
Umbraco.Cms.Core.Media.EmbedProviders.Twitter
Umbraco.Cms.Core.Media.EmbedProviders.Vimeo
Umbraco.Cms.Core.Media.EmbedProviders.YouTube

Umbraco 10

Update 'diff' from 3.5.0 to 5.0.0

The diff library used in the Backoffice client has been updated and introduces a breaking change since the exposed global object has been renamed from JsDiff to Diff.

Content Schedule performance

Removes mutable ContentSchedule property from IContent/Content to read/write content schedules.

Use IContentService.GetContentScheduleByContentId && IContentService.PersistContentSchedule or the optional contentSchedule parameter on IContentService.Save instead.

Removed redundant event handling code

Removed public methods: PublishedSnapshotServiceEventHandler.Dispose, PublishedSnapshotServiceEventHandler.Dispose(bool), and .PublishedSnapshotServiceEventHandler.Initialize.
Removed public ctor.

Scope provider cleanup

Some public classes in the Cms.Core.Services namespace have moved assembly from Umbraco.Cms.Infrastructure to Umbraco.Cms.Core.
These same public classes have changed namespace from Umbraco.Cms.Core.Services.Implement to Umbraco.Cms.Core.Services.

Update to NPoco5

NPoco types and interfaces are part of our public interface which means that this upgrade imposes breaking changes.

SQLite support

Removed support for Microsoft SQL Server Compact (SQL CE).
Removed ReadLock and WriteLock methods from ISqlSyntaxProvider interface. Use IDistributedLockingMechanism (or IScope which delegates to IDistributedLockingMechanism) instead.
Constants for SQL Server provider name moved+consolidated from Core.Constants.DatabaseProviders and Core.Constants.-DbProviderNames to Umbraco.Cms.Persistence.SqlServer.Constants
Some SQL Server related services moved from the Umbraco.Infrastructure project to the new Umbraco.Cms.Persistence.
SqlServer project with altered namespaces e.g. SqlServerSyntaxProvider, SqlServerBulkSqlInsertProvider, SqlServerDatabaseCreator.

Added the following methods/properties to ISqlSyntaxProvider. These must be implemented in any downstream implementation e.g:

ISqlSyntaxProvider.HandleCreateTable(IDatabase,TableDefinition,Boolean)
ISqlSyntaxProvider.GetFieldNameForUpdate()
ISqlSyntaxProvider.GetColumn(DatabaseType,String,String,String,String,Boolean)
ISqlSyntaxProvider.InsertForUpdateHint(Sql)
ISqlSyntaxProvider.AppendForUpdateHint(Sql)
ISqlSyntaxProvider.LeftJoinWithNestedJoin(Sql,Func<Sql,Sql>,String)

Update to ImageSharp v2

Update dependency versions:

SixLabors.ImageSharp from 1.0.4 to 2.1.1
SixLabors.ImageSharp.Web from 1.0.5 to 2.0.0

Renamed the CachedNameLength property to CacheHashLength on ImagingCacheSettings.

Moved ImageSharpImageUrlGenerator from project Umbraco.Infrastructure to Umbraco.Web.Common and updated the corresponding namespace and DI registration (from AddCoreInitialServices() to AddUmbracoImageSharp());

Moved ImageSharp configuration from the AddUmbracoImageSharp() extension method into separate IConfigureOptions<> implementations:

The middleware is configured in ConfigureImageSharpMiddlewareOptions (which also replaces ImageSharpConfigurationOptions that previously only set the default ImageSharp configuration);
The default physical cache is configured in ConfigurePhysicalFileSystemCacheOptions.

Migrate Member properties to columns on the Member table

This is breaking because it is no longer possible to access the properties listed below through the IMember.Properties collection. You must now access them through their specific properties that is IMember.IsLockedOut.

umbracoMemberFailedPasswordAttempts
umbracoMemberApproved
umbracoMemberLockedOut
umbracoMemberLastLockoutDate
umbracoMemberLastLogin
umbracoMemberLastPasswordChangeDate

Additionally, when previously you resolved a Member as published content, all the default properties would be there twice. For instance, IsLockedOut would be there both as a property with the alias umbracoMemberLockedOut and with the alias IsLockedOut. Now it'll only be there once, with the alias being the name of the property, so IsLockedOut in this instance.

Lastly the nullable dates on a user, i.e. LastLoginLate will now be null instead of DateTime.MinValue when getting a user with the UserService.

Update examine to version 3

Examine 3 breaking changes:

ValueSet immutable.
ValueSetValidationResult is renamed to ValueSetValidationStatus and ValueSetValidationResult is now a type.

Async support for content finders

bool TryFindContent(IPublishedRequestBuilder request);

Has changed to:

Task<bool> TryFindContent(IPublishedRequestBuilder request);

Improve redirect Content finder scalability

Added more methods to IRedirectUrlRepository and IRedirectUrlService.cs.

Fix Block List settings exception and optimize PVCs

Added a new method on IPublishedModelFactory: Type GetModelType(string? alias);
The generic types of a BlockListItem<TContent, TSettings>instance in theBlockListModelreturned byBlockListPropertyValueConverteris now determined by calling this new method, which can be different and cause aModelBindingException` in your views.

Async tree search

IEnumerable<SearchResultEntity?> Search(string query, int pageSize, long pageIndex, out long totalFound, string? searchFrom 
= null)

Has changed to:

Task<EntitySearchResults> SearchAsync(string query, int pageSize, long pageIndex, string? searchFrom = null);

Moved StackQueue to correct namespace

StackQueue has been moved from Umbraco.Core.Collections to the Umbraco.Cms.Core.Collections namespace.

Globalsetting SqlWriteLockTimeOut has been removed

This setting has been superseded by DistributedLockingWriteLockDefaultTimeout.

GlobalSetting UmbracoPath cannot be configured

It is no longer possible to rename the /Umbraco folder path using configuration. The property still exists but is hardcoded to /Umbraco and will be removed in Umbraco 12, planned for release in June 2023.

Release notes

You can find a list of all the released Umbraco versions on Our Umbraco website. When you visit Our Umbraco website, click on the version number to view the changes made in that specific version.

Find your upgrade path

Are you looking to upgrade an Umbraco Cloud project from 9 to 10? Follow the guide made for Upgrading your project from Umbraco 9 to 10 instead, as it requires a few steps specific to Umbraco Cloud.

10.latest to the latest Umbraco version

It might be necessary to delete all of the bin and obj directories in each of the projects of your solution. It has been observed that Visual Studio's "Clean Solution" option is sometimes not enough.

You can upgrade from Umbraco 10 to the latest version directly. If you choose to skip upgrading to versions 11 and 12, you will no longer receive warning messages for obsolete features. However, if you do skip these versions, any breaking changes will no longer compile.

It is recommended to upgrade to the closest Long-term Support (LTS) major version before upgrading to the latest version. For Umbraco 10, the closest long-term support version is Umbraco 13 so a direct upgrade is possible.

9.latest to 10

Important: .NET version 6.0.5 is the minimum required version for Umbraco 10 to be able to run. You can check with dotnet --list-sdks what your latest installed Software Development Kit (SDK) version is. The latest SDK version 6.0.301 includes .NET 6.0.6, while SDK version 6.0.300 includes .NET 6.0.5.

Watch the 'Upgrading from Umbraco 9 to Umbraco 10 video tutorial' for a complete walk-through of all the steps.

The upgrade path between Umbraco 9 and Umbraco 10 can be done directly by upgrading your project using NuGet. You will need to ensure the packages you are using are available in Umbraco 10.

SQL CE is no longer a supported database engine

There is no official migration path from SQL CE to another database engine.

The following options may suit your needs:

Follow a community guide to migrate from a SQL CE database to SQL Server, like the article by Jan Reilink
Setup a new database for v10 and use uSync to transfer document types and content across.
Setup a new database for v10 and use a premium tool such as redgate SQL Data Compare to copy database contents across.
Setup a new database for v10 and use a premium tool such as Umbraco Deploy to transfer document types and content across.

Steps to upgrade using Visual Studio

It's recommended that you upgrade the site offline, and test the upgrade fully before deploying it to the production environment.

Stop your site in IIS to prevent any changes being made to the database or filesystem while you are upgrading.
Open your Umbraco 9 project in Visual Studio.
Right-click on the project name in the Solution Explorer and select Properties.
Select .NET 6.0 from the Target Framework drop-down.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
Go to the Installed tab in the NuGet Package manager.
Choose Umbraco.Cms.
Select 10.0.0 from the Version drop-down and click Install to upgrade your project to version 10.
Update Program.cs to the following:

public class Program
{
    public static void Main(string[] args)
        => CreateHostBuilder(args)
            .Build()
            .Run();

    // The calls to `ConfigureUmbracoDefaults` and `webBuilder.UseStaticWebAssets()` are new.
    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureUmbracoDefaults()
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStaticWebAssets();
                webBuilder.UseStartup<Startup>();
            });
}

Remove the following files and folders:
- /wwwroot/umbraco
- /umbraco/PartialViewMacros
- /umbraco/UmbracoBackOffice
- /umbraco/UmbracoInstall
- /umbraco/UmbracoWebsite
- /umbraco/config/lang
- /umbraco/config/appsettings-schema.json
If using Umbraco Forms, update your files and folders according to the Upgrading - version specific for version 10 article.
Restart your site in IIS, build and run your project to finish the installation of Umbraco 10.

To re-enable the appsettings IntelliSense, you must update your schema reference in the appsettings.json file and any other appsettings.{Environment}.json files from:

"$schema": "./umbraco/config/appsettings-schema.json",

To:

"$schema": "./appsettings-schema.json",

To upgrade to Umbraco 10, your database needs to be at least on Umbraco 8.18.

Upgrade of any publicly hosted environment

When the upgrade is completed and tested, and prior to deploying to any publicly accessible environment, you should consider the following:

Ensure you have backups for both the database and the file system.
Stop the site so it is not accessible during the upgrade process.
Delete the relevant folders from the filesystem prior to deploying:
- /wwwroot/umbraco
- /umbraco/PartialViewMacros
- /umbraco/UmbracoBackOffice
- /umbraco/UmbracoInstall
- /umbraco/UmbracoWebsite
- /umbraco/config/lang
- /umbraco/config/appsettings-schema.json
If you are using Umbraco Forms, update your files and folders according to the Upgrading - version specific for version 10 article.
Deploy the site how you normally would to your public facing environment.
Start the site. At this point it will launch and upgrade the database, after which the site should become accessible and your upgrade is complete.
Check the logs for any errors which may have occurred during the upgrade process.

8.latest to 9

There is no direct upgrade path from Umbraco 8 to Umbraco 9. It is however possible to migrate from Umbraco 8 sites to Umbraco 9 sites.

You can reuse your content by restoring your Umbraco 8 database into a new database used for an Umbraco 9 site.

You need to ensure the packages you are using are available in Umbraco 9, and you will need to reimplement your custom code and templates.

The direct upgrade path is not possible because the codebase has been fundamentally updated in Umbraco 9. The underlying web framework has been updated from ASP.NET to ASP.NET Core.

It is not possible to take this step while maintaining full compatibility with Umbraco 8.

8.0.0 to 8.1.0

There are a few breaking changes from 8.0.x to 8.1.0. Make sure to check the full list.

IPublishedContent breaking changes in 8.1.0

Due to the changes in IPublishedContent there are a few steps you will need to take, to make sure that your site works.

The IPublishedContent interface is central to Umbraco, as it represents published content and media items at the rendering layer level. This could be in controllers or views. In other words, it is the interface that is used everywhere when building sites.

The introduction of multilingual support in version 8 required changes to the interface. For instance, a property value could be obtained with GetPropertyValue(alias) in version 7. Version 8 requires a new parameter for culture, and the call thus became Value(alias, culture).

In the excitement of the version 8 release, we assumed that IPublishedContent was "done". By our tests, everything was looking good. However, feedback from early testers showed that the interface was in some places odd or inconsistent or had issues.

Fixing the bugs is a requirement. Some of the required bug fixes could not be achieved without introducing some breaking changes.

At that point, we decided to give IPublishedContent some love. We fixed the bugs and made it clean, friendly, discoverable, and predictable for the entire life of version 8.

Breaking changes to such a central interface is not something we take lightly. Even though they do not impact the "concepts" nor require heavy refactoring, they may demand an amount of small fixes here and there.

The general idea underlying these changes is that:

The proper way to retrieve "something" from an IPublishedContent instance is always through a method, for example: Children(). And, when that method can be multilingual, the method accepts a culture parameter, which can be left null to get the "current" culture value.
To reduce the amount of breaking changes, and to simplify things for non-multilingual sites, existing properties such as document.Name and document.Children (and others) still exist, and return the value for the current culture. In other words, these properties are now implemented as document.Name => document.Name() or document.Children => document.Children().

The rest of this document presents each change in details.

More interfaces

It was possible to mock and test the IPublishedContent interface in version 7. It has been improved in version 8, but it still relies on concrete PublishedContentType and PublishedPropertyType classes to represent the content types, which complicates things.

In version 8.1, these two classes are abstracted as IPublishedContentType and IPublishedPropertyType, thus making IPublishedContent easier to mock and test.

CHANGE: This impacts every method accepting or returning a content type. For instance, the signature of most IPropertyValueConverter methods changes. References to PublishedContentType must be replaced with references to IPublishedContentType.

The following IPublishedContent members change:

Name

The document.Name property is complemented by the document.Name(string culture = null) extension method. The property returns the name for the current culture. The document.GetCulture(...).Name syntax is removed.

CHANGE: Calls to document.GetCulture(culture).Name must be replaced with document.Name(culture).

UrlSegment

The document.UrlSegment property is complemented by the document.UrlSegment(string culture = null) extension method. The property returns the Url segment for the current culture. The document.GetCulture(...).UrlSegment syntax is removed.

CHANGE: Calls to document.GetCulture(culture).UrlSegment must be replaced with document.UrlSegment(culture).

Culture

The document.GetCulture() method is removed. The proper way to get a culture date is document.CultureDate(string culture = null). The document.Cultures property now returns the invariant culture, for invariant documents.

CHANGE: Calls to document.GetCulture(culture).Date must be replaced with document.CultureDate(culture). Calls to document.Cultures must take into account the invariant culture.

Children

The document.Children property is complemented by the document.Children(string culture = null) extension method which, when a culture is specified always return children available for the specified culture. The property returns the children available for the current culture.

A new document.ChildrenForAllCultures property is introduced, which returns all children, regardless of whether they are available for a culture or not.

CHANGE: Calls to document.Children may have to be replaced by document.ChildrenForAllCultures depending on if the 8.0.x usage of this was relying on it returning unfiltered/all children regardless of the current routed culture.

Url

The document.Url property is complemented by the document.Url(string culture = null, UrlMode mode = UrlMode.Auto) extension method. The document.GetUrl(...) and document.UrlAbsolute() methods are removed. The UrlProviderMode enumeration is renamed UrlMode.

CHANGE: Calls to document.GetUrl(...) must be replaced with document.Url(...). Calls to document.UrlAbsolute() must be replaced with document.Url(mode: UrlMode.Absolute).

UmbracoContext

Due to the UrlProviderMode enumeration being renamed UrlMode, the signature of some overloads of the Url(...) method has changed. Methods that do not have a mode parameter remain unchanged.

CHANGE: Code such as context.Url(1234, UrlProviderMode.Absolute) must become context.Url(1234, UrlMode.Absolute).

The UmbracoContext class gives access to the rendering layer, which is more than a "cache". To reflect this, its ContentCache and MediaCache properties are renamed Content and Media. However, the old properties remain as obsolete properties.

CHANGE: None required in 8.1, but code such as context.ContentCache.GetById(1234) should eventually be converted to context.Content.GetById(1234) as the obsolete properties may be removed in a further release.

GetCulture

Version 7 had a document.GetCulture() method that was deriving a culture from domains configured in the tree. Somehow, that method was lost during version 8 development (issue #5269).

Because that method is useful, especially when building traditional, non-multilingual sites, it has been re-introduced in version 8.1 as document.GetCultureFromDomains().

CHANGE: None.

DomainHelper

DomainHelper has been replaced with a static DomainUtilities class.

CHANGE: It is rare that DomainHelper is used in code since it only contains one public method but if developers are using this, it can no longer be injected since it's now a static class called DomainUtilities.

Models Builder

If you're using ModelsBuilder in dll mode you need to delete the dlls before upgrading. Otherwise, they're going to be wrong and cause your whole site to throw errors.

If you're using ModelsBuilder in AppData mode and you have your generated models in your solution you need to update them after upgrading. PublishedContentType will need to be replaced with IPublishedContentType. If you have an implementation of the PropertyValueConverter class, you need to replace all references to PublishedPropertyType with IPublishedPropertyType within that class. Only after you do that will your solution build again.

AutoMapper

Umbraco 8.1 replaces AutoMapper with UmbracoMapper. This in itself will not break anything on your site. If you have used AutoMapper in your own code you will have to either include the package yourself or switch your implementation to use UmbracoMapper.

Follow the upgrade guide for Umbraco 8 to complete the upgrade

7.latest to 8.0.0

There is no direct upgrade path from Umbraco 7 to Umbraco 8. It is however possible to migrate content from Umbraco 7 sites to Umbraco 8 sites. We have added content migrations in Umbraco 8.1.0 enabling you to migrate your content from Umbraco 7 to Umbraco 8.

It is not possible to upgrade an Umbraco 7 site to Umbraco 8 because the codebase has been fundamentally updated in Umbraco 8. A lot of outdated code and technology has been removed and instead new, faster, and more secure technology has been implemented.

In Umbraco 8 we have added improvements and updated dependencies. We have also done a thorough clean-up to make it simpler for you to work with and extend your Umbraco project.

Migrate your content to Umbraco 8

7.6.3 to 7.7.0

Version 7.7.0 introduces User Groups, better user management, and security facilities. This means that anything to do with "User Types" no longer exists including APIs that work with User Types. If your code or any package's code refers to "User Type" APIs, you need to make changes to your code. In many cases, we've added backward compatibility for these scenarios and obsoleted APIs that should no longer be used.

We are now by default using the e-mail address and not the username for the credentials. When trying to login to the backoffice you need to use the e-mail address as opposed to the username. If you do an upgrade from an older version and would like to keep using the username, change the <usernameIsEmail>true</usernameIsEmail> setting to false.

For a full list of breaking changes see: the list on the issue tracker

Version 7.7.2 no longer ships with the CookComputing.XmlRpcV2 assembly. If you reference this assembly or have a package that requires this assembly, you need to copy it back into your website.

This version also ships with far fewer client files that were only relevant for older versions of Umbraco (i.e. < 7.0.0). There might be some packages that were referencing these old client files. If you see missing image references you may need to contact the vendor of the package in question to update their references.

Follow the upgrade guide for Umbraco 7 to complete the upgrade.

7.6.0 to 7.6.3

In short:

In Umbraco version 7.6.2 we made a mistake in the Property Value Converts (PVCs). This was corrected 2 days later in version 7.6.3. If you were having problems with querying the following Data Types on the frontend, make sure to upgrade to 7.6.3:

Multi Node Tree Picker
Related Links
Member Picker

Depending on whether you tried to fix the problem with those, you will need to fix them after you upgrade to 7.6.3.

Property Value Converters (PVC)

Umbraco stores data for Data Types in different ways. For a lot of pickers it will store 1072 or 1083,1283. These numbers refer to the identifier of the item in Umbraco. In the past, when building your templates, you would manually have to take that value and find the content item it belongs to. Then you would be able to get the data you wanted from there. An example of that is shown below:

@{
    IPublishedContent contactPage;
    var contactPageId = Model.Content.GetPropertyValue<int>("contactPagePicker");
    if (contactPageId > 0)
    {
        contactPage = Umbraco.TypedContent(contactPageId);
    }
}

<p>
  <a href="@contactPage.Url">@contactPage.Name</a>
</p>

In Umbraco 7.6.0, this is what you would do instead:

<p>
    <a href="@Model.Content.ContactPagePicker.Url">@Model.ContactPagePicker.Name</a>
</p>

This is possible using Models Builder and through the inclusion of core property value converters, a package by community member Jeavon Leopold.

To not break everybody's sites (the results of queries are different when PVCs are enabled), we disabled these PVCs by default.

Umbraco 7.6.0 also came with new pickers that store their data as a UDI (Umbraco Identifier). We wanted to simplify the use of these new pickers and by default we wanted PVC's to always be enabled for those pickers.

We noticed that some new pickers also got their PVC's disabled when the configuration setting was set to false (<EnablePropertyValueConverters>false</EnablePropertyValueConverters>).

To make everything consistent, we made sure that the UDI pickers would always use PVC's in 7.6.2, this however reversed the behavior. So when PVC's were enabled, the property would not be converted and when PVC's were disabled, the property would be converted after all. This is the exact opposite behavior of 7.6.2.

So we have fixed this now in 7.6.3.

This issue only affects:

Multi Node Tree Picker
Related Links
Member Picker

Have you already upgraded to 7.6.2 and fixed queries for those three Data Types? Then you have to do that again in version 7.6.3.

Follow the upgrade guide for Umbraco 7 to complete the upgrade.

7.4.0 to 7.6.0

Find a list of all the breaking changes below and a list of the items is also available on the tracker

The three most important things to note are:

In web.config do not change useLegacyEncoding to false if it is currently set to true - changing the password encoding will cause you not being able to log in any more.
In umbracoSettings.config leave EnablePropertyValueConverters set to false - this will help your existing content queries to still work.
In tinyMceConfig.config make sure to remove <plugin loadOnFrontend="true">umbracolink</plugin> so that the rich text editor works as it should.

Breaking Changes

Dependencies

UrlRewriting.Net (U4-9004)

UrlRewriting was old, leaking memory, and slowing down website startup when dealing with more than a few rules. It's entirely replaced by the IIS Url Rewrite extension.

Json.Net (U4-9499)

Json.Net has been updated to version 10.0.0 to benefit from improvements in features, fixes, and performances (see release notes). This might be a breaking change for people relying on one of the changed functionality.

Log4net (U4-1324)

Umbraco has used a custom build of an old (1.2.11) version of log4net that supported Medium Trust. However, Umbraco itself does not support Medium Trust anymore, and therefore log4net has been upgraded to the standard, latest build of log4net 2.0.8.

ImageProcessor (U4-8963)

An optional parameter has been added to the GetCropUrl method in order to support the background color parameter. This breaks the method signature and therefore might require a recompile of user's code.

HtmlAgilityPack (U4-9655)

The HtmlAgilityPack has been upgraded to version 1.4.9.5. The Umbraco upgrade process should take care of setting up the binding redirects appropriately.

Core

Membership Provider Encoding (U4-6566)

The Membership Provider useLegacyEncoding setting is now false by default, as the legacy password encoding has weaknesses.

This change only impacts new installs (no change for upgrades).

Property Value Converters (U4-7318)

A large amount of property value converters contributed by the community have been merged in and are now the default value converters. These converters change the object types returned by GetPropertyValue for more convenient types.

Instead of returning comma-separated string values like it did before, the SliderValueConverter now returns a decimal or a Range<decimal> value that can be used directly in views.

This change only impacts new installs (no change for upgrades).

The new property value converters are controlled by an umbracoSettings.config setting. In the section settings/content, setting EnablePropertyValueConverters needs to be present and true to activate them.

Database (U4-9201)

Umbraco has been using a PetaPoco-managed UmbracoDatabase instance since version 7 came out. We realized that some of our legacy code still bypassed that mechanism and used parallel, out-of-band database connections, causing issues with transactions.

The legacy code has been refactored to rely on the UmbracoDatabase instance. However, because that database is disposed of during EndRequest, the code that ran after it has been disposed may not work anymore. This should then be updated to use either an HttpModule event that occurs before EndRequest or the new UmbracoModule.EndRequest event.

More details are available on issue 146 on the 301 Redirect Tracker GitHub issue tracker.

Scopes (U4-9406)

Version 7.6 introduces the notion of scopes, which allow for wrapping multiple service-level operations in one single transaction. The scopes API is partially public. Scopes are not meant for public use at this stage and we need a few more releases to ensure that the APIs are stable.

Scopes should not change how Umbraco functions.

Introducing scopes means that some public APIs signatures are changing. Most of these changes target internal and/or non-breaking APIs (as per our guidelines). This should therefore have no impact on sites but may break unit tests.

Property Editors storing UDI instead of ID (U4-9310)

The property editors for pickers for content, media, members, and related links have been updated to store UDI instead of the node ID. Pickers in sites being upgraded have been marked as obsolete but will continue to work as they always did.

New sites will have the obsolete pickers filtered out from the list of available property editors, but they can be enabled by a configuration flag.

Rich Text Editor (RTE) Images attributes (U4-6228, U4-6595)

For a long time, we had a rel attribute on an <img> tag when inserted into the RTE. This is invalid HTML markup. We worked around this by stripping this attribute using a Property Editor Value converter. Some developers relied on this attribute so we didn't change it to a "data-id" attribute which would have been valid. In 7.6 we are not storing integer IDs in these attributes. Instead of storing UDI values so with this change we no longer use rel or data-id and instead there will be a "data-udi" attribute. This change should affect only a small amount of people that were previously relying on the values from the "rel" attribute.

Others

We are shipping with SignalR in the core at version 2.2.1. If you already have SignalR installed into your app and are using an older version there may be conflicts.

The creation and editing of WebForms templates will no longer be supported as for version 7.6.0.

Upgrading via NuGet

This is an important one and there was no perfect solution to this. We have removed the UrlRewriting dependency and no longer ship with it. However, if you are using it we didn't want to have NuGet delete all of your rewrites. The good news is that if you are using it, the NuGet upgrade will not delete your rewrite file and everything should continue to work.

However, if you are not using it, you will get an error after upgrading. Here's how to fix it:

Since you aren't using UrlRewriting you will have probably never edited the UrlRewriting file. In this case, NuGet will detect that and remove it. However you will need to manually remove these UrlRewriting references from your web.config:

<section name="urlrewritingnet" restartOnExternalChanges="true" requirePermission="false" type="UrlRewritingNet.Configuration.UrlRewriteSection, UrlRewritingNet.UrlRewriter" />

and

<urlrewritingnet configSource="config\UrlRewriting.config" />

Remove the following httpModules from your web.config:

<system.web>
<httpModules>
    <add name="UrlRewriteModule" type="UrlRewritingNet.Web.UrlRewriteModule, UrlRewritingNet.UrlRewriter"/>
    ...
</httpModules>
<system.web>

and

<system.webServer>
    <modules>
    <remove name="UrlRewriteModule"/>
    <add name="UrlRewriteModule" type="UrlRewritingNet.Web.UrlRewriteModule, UrlRewritingNet.UrlRewriter"/>
    ...
    </modules>
</system.webServer>

Forms

Umbraco Forms 6.0.0 has been released to be compatible with Umbraco 7.6. It is a new major version release of Forms primarily due to the strict dependency on 7.6+. If you are using Forms, you will need to update it to version 6.0.0

There are important Forms upgrade documentation that you will need to read..

Courier

Umbraco Courier 3.1.0 has been released to be compatible with Umbraco 7.6. If you are using Courier, you will need to update it to version 3.1.0.

Follow the upgrade guide for Umbraco 7 to complete the upgrade

7.3.0 to 7.4.0

For manual upgrades:

Copy the new folder ~/App_Plugins/ModelsBuilder into the site
Do not forget to merge ~/Config/trees.config and ~/Config/Dashboard.config - they contain new and updated entries that are required to be there
- If you forget trees.config you will either not be able to browse the Developer section or you will be logged out immediately when trying to go to the developer section
You may experience an error saying Invalid object name 'umbracoUser' - this can be fixed by clearing your cookies on localhost

Follow the upgrade guide for Umbraco 7 to complete the upgrade.

7.2.0 to 7.3.0

Make sure to manually clear your cookies after updating all the files, otherwise you might an error relating to Umbraco.Core.Security.UmbracoBackOfficeIdentity.AddUserDataClaims(). The error looks like: Value cannot be null. Parameter name: value.

NuGet will do the following for you. If you're upgrading manually make sure to also:

Delete bin/Microsoft.Web.Helpers.dll
Delete bin/Microsoft.Web.Mvc.FixedDisplayModes.dll
Delete bin/System.Net.Http.dll
Delete bin/System.Net.Http.*.dll (all dll files starting with System.Net.Http) except for System.Net.Http.Formatting.dll
Delete bin/umbraco.XmlSerializers.dll
Add this in the appSetting section of your web.config file: <add key="owin:appStartup" value="UmbracoDefaultOwinStartup" />

Other considerations:

WebApi has been updated, normally you don’t have to do anything unless you have custom webapi configuration:
- See this article if you are using WebApiConfig.Register: https://www.asp.net/mvc/overview/releases/how-to-upgrade-an-aspnet-mvc-4-and-web-api-project-to-aspnet-mvc-5-and-web-api-2
- You need to update your web.config file to have the correct WebApi version references - this should be done by doing a compare/merge of your ~/web.config file with the ~/web.config file in the release
MVC has been updated to MVC5
- You need to update your web.config file to have the correct MVC version references - this should be done by doing a compare/merge of your ~/web.config file with the ~/web.config file in the release
- The upgrader will take care of updating all other web.config’s (in all other folders, for example, the Views and App_Plugins folders) to have the correct settings
- For general ASP.NET MVC 5 upgrade details see: https://www.asp.net/mvc/overview/releases/how-to-upgrade-an-aspnet-mvc-4-and-web-api-project-to-aspnet-mvc-5-and-web-api-2
It is not required that you merge the changes for the Examine index paths in the ExamineIndex.config file. However, if you do, your indexes will be rebuilt on startup because Examine will detect that they don’t exist at the new location.
It's highly recommended to clear the browser cache - the ClientDependency version is automatically bumped during installation which should force the browser cache to refresh, however in some edge cases this might not be enough.

Follow the upgrade guide for Umbraco 7 to complete the upgrade.

7.1.0 to 7.2.0

Copy in the /Views/Partials/Grid (contains Grid rendering views).

Follow the upgrade guide for Umbraco 7 to complete the upgrade.

7.0.2 to 7.1.0

Remove the /Install folder.

Follow the upgrade guide for Umbraco 7 to complete the upgrade.

7.0.1 to 7.0.2

There was an update to the /umbraco/config/create/ui.xml which needs to be manually updated. The original element had this text:

<nodeType alias="users">
    <header>User</header>
    <usercontrol>/create/simple.ascx</usercontrol>
    <tasks>
    <create assembly="umbraco" type="userTasks" />
    <delete assembly="umbraco" type="userTasks" />
    </tasks>
</nodeType>

The usercontrol value has changed to: /create/user.ascx. This is a required change otherwise creating a new user will not work.
There is a breaking change to be aware of, full details can be found here.

Follow the upgrade guide for Umbraco 7 to complete the upgrade.

7.0.0 to 7.0.1

Remove all uGoLive dlls from /bin
- These are not compatible with V7
Move appSettings/connectionStrings back to web.config
- If you are on 7.0.0 you should migrate these settings into the web.config instead of having them in separate files in /config/
- The keys in config/AppSettings.config need to be moved back to the web.config <appSettings> section and similarly, the config/ConnectionStrings.config holds the Umbraco database connections in v7.0.0 and they should be moved back to the web.config <connectionStrings> section.
- /config/AppSettings.config and /config/ConnectionString.config can be removed after the contents have been moved back to web.config.
Delete all files in ~/App_Data/TEMP/Razor/
- Related to issues with razor macros

Follow the upgrade guide for Umbraco 7 to complete the upgrade.

6.latest to 7

Read and follow the full v7 upgrade guide

4.latest to 6

If your site was ever a version between 4.10.0 and 4.11.4 and you have upgraded to 6.0.0 install the fixup package and run it after the upgrade process is finished.
The DocType Mixins package is not compatible with v6+ and will cause problems in your Document Types.

Version 4

Version 4.10.x to 4.11.x

If your site was ever a version between 4.10.0 and 4.11.4 install the fixup package and run it after the upgrade process is finished.

Version 4.8.0 to 4.10.0

Delete the bin/umbraco.linq.core.dll file
Copy the new files and folders from the zip file into your site's folder
- /App_Plugins
- /Views
- Global.asax
Remove the Config/formHandlers.config file

Version 4.7.2 to 4.8.0

Delete the bin/App_Browsers.dll file
Delete the bin/App_global.asax.dll file
Delete the bin/Fizzler.Systems.HtmlAgilityPack.dll file
For people using uComponents 3.1.2 or below, 4.8.0 breaks support for it. Either upgrade to a newer version beforehand or follow the workaround posted here

Version 4.7.1.1 to 4.7.2

Delete the bin/umbraco.MacroEngines.Legacy.dll file

Version 4.6.1 to 4.7.1.1

Delete bin/Iron*.dll (all dll files starting with "Iron")
Delete bin/RazorEngine*.dll (all dll files starting with "RazorEngine")
Delete bin/umbraco.MacroEngines.Legacy.dll
Delete bin/Microsoft.Scripting.Debugging.dll
Delete bin/Microsoft.Dynamic.dll

Block Grid

Alias: Umbraco.BlockGrid

Returns: BlockGridModel

The Block Grid property editor enables editors to layout their content in the Umbraco backoffice. The content is made of Blocks that can contain different types of data.

Sample configuration

When testing out the property editor, you can use a set of predefined Blocks. The option will only be possible when there are no other Data Types using the Block Grid property editor.

Create a new Data Type.
Select the Block Grid as the Property editor.
Install the "Sample Configuration".

4 Blocks will be added to the property, ready for testing.

Configuring the Block Grid

The Block Grid property editor is configured via the Data Types backoffice interface.

To set up the Block Grid property editor, follow these steps:

Navigate to the Settings section in the Umbraco backoffice.
Right-click the Data Types folder.
Select Create -> New Data Type.
Select Block Grid from the list of available property editors.

You will see the configuration options for a Block Grid property editor as shown below:

The Data Type editor allows you to configure the following properties:

Blocks - Defines the Block Types available for use in the property. For more information, see Setup Block Types.
Amount - Sets the minimum and/or the maximum number of Blocks that should be allowed at the root of the layout.
Live editing mode - Enabling this option will allow you to see the changes as you are editing them.
Editor width - Overwrites the width of the property editor. This field takes any valid CSS value for "max-width". For example: 100% or 800px.
Grid Columns - Define the number of columns in your grid layout. The default is 12 columns.
Layout Stylesheet - Replaces the built-in Layout Stylesheet. Additionally, you can retrieve the default layout stylesheet to use as a base for your own inspiration or for writing your own stylesheet.
Create Button Label - Overwrites the label on the Create button.

Setup Block Types

Block Types are based on Element Types. These can be created beforehand or while setting up your Block Types.

Once you have added an Element Type as a Block Type on your Block Grid Data Type you have the option to configure it.

Examples and more details about configuring the Label property

Groups

Blocks can also be grouped. This is visible in the Block Catalogue and can also be used to allow a group of Blocks in an Area.

Block Configuration Settings

Each Block has a set of properties that are optional to configure. These are described below.

General

Customize the user experience for your content editors when they work with the Blocks in the Content section.

Label - Defines a label for the appearance of the Block in the editor. The label can use AngularJS template-string-syntax to display values of properties.

Label example: "My Block {{myPropertyAlias}}" will be shown as: "My Block FooBar".

You can also use more advanced expression using AngularJS filters, like {{myPropertyAlias | limitTo:100}} or for a property using Richtext editor {{myPropertyAlias | ncRichText | truncate:true:100}}. It is also possible to use properties from the Settings model by using {{$settings.propertyAlias}}.

Get more tips on how to use AngularJS filters in Umbraco CMS from this community-made Umbraco AngularJS filter cheat sheet.

Content model - Presents the Element Type used as model for the Content section of this Block. This cannot be changed but you can open the Element Type to perform edits or view the properties available. Useful when writing your Label.
Settings model - Adds a Settings section to your Block based on a given Element Type. When selected you can open the Element Type or choose to remove the Settings section again.

Size options

Customize the Blocks size in the Grid. If you define multiple options, the Block becomes scalable.

By default, a Block takes up the available width.

A Block can be resized in two ways:

When a Block is placed in an Area, it will fit to the Areas width. Learn more about Areas.
A Block can have one or more Column Span options defined.

A Column Span option is used to define the width of a Block. With multiple Column Span options defined, the Content Editor can scale the Block to fit specific needs.

Additionally, Blocks can be configured to span rows, this enables one Block to be placed next to a few rows containing other Blocks.

Available column spans - Defines one or more columns, the Block spans across. For example: in a 12 columns grid, 6 columns is equivalent to half width. By enabling 6 columns and 12 columns, the Block can be scaled to either half width or full width.
Available row spans - Defines the amount of rows the Block spans across.

See the scaling blocks section of this article for an example of how scaling works.

Catalogue appearance

These properties refer to how the Block is presented in the Block catalogue when editors choose which Blocks to use for their content.

Background color - Defines a background color to be displayed beneath the icon or thumbnail. Example: #424242.
Icon color - Changes the color of the Element Type icon. Example: #242424.
Thumbnail - Pick an image or Scalable Vector Graphics (SVG) file to replace the icon of the Block in the catalogue.

The thumbnails for the catalogue are presented in the format of 16:10. We recommend a resolution of 400px width and 250px height.

Permissions

Allow in root - Determines whether the Block can be created at the root of your layout. Turn this off if you only want a Block to appear within Block Areas.
Allow in areas - Determines whether the Block can be created inside Areas of other Blocks. If this is turned off it can still be allowed in Block Areas by defining specific allowed Blocks.

Areas

Blocks can nest other Blocks to support specific compositions. These compositions can be used as a layout for other Blocks.

To achieve nesting, a Block must have one or more Areas defined. Each Area can contain one or more Blocks.

Each Area has a size, defined by column and rows spans. The grid for the Areas are based on the same amount of columns as your root grid, unless you choose to change it.

To scale an Area, click and drag the scale-button in the bottom-right corner of an Area.

Grid Columns for Areas - Overwrites the amount of columns used for the Area grid.
Areas - Determines whether the Block can be created inside Areas of other Blocks.

Area configuration

Alias - The alias is used to identify this Area. It is being printed by GetBlockGridHTML() and used as name for the Area slot in Custom Views. The alias is also available for CSS Selectors to target the HTML-Element representing an Area.
Create Button Label - Overwrites the Create Button Label of the Area.
Number of blocks - Determines the total number of Blocks in an Area.
Allowed block types - When this is empty, all Blocks with Permissions for creation in Areas, will be available. This can be overwritten by specifying the allowed Blocks. Define the types of Blocks or Groups of Blocks that are allowed. Additionally, you can also set how many Blocks of each type/group should be present.

When allowing a Group of Blocks, you might want to require a specific amount for a certain Block of that Group. This can be done by adding that Block Type to the list as well and set the requirements.

Advanced

These properties are relevant when working with custom views or complex projects.

Custom view - Overwrites the AngularJS view for the block presentation in the Content editor. Use this view to make a more visual presentation of the Block or make your own editing experience by adding your own AngularJS controller to the view.

Notice that any styling of a Block is scoped. This means that the default backoffice styles are not present for the view of this Block.

Custom stylesheet - Pick your own stylesheet to be used by the Block in the Content editor.
Overlay editor size - Sets the size for the Content editor overlay for editing this block.
Hide content editor - Hides the UI for editing the content in a Block Editor. This is only relevant if you made a custom view that provides the UI for editing of content.

Editing Blocks

When viewing a Block Grid property editor in the Content section for the first time, you will be presented with the option to Add content.

Clicking the Add content button opens up the Block Catalogue.

The Block Catalogue looks different depending on the amount of available Blocks and their catalogue appearance.

Click the Block Type you wish to create and a new Block will appear in the layout.

More Blocks can be added to the layout by clicking the Add content button. Alternatively, use the Add content button that appears on hover to add new Blocks between, besides, or above the existing Blocks.

To delete a Block, click the trash icon which appears on the mouse hover.

Sorting Blocks

Blocks can be rearranged using the click and drag feature. Move them up or down to place them in the desired order.

Moving a Block from one Area to another is done in the same way. If a Block is not allowed in the given position, the area will display a red color and not allow the new position.

Scaling Blocks

If a Block has multiple size options it can be scaled via the UI. This appears in the bottom left corner of the Block.

The Block is resized using a click-and-drag feature. Moving the mouse will change the size to the size options closest to the mouse pointer.

Rendering Block Grid Content

Rendering the stored value of your Block Grid property editor can be done in two ways:

Default rendering
Build your own rendering

1. Default rendering

You can choose to use the built-in rendering mechanism for rendering Blocks using a Partial View for each block.

The default rendering method is named GetBlockGridHtmlAsync() and comes with a few options - for example:

@await Html.GetBlockGridHtmlAsync(Model, "myGrid")

In the sample above "myGrid" is the alias of the Block Grid editor.

If you are using ModelsBuilder, the example will look like this:

@await Html.GetBlockGridHtmlAsync(Model.MyGrid)

To use the GetBlockGridHtmlAsync() method, you will need to create a Partial View for each Block Type. The Partial View must be named using the alias of the Element Type that is being used as Content Model for the Block Type.

These Partial View files need to go into the Views/Partials/blockgrid/Components/ folder.

Example: Views/Partials/blockgrid/Components/MyElementTypeAliasOfContent.cshtml.

The Partial Views will receive a model of type Umbraco.Cms.Core.Models.Blocks.BlockGridItem. This model contains Content and Settings from your block, as well as the configured RowSpan, ColumnSpan, and Areas of the Block.

Rendering the Block Areas

The Partial View for the Block is responsible for rendering its own Block Areas. This is done using another built-in rendering mechanism:

@await Html.GetBlockGridItemAreasHtmlAsync(Model)

Here you will need to create a Partial View for each Block Type within the Block Area. For the name, use the alias of the Element Type that is being used as Content Model for the Block Type.

These Partial Views must be placed in the same folder as before, (Views/Partials/blockgrid/Components/), and will receive a model of type Umbraco.Cms.Core.Models.Blocks.BlockGridItem.

Putting it all together

The following is an example of a Partial View for a Block Type of type MyElementTypeAliasOfContent.

MyElementTypeAliasOfContent.cshtml

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockGridItem>;

@* Render the value of field with alias 'heading' from the Element Type selected as Content section *@
<h1>@Model.Content.Value("heading")</h1>

@* Render the block areas *@
@await Html.GetBlockGridItemAreasHtmlAsync(Model)

If you are using ModelsBuilder, you can make the property rendering strongly typed by letting your view accept a model of type BlockGridItem<T>. For example:

MyElementTypeAliasOfContent.cshtml

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockGridItem<ContentModels.MyElementTypeAliasOfContent>>;
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;

@* Render the Heading property from the Element Type selected as Content section *@
<h1>@Model.Content.Heading</h1>

@* Render the block areas *@
@await Html.GetBlockGridItemAreasHtmlAsync(Model)

Stylesheet

Using the default rendering together with your layout stylesheet will provide what you need for rendering the layout.

If you like to use the Default Layout Stylesheet, you must copy the stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the css folder, example: wwwroot/css/umbraco-blockgridlayout.css.

<link rel="stylesheet" href="@Url.Content("~/css/blockgridlayout.css")" />

A set of built-in Partial Views are responsible for rendering the Blocks and Areas in a grid layout. If you want to tweak or change the way the grid layout is rendered, you can use the built-in Partial Views as a template:

Clone the views from <a href="https://github.com/umbraco/Umbraco-CMS/">GitHub</a>. They can be found in /src/Umbraco.Cms.StaticAssets/Views/Partials/blockgrid/
Copy the cloned views to the local folder Views/Partials/blockgrid/
Make changes to your copied views. The entry point for GetBlockGridHtmlAsync() is the view default.cshtml

2. Build your own rendering

The built-in value converter for the Block Grid property editor lets you use the block data as you like. Call the Value<T> method with a type of BlockGridModel to have the stored value returned as a BlockGridModel instance.

BlockGridModel contains the Block Grid configuration (like the number of columns as GridColumns) whilst also being an implementation of IEnumerable<BlockGridItem> (see details for BlockGridItem above).

The following example mimics the built-in rendering mechanism for rendering Blocks using Partial Views:

View.cshtml

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@using Umbraco.Cms.Core.Models.Blocks
@{
    var grid = Model.Value<BlockGridModel>("myGrid");

    // get the number of columns defined for the grid
    var gridColumns = grid.GridColumns;

    // iterate the block items
    foreach (var item in grid)
    {
        var content = item.Content;

        @await Html.PartialAsync("PathToMyFolderOfPartialViews/" + content.ContentType.Alias, item);
    }
}

If you do not want to use Partial Views, you can access the block item data directly within your rendering:

View.cshtml

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@using Umbraco.Cms.Core.Models.Blocks
@{
    var grid = Model.Value<BlockGridModel>("myGrid");

    // get the number of columns defined for the grid
    var gridColumns = grid.GridColumns;

    // iterate the block items
    foreach (var item in grid)
    {
        // get the content and settings of the block
        var content = item.Content;
        var settings = item.Settings;
        // get the areas of the block
        var areas = item.Areas;
        // get the dimensions of the block
        var rowSpan = item.RowSpan;
        var columnSpan = item.ColumnSpan;

        // render the block data
        <div style="background-color: #@(settings.Value<string>("color"))">
            <h2>@(content.Value<string>("title"))</h2>
            <span>This block is supposed to span <b>@rowSpan rows</b> and <b>@columnSpan columns</b></span>
        </div>
    }
}

Write a Custom Layout Stylesheet

The default layout stylesheet is using CSS Grid. This can be modified to fit your implementation and your project.

Adjusting the Default Layout Stylesheet

To make additions or overwrite parts of the default layout stylesheet, import the default stylesheet at the top of your own file.

@import 'css/umbblockgridlayout.css';

You need to copy the Default Layout Stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the css folder, example: wwwroot/css/umbraco-blockgridlayout.css.

Write a new Layout Stylesheet

In this case, you would have to write the layout from scratch.

You are free to pick any style, meaning there is no requirement to use CSS Grid. It is, however, recommended to use CSS Grid to ensure complete compatibility with the Umbraco backoffice.

CSS Class structure and available data

When extending or writing your own layout, you need to know the structure and what data is available.

For example: You can use the below HTML structure:

<div class="umb-block-grid"
     style="--umb-block-grid--grid-columns: 12;"
>

    <!-- Notice this is the same markup used every time we will be printing a list of blocks: -->
    <div class="umb-block-grid__layout-container">

        <!-- repeated for each layout entry -->
        <div
            class="umb-block-grid__layout-item"
            data-content-element-type-alias="MyElementTypeAlias"
            data-content-element-type-key="00000000-0000-0000-0000-000000000000"
            data-element-udi="00000000-0000-0000-0000-000000000000"
            data-col-span="6"
            data-row-span="1"
            style="
            --umb-block-grid--item-column-span: 6;
            --umb-block-grid--item-row-span: 1;
            "
        >

            <!-- Here the Razor View or Custom View for this block will be rendered. -->

            <!-- Each razor view must render the 'area-container' them self.
            This can be done by the Razor helper method:

            @await Html.GetBlockGridItemAreasHtmlAsync(Model)

            The structure will be as printed below,
            Do notice targeting the 'area-container' needs a double selector as markup will be different in Backoffice.
            Here is an example of the CSS selector:
                .umb-block-grid__area-container, .umb-block-grid__block--view::part(area-container) {
                    position: relative;
                }
            -->
            <div
                class="umb-block-grid__area-container"
                style="--umb-block-grid--area-grid-columns: 9;"
            >

                <!-- repeated for each area for this block type. -->
                <div
                    class="umb-block-grid__area"
                    data-area-col-span="3"
                    data-area-row-span="1"
                    data-area-alias="MyAreaAlias"
                    style="
                    --umb-block-grid--grid-columns: 3;
                    --umb-block-grid--area-column-span: 3;
                    --umb-block-grid--area-row-span: 1;
                    ">

                        <!-- Notice here we print the same markup as when we print a list of blocks(same as the one in the root of this structure..):
                        <div class="umb-block-grid__layout-container">
                            ...
                        </div>
                        End of notice.  -->
                </div>
                <!-- end of repeat -->

            </div>


        </div>
        <!-- end of repeat -->

    </div>

</div>

Build a Custom Backoffice View

Building Custom Views for Block representations in Backoffice is based on the same API for all Block Editors.

Read about building a Custom View for Blocks here

Creating a Block Grid programmatically

In this example, we will be creating content programmatically for a "spot" Blocks in a Block Grid.

On a document type add a property called blockGrid.
Then add as editor Block Grid.
In the Block Grid add a new block and click to Create new Element Type
Name this element type spotElement with the following properties:

a property called title with the editor of Textstring
a property called text with the editor of Textstring

Then on the Settings model click to add a new Setting.
Then click to Create new Element Type.
Name this element type spotSettings with the following properties:

a property called featured with the editor of True/false.

The raw input data for the spots looks like this:

new[]
{
    new { Title = "Item one", Text = "This is item one", Featured = false, ColumnSpan = 12, RowSpan = 1 },
    new { Title = "Item two", Text = "This is item two", Featured = true, ColumnSpan = 6, RowSpan = 2 }
}

The resulting JSON object stored for the Block Grid will look like this:

{
    "layout": {
        "Umbraco.BlockGrid": [{
                "contentUdi": "umb://element/bb23fe28160941efa506da7aa314172d",
                "settingsUdi": "umb://element/9b832ee528464456a8e9a658b47a9801",
                "areas": [],
                "columnSpan": 12,
                "rowSpan": 1
            }, {
                "contentUdi": "umb://element/a11e06ca155d40b78189be0bdaf11c6d",
                "settingsUdi": "umb://element/d182a0d807fc4518b741b77c18aa73a1",
                "areas": [],
                "columnSpan": 6,
                "rowSpan": 2
            }
        ]
    },
    "contentData": [{
            "contentTypeKey": "0e9f8609-1904-4fd1-9801-ad1880825ff3",
            "udi": "umb://element/bb23fe28160941efa506da7aa314172d",
            "title": "Item one",
            "text": "This is item one"
        }, {
            "contentTypeKey": "0e9f8609-1904-4fd1-9801-ad1880825ff3",
            "udi": "umb://element/a11e06ca155d40b78189be0bdaf11c6d",
            "title": "Item two",
            "text": "This is item two"
        }
    ],
    "settingsData": [{
            "contentTypeKey": "22be457c-8249-42b8-8685-d33262f7ce2a",
            "udi": "umb://element/9b832ee528464456a8e9a658b47a9801",
            "featured": "0"
        }, {
            "contentTypeKey": "22be457c-8249-42b8-8685-d33262f7ce2a",
            "udi": "umb://element/d182a0d807fc4518b741b77c18aa73a1",
            "featured": "1"
        }
    ]
}

For each item in the raw data, we need to create:

One contentData entry with the title and text.
One settingsData entry with the featured value (the checkbox expects "0" or "1" as data value).
One layout entry with the desired column and row spans.

All contentData and layoutData entries need their own unique Udi as well as the ID (key) of their corresponding Element Types. In this sample, we only have one Element Type for content (spotElement) and one for settings (spotSettings). In a real life scenario, there could be any number of Element Type combinations.

First and foremost, we need models to transform the raw data into Block Grid compatible JSON. Create a class called Model.cs containing the following:

Models.cs

using Newtonsoft.Json;
using Umbraco.Cms.Core;

namespace My.Site.Models;

// this is the "root" of the block grid data
public class BlockGridData
{
    public BlockGridData(BlockGridLayout layout, BlockGridElementData[] contentData, BlockGridElementData[] settingsData)
    {
        Layout = layout;
        ContentData = contentData;
        SettingsData = settingsData;
    }

    [JsonProperty("layout")]
    public BlockGridLayout Layout { get; }

    [JsonProperty("contentData")]
    public BlockGridElementData[] ContentData { get; }

    [JsonProperty("settingsData")]
    public BlockGridElementData[] SettingsData { get; }
}

// this is a wrapper for the block grid layout, purely required for correct serialization
public class BlockGridLayout
{
    public BlockGridLayout(BlockGridLayoutItem[] layoutItems) => LayoutItems = layoutItems;

    [JsonProperty("Umbraco.BlockGrid")]
    public BlockGridLayoutItem[] LayoutItems { get; }
}

// this represents an item in the block grid layout collection
public class BlockGridLayoutItem
{
    public BlockGridLayoutItem(Udi contentUdi, Udi settingsUdi, int columnSpan, int rowSpan)
    {
        ContentUdi = contentUdi;
        SettingsUdi = settingsUdi;
        ColumnSpan = columnSpan;
        RowSpan = rowSpan;
    }

    [JsonProperty("contentUdi")]
    public Udi ContentUdi { get; }

    [JsonProperty("settingsUdi")]
    public Udi SettingsUdi { get; }

    [JsonProperty("areas")]
    // areas are omitted from this sample for abbreviation
    public object[] Areas { get; } = { };

    [JsonProperty("columnSpan")]
    public int ColumnSpan { get; }

    [JsonProperty("rowSpan")]
    public int RowSpan { get; }

}

// this represents an item in the block grid content or settings data collection
public class BlockGridElementData
{
    public BlockGridElementData(Guid contentTypeKey, Udi udi, Dictionary<string, object> data)
    {
        ContentTypeKey = contentTypeKey;
        Udi = udi;
        Data = data;
    }

    [JsonProperty("contentTypeKey")]
    public Guid ContentTypeKey { get; }

    [JsonProperty("udi")]
    public Udi Udi { get; }

    [JsonExtensionData]
    public Dictionary<string, object> Data { get; }
}

By injecting ContentService and ContentTypeService into an API controller, we can transform the raw data into Block Grid JSON. It can then be saved to the target content item. Create a class called BlockGridTestController.cs containing the following:

BlockGridTestController.cs

using Microsoft.AspNetCore.Mvc;
using My.Site.Models;
using Newtonsoft.Json;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Web.Common.Controllers;

namespace My.Site.Controllers;

public class BlockGridTestController : UmbracoApiController
{
    private readonly IContentService _contentService;
    private readonly IContentTypeService _contentTypeService;

    public BlockGridTestController(IContentService contentService, IContentTypeService contentTypeService)
    {
        _contentService = contentService;
        _contentTypeService = contentTypeService;
    }

    // POST: /umbraco/api/blockgridtest/create
    [HttpPost]
    public ActionResult Create()
    {
        // get the item content to modify
        IContent? content = _contentService.GetById(1203);
        if (content == null)
        {
            return NotFound("Could not find the content item to modify");
        }

        // get the element types for spot blocks (content and settings)
        IContentType? spotContentType = _contentTypeService.Get("spotElement");
        IContentType? spotSettingsType = _contentTypeService.Get("spotSettings");
        if (spotContentType == null || spotSettingsType == null)
        {
            return NotFound("Could not find one or more content types for block data");
        }

        // this is the raw data to insert into the block grid
        var rawData = new[]
        {
            new { Title = "Item one", Text = "This is item one", Featured = false, ColumnSpan = 12, RowSpan = 1 },
            new { Title = "Item two", Text = "This is item two", Featured = true, ColumnSpan = 6, RowSpan = 2 }
        };

        // build the individual parts of the block grid data from the raw data
        var layoutItems = new List<BlockGridLayoutItem>();
        var spotContentData = new List<BlockGridElementData>();
        var spotSettingsData = new List<BlockGridElementData>();
        foreach (var data in rawData)
        {
            // generate new UDIs for block content and settings
            var contentUdi = Udi.Create(Constants.UdiEntityType.Element, Guid.NewGuid());
            var settingsUdi = Udi.Create(Constants.UdiEntityType.Element, Guid.NewGuid());

            // create a new layout item
            layoutItems.Add(new BlockGridLayoutItem(contentUdi, settingsUdi, data.ColumnSpan, data.RowSpan));

            // create new content data
            spotContentData.Add(new BlockGridElementData(spotContentType.Key, contentUdi, new Dictionary<string, object>
            {
                { "title", data.Title },
                { "text", data.Text },
            }));

            // create new settings data
            spotSettingsData.Add(new BlockGridElementData(spotSettingsType.Key, settingsUdi, new Dictionary<string, object>
            {
                { "featured", data.Featured ? "1" : "0" },
            }));
        }

        // construct the block grid data from layout, content and settings
        var blockGridData = new BlockGridData(
            new BlockGridLayout(layoutItems.ToArray()),
            spotContentData.ToArray(),
            spotSettingsData.ToArray());

        // serialize the block grid data as JSON and save it to the "blockGrid" property on the content item
        var propertyValue = JsonConvert.SerializeObject(blockGridData);
        content.SetValue("blockGrid", propertyValue);
        _contentService.Save(content);

        return Ok("Saved");
    }
}

For the above code IContent? content = _contentService.GetById(1203); change the id with your content node that is using the Block Grid.

In order to test this implementation, run the project and add /umbraco/api/blockgridtest/create after your domain name. If the result shows as Saved then check your content node and you will see the 2 spotElement contents.

This can also be tested via Postman as well if preffered.