1 of 100

17.latest (LTS)

Fundamentals

Installation

Instructions on installing Umbraco on various platforms using various tools.

Install the latest .NET Software Development Kit (SDK)

Before you install Umbraco, you must ensure that you can run it on your machine.

Identify and install the latest .NET SDK.

Install Umbraco using CLI

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

Open your command line.
Install the Umbraco templates:

Create a new project:

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

Build and run the newly created Umbraco site:

The console will output a message similar to: [10:57:39 INF] Now listening on: https://localhost:44388

We recommend setting up a developer certificate and running the website under HTTPS. If that has not yet been configured, run the following command:

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 . 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 install and set up Umbraco projects.

.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 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.

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

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.

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.

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.

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

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 on your machine:

One of the
One of the following .NET Tools or Editors:
- with the

Umbraco can be installed with a SQLite or SQL Server database and configured with a . For SQL Server, indicating a minimum supported version of SQL Server 2016.

When using Visual Studio as your primary Integrated Development Environment (IDE) we recommend .

Are you using Microsoft SQL as your data? The Umbraco Data Access Layer (DAL) does not support case-sensitive naming. When you use Microsoft SQL as your database, ensure that the database is created using a case-insensitive (CI) collation variant. For example, SQL_Latin1_General_CP1_CI_AS. Learn more about in the official Microsoft documentation.

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:

and other

For more information, see the article in the Microsoft documentation.

You can use 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 .

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

Start by implementing a custom IServerRoleAccessor that pins the role as SchedulingPublisher:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<EntityDataPickerTest>
@{
    Layout = null;
}
<html lang="en">
<head>
    <title>Entity Data Picker</title>
</head>
<body>
@if (Model.MyEntityPicker is null)
{
    <p>No entity picker value found</p>
}
else
{
    <p>Data source: <strong>@Model.MyEntityPicker.DataSource</strong></p>
    <p>Picked IDs:</p>
    <ul>
        @foreach (string id in Model.MyEntityPicker.Ids)
        {
            <li>@id</li>
        }
    </ul>
}
</body>
</html>

using Umbraco.Cms.Core.Composing;

namespace Umbraco.Cms.Web.UI.SignalRLoadBalancing;

public class SignalRComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        var connectionString = builder.Config.GetUmbracoConnectionString();
        if (connectionString is null)
        {
            return;
        }

        builder.Services.AddSignalR().AddSqlServer(connectionString);
    }
}

using Umbraco.Cms.Core.Composing;

namespace Umbraco.Cms.Web.UI.SignalRLoadBalancing;

public class SignalRComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder) => builder.Services.AddSignalR().AddAzureSignalR();
}

@using Umbraco.Cms.Core.Models
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@{
    Layout = null;
    var entityDataPickerValue = Model.Value<EntityDataPickerValue>("myEntityPicker");
}
<html lang="en">
<head>
    <title>Entity Data Picker</title>
</head>
<body>
@if (entityDataPickerValue is null)
{
    <p>No entity picker value found</p>
}
else
{
    <p>Data source: <strong>@entityDataPickerValue.DataSource</strong></p>
    <p>Picked IDs:</p>
    <ul>
        @foreach (string id in @entityDataPickerValue.Ids)
        {
            <li>@id</li>
        }
    </ul>
}
</body>
</html>

Running Umbraco in Docker using Docker Compose

Running Umbraco on docker locally using docker compose

This article shows how to run Umbraco locally in Docker using Docker Compose. You can use either SQL Server or SQLite for development.

This setup is intended for local development only. It is not recommended for production environments.

Prerequisites

Before you can run Umbraco in Docker, make sure the following are installed:

.NET SDK with Umbraco Templates v16 or higher
Docker Desktop

Installing

To install Umbraco using the provided Dockerfile and Docker Compose setup, follow these steps:

Option 1: Using SQL Server

Create a folder and navigate into it:

Create a new Umbraco project with Docker support:

Add Docker Compose files:

The -P flag is required to specify the correct paths in the docker-compose file. The project is now ready to run with Docker Compose.

The folder structure should now look like this:

MyDockerProject/
- Database/
  - Dockerfile
  - healthcheck.sh

The project now includes docker files for both Umbraco and the SQL server database.

It also includes additional scripts to launch and configure the database and a .env file with the database password.

Run the following command from the root folder (where docker-compose.yml is located):

Access the site at http://localhost:44372.

Option 2: Using SQLite

Create a new folder and navigate into it:

Create a new Umbraco project:

Add a Dockerfile

To speed up the build process, add a .dockerignore file to exclude unnecessary folders like .git, bin, and obj.

Build the container:

Run the container:

Access the site at http://localhost:8080.

Useful Commands

There are some useful commands you can use to manage the docker containers:

docker compose down --volumes: Deletes containers and the volumes they use. This is useful if you want to start from scratch.

Be careful with this command, as it deletes your database and all data in it.

docker compose up --build: Rebuild the images and start the containers. This is useful if you have made changes to the project and want to see them reflected on the running site.
docker compose watch: Start the containers and watch the default models folder. This means that if the project uses a source-code models builder the images are automatically rebuilt and restarts when you change the models.

Bind Mounts (SQL Server setup)

The docker compose file uses bind mounts for the following folders:

/wwwroot/media
/wwwroot/scripts
/wwwroot/css

This is not meant to be used in production.

For local development, however, this means that the files necessary for development are available from outside the container in your IDE. This allows development even though the project is running in docker.

Template Options (SQL Server only)

The umbraco-compose template supports:

-P or --project-name: The name of the project. This is required and used to set the correct paths in the docker-compose file.
-dbpw or --DatabasePassword: Used to specify the database password. This is stored in the .env file and defaults to: Password1234.

Block Level Variance

An intro to achieving content variance at block level.

In a variant context, a Block Editor behaves like any other Umbraco property editor by default. The Blocks contained within the editor "belong" to the Document variant, and there is no connection between Blocks across variants.

In other words, both Block content and structure can vary between each Document variant.

This is the desired behavior for many cases. However, in some cases it is preferable to have a shared Block structure across all variants, where only the Block content varies.

This is known as Block Level Variance:

Block Level Variance is achieved when:

The Document Type is configured for variance, and
The Block Editor property is not configured for variance, and
The Block Editor property editor is configured to use that do vary.

The "unexposed" Block state

When adding a new variant Block to one Document variant, it is automatically added to all variants of the Document.

The Block will start out in an "unexposed" state for all other Document variants than the one where it was added. It will remain like that for each variant until it is edited in that variant.

The "unexposed" state is visualized by a dimmed-down icon and title (or likely a missing title, if is used):

"Unexposed" Blocks are omitted from the published Document output. So, you do not need to worry about defensive coding to avoid rendering these Blocks.

Invariance vs. Block Level Variance

It is entirely possible to mix and match variance and invariance within the scope of Block Level Variance. Invariance is fully supported, both at Block level and at Block property level.

Invariance within Block Level Variance follows the same rules as invariance at Document level:

Invariant content is added to and updated across all Document variants.
Invariant content is explicitly published for all published Document variants when one or more variants are published.

Examples

Consider a Document with English and Danish language variants, which is published in both languages.

An editor opens the English variant.
They add an invariant Block, and
They re-publish the English variant.

Result: The new block will appear in both the English and Danish published content.

An editor opens the Danish variant.
They update an invariant property value in a variant Block, and
They re-publish the Danish variant.

Result: The updated property value appears in both the English and Danish published content.

Structure vs. Block Level Variance

The Block Editor structure is invariant for Block Level Variance. This means that the structure follows the same rules for invariance as outlined in the section above.

In other words: If an editor changes the order of the Blocks in one Document variant, it changes for all Document variants. The change is applied to all published Document variants, as soon as one or more variants are published.

Custom CSS properties

Customize the appearance of the Rich Text Editor with custom CSS properties.

You can customize the appearance of the Rich Text Editor using CSS properties by defining them in your CSS files.

For example, to set the minimum height of all Rich Text Editors throughout the backoffice. You could use the following CSS rule:

:root {
    --umb-rte-min-height: 300px;
}

For general information on working with stylesheets and JavaScript in Umbraco, check Stylesheets and JavaScript.

If you wanted to target a specific Rich Text Editor, you can set the stylesheet directly in the configuration.

Custom CSS properties reference

The following CSS properties are available for customization:

CSS Property

Description

Default Value

The CSS custom properties may change in future versions of Umbraco. You can always find the latest values in the in the Umbraco CMS GitHub repository.

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 'pageLabel'. 
    content.SetValue("pageLabel", "A pre-set string value");
    
    // Save the change
    ContentService.Save(content);
}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'pageLabel'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.MyLabel).Alias, "A pre-set string value");
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");
    
    // 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 'colorTheme'
    content.SetValue("colorTheme", "water");
            
    // Save the change
    ContentService.Save(content);
}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'colorTheme'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.ColorTheme).Alias, "water");
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 'description'
    content.SetValue("description", "This is some text for the text area!");

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{

    // Set the value of the property with alias 'description'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.Description).Alias, "This is some text for the text area!");
}

/Views

FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
WORKDIR /app
EXPOSE 8080

FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["MyDockerSqliteProject/MyDockerSqliteProject.csproj", "MyDockerSqliteProject/"]
RUN dotnet restore "MyDockerSqliteProject/MyDockerSqliteProject.csproj"
COPY . .
WORKDIR "/src/MyDockerSqliteProject"
RUN dotnet build "MyDockerSqliteProject.csproj" -c  $BUILD_CONFIGURATION -o /app/build

FROM build AS publish
RUN dotnet publish "MyDockerSqliteProject.csproj" -c  $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyDockerSqliteProject.dll"]

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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);
}

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

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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

    // Create a variable for the GUID of the member ID
    var authorId = Guid.Parse("ed944097281e4492bcdf783355219450");

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

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'author'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.Author).Alias, udi);
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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);
}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{

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

@{
     // Model has a property called "Color" which holds a Color Picker editor
    var hexColor = Model.Color;
    // Define the label if you've included it
    String colorLabel = Model.Color.Label;

    if (hexColor != null)
    {
        <div style="background-color: #@hexColor">@colorLabel</div>
    }
}

@using Umbraco.Cms.Core.PropertyEditors.ValueConverters
@{
    // Model has a property called "Color" which holds a Color Picker editor
    var hexColor = Model.Value("Color");
    // Define the label if you've included it
    var colorLabel = Model.Value<ColorPickerValueConverter.PickedColor>("Color").Label;

    if (hexColor != null)
    {
        <div style="background-color: #@hexColor">@colorLabel</div>
    }
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 'color'. 
    // The value set here, needs to be one of the colors on the Color Picker
    content.SetValue("color", "38761d");

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

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 'color'. 
    // The value set here, needs to be one of the colors on the Color Picker
    content.SetValue("color", "{'value':'000000', 'label':'Black', 'sortOrder':1, 'id':'1'}");

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'color'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.Color).Alias, "38761d");
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");
    
    // 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 'memberGroup'. The value is the specific ID of the member group
    content.SetValue("memberGroup", 1067);
            
    // Save the change
    ContentService.Save(content);
}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'memberGroup'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.MemberGroup).Alias, 1067);
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 'color'.
    content.SetValue("color", "#6fa8dc");
    
    // Save the change
    ContentService.Save(content);
}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'color'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.Color).Alias, "#6fa8dc");
    
    // Set the value of the property with alias 'theme'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.Theme).Alias, "rgba(111, 168, 220, 0.7)");
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");
    
    // 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 'myCheckBox'
    content.SetValue("myCheckBox", true);
            
    // Save the change
    ContentService.Save(content);
}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'myCheckBox'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.MyCheckBox).Alias, true);
}

@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", "[email protected]");

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

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Infrastructure.Migrations.Upgrade.V_15_0_0;

namespace UmbracoDocs.Samples;

public class DisableBlockEditorMigrationComposer : IComposer
{
    [Obsolete]
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<ConvertBlockEditorPropertiesOptions>(options =>
        {
            // setting this to true will parallelize the migration of all Block Editors
            options.ParallelizeMigration = true;
        });
}

DisableBlockEditorMigrationComposer.cs

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Infrastructure.Migrations.Upgrade.V_15_0_0;

namespace UmbracoDocs.Samples;

public class DisableBlockEditorMigrationComposer : IComposer
{
    [Obsolete]
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<ConvertBlockEditorPropertiesOptions>(options =>
        {
            // setting this to true will skip the migration of all Block List properties
            options.SkipBlockListEditors = false;

            // setting this to true will skip the migration of all Block Grid properties
            options.SkipBlockGridEditors = false;

            // setting this to true will skip the migration of all Rich Text Editor properties
            options.SkipRichTextEditors = false;
        });
}

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

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

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

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

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

The renaming is purely a client-side UI change, meaning the property editor still uses the Umbraco.ContentPicker schema alias.

Migrate custom Property Editors to Umbraco version 14 and later

This article helps you migrate custom Property Editors to Umbraco 14 and later

This article applies only to implementers of custom Property Editors, that is:

Maintainers of Property Editor packages.
Site implementers who have built their own Property Editors.

Umbraco 14 introduces a split between server-side and client-side Property Editor aliases. The reasoning behind this change is two-fold:

It allows server-side implementations to be reused for multiple client-side Property Editor UIs.
It helps to ensure a better division between client-side and server-side responsibility.

Migration impact for Property Editors

In the Umbraco source code, the change manifests as the EditorUiAlias property on IDataType.

When upgrading from Umbraco 13 to Umbraco 14 and later, Umbraco automatically migrates all Data Types to include an EditorUiAlias value. For custom Property Editors, this migration is based on certain assumptions.

Manifest based Property Editors

If the Property Editor is built with a :

Assign the package manifest alias to the Data Type EditorUiAlias, and
Convert the Data Type EditorAlias to the alias of a core Data Editor, based on the valueType specified in the package manifest.

The following table contains the applied conversion from valueType to EditorAlias:

This might also impact Property Value Converters

Property Value Converters for package manifest based Property Editors might be impacted by this migration.

It is common practice to pair a Property Editor to a Property Value Converter using the package manifest alias:

Since the migration moves the alias

Code based editors

If the Property Editor is built with a , we:

Assign the Data Editor Alias to the Data Type EditorUiAlias, and
Retain the Data Type EditorAlias as-is (which is the Data Editor Alias).

The Data Editor Alias is found in the DataEditor attribute:

Migration impact for porting Property Editor UIs

The file is a central component for extensions in Umbraco 14+, including Property Editor UIs.

To keep the Property Editor working with migrated properties, ensure that the propertyEditorUi extension is declared with:

The migrated value of EditorUiAlias as its alias, and
The migrated value of EditorAlias as its propertyEditorSchemaAlias (found in the extension meta collection).

For example:

See the article for guidance on building a Property Editor UI for Umbraco 14 and later.

Alternatives

If the Data Type migration yields an undesirable result, you have two options:

Manually change the EditorAlias and/or EditorUiAlias directly in the umbracoDataType table, or
Create a custom migration to update the properties. See the article for inspiration.

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 Install an Umbraco project template.

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

The 'umbracoDbDSN_ProviderName' attribute sets the .NET Framework data provider name for the DataSource control's connection. For more information on the data providers included in the .Net Framework, see the .

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 UnattendedTelemetryLevel can be set to Minimal, Basic, or Detailed. If omitted, Detailed is the default.

Alternatively you may set your configuration with Environment Variables or other means. Learn more about this in the .

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

Running Umbraco in Docker

Exactly how you choose to compose your Dockerfile will depend on your project specific needs. This section is not intended as a comprehensive guide, rather as an overview of topics to be aware of when hosting in Docker.

What is Docker

Docker is a platform for developing, shipping, and running applications in containers. Multiple services exist for hosting these containers. For more information, refer to the official Docker Documentation

The Docker file system

By default, files created inside a container are written to an ephemeral, writable container layer. This means that the files don't persist when the container is removed, and it's challenging to get files out of the container. Additionally, this writable layer is not suitable for performance-critical data processing.

This has implications when running Umbraco in Docker.

For more information, refer to the .

General file system consideration

In general, when working with files and Docker you work in a "push" fashion with read-only layers. When you build, you take all your files and "push" them into this read-only layer.

This means that you should avoid making files on the fly, and instead rely on building your image.

In an Umbraco context, this means you should not create or edit template, script or stylesheet files via the backoffice. These should be deployed as part of your web application and not managed via Umbraco.

Similarly, you shouldn't use InMemory modelsbuilder, since that also relies on creating files on the disk. While this is not a hard requirement, it doesn't provide any value unless you are live editing your site.

Instead, configure models builder to use "source code" mode in development, and "none" in production, as .

Logs

Umbraco writes logs to the /umbraco/Logs/ directory. Due to the performance implications of writing to a writable layer, and the limited size, it is recommended to mount a volume to this directory.

You may prefer to avoid writing to disk for logs when hosting in containers. If so, you can disable this default behavior and register a custom Serilog sink to alternative storage, such as Azure Table storage.

You can also provide an alternative implementation of a common abstraction for the log viewer. In this way you can read logs from the location where you have configured them to be written.

For more details, read the article on Umbraco's .

Data

The /umbraco/Data/ directory is used to store temporary files, such as file uploads. Considering the limitations of the writable layer, you should also mount a volume to this directory.

Media

It's recommended to not store media in the writable layer. This is for similar performance reasons as logs, but also for practical hosting reasons. You likely want to persist media files between containers.

One solution is to use bind mounts. The ideal setup, though, is to store the media and ImageSharp cache externally. For more information, refer to the .

Required files

Your solution may require some specific files to run, such as license files. You will need to pass these files into the container at build time, or mount them externally.

HTTPS

When running websites in Docker, it's common to do so behind a reverse proxy or load balancer. In these scenarios you will likely handle SSL termination at the reverse proxy. This means that Umbraco will not be aware of the SSL termination, and will complain about not using HTTPS.

Umbraco checks for HTTPS in two locations:

The HstsCheck health check - This will result in a failed healthcheck.
The UseHttpsValidator - This will result in a build error, if Production runtime mode is used.

To avoid these checks failing, you can remove them in your project.

Health Check

The health check must be removed via configuration, through the appsettings.json file, environment variables, or similar. For more information see the .

The HstsCheck key is E2048C48-21C5-4BE1-A80B-8062162DF124 so the appsettings will look something like:

Runtime mode validator

The UseHttpsValidator must be removed through code For more information see the .

The code to remove the validator can look something like:

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 Examine Directory Factory Options and the Umbraco temporary storage location.

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/*

Alternatively store the Umbraco temporary files in the local server's 'temp' folder and set Examine to use a .

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.

There is a specific documentation for load balancing with

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.

If you are load balancing with make sure to check out the article we have for that specific set-up.

Advanced techniques

Once you are familiar with how flexible load balancing works, you might be interested in some .

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 to 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 .
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:

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

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 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 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.

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 https://code.visualstudio.com/ 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

Follow the to create your project folder.

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/.

Load Balancing Azure Web Apps

Ensure you read the Load Balancing overview and general Azure Web Apps 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

The single instance Backoffice Administrative Web App should be set to use .

The multi-instance Scalable Public Web App should be set to use .

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

Umbraco runs within a .

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.

You can also copy the following JSON directly into your Azure Web App configuration via the Advanced Edit feature.

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.

Date Time (with Time Zone)

Schema Alias: Umbraco.DateTimeWithTimeZone

UI Alias: Umb.PropertyEditorUi.DateTimeWithTimeZonePicker

Returns: DateTimeOffset?

The Date Time with Time Zone property editor provides a comprehensive interface for selecting dates, times, and time zones. It stores values as ISO 8601 date/time strings with time zone information. This makes it ideal for applications that need accurate date handling across different time zones.

Configuration

You can configure this property editor in the same way as any standard property editor, using the Data Types admin interface.

To set up a property using this editor, create a new Data Type. Select Date Time (with time zone) from the list of available property editors.

You will see the configuration options as shown below.

Time format - Specifies the level of precision for time values shown and stored by the editor.
Time zones - Controls how time zones are available in the property editor.

Time format

HH:mm - Displays hours and minutes (e.g., 14:30). Suitable for most general use cases.
HH:mm:ss - Displays hours, minutes, and seconds (e.g., 14:30:45). Use this when you need more precise timing.

Time zones

All - Displays the full list of time zones (for example, America/New_York, Europe/Stockholm).
Local - Displays only the local time zone of the user's browser/computer. Useful for simplifying the UI when time entries should always be based on the user’s local context.
Custom - Allows you to define a list of time zones. When you select this option, a dropdown appears. You can search and select from the full IANA time zone list. Add multiple zones to restrict user selection to only the zones you specify.

The selected time zone affects how the date/time is displayed and stored. When you select a time zone, the value will be saved with the corresponding offset (e.g., 2025-01-01T14:30:00+01:00). Daylight saving time is also taken into account.

Editing experience

Adding or editing a value

You will be presented with date, time, and time zone inputs. The time zone input allows typing, which filters the list of presented time zones.

If your browser time zone appears in the list and no date is stored yet, it will be pre-selected by default.

When you select a time zone different from your browser's local time zone, the editor displays a helpful conversion message. This shows what the selected date and time would be equivalent to in your local time zone, making it easier to understand the time difference.

If only one time zone is available, you will see a label with the time zone name instead.

Rendering

The value returned will have the type DateTimeOffset?. This allows you to work with the date/time value while preserving time zone information.

Display the value

With Models Builder:

Without Models Builder:

Value conversions

Convert to local time:

Convert to UTC time:

Convert to DateTime:

Add values programmatically

This property editor stores values as a JSON object. The object contains both the date (as an ISO 8601 string) and the selected time zone identifier.

Storage format

The property editor stores values in this JSON format:

Create a C# model that matches the JSON schema.
Create an instance of the created class with the desired values.
Inject the IJsonSerializer and use it to serialize the object.
Inject the IContentService

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 positioned at the top of the Backoffice.

Below is a short overview of the default sections in Umbraco CMS:

Content

The Content section contains the content nodes that make up the website. Content is displayed as nodes in the Content tree.

Nodes in Umbraco can display the following content states:

Grayed-out nodes are not published yet.
Nodes that are currently locked using the Public Access feature.
Content nodes that contain a collection of nodes.

To create content, you must define it using Document Types.

For more information, see the article.

Media

The Media section contains the media for the website. You can create folders and upload media files, such as images and PDFs. Additionally, you can customize the existing Media Types or define your own from the Settings section.

For more information, see the article.

Settings

The Settings section allows you to manage website layout files, languages, media, and content types. It also gives you access to more advanced features such as the Log Viewer and extension insights.

The Settings section consists of:

Structure

Document Types
Media Types
Member Types
Data Types

Templating

Templates (.cshtml files)
Partial views (.cshtml files)
Stylesheets (.css files)

Advanced

Relations
Log Viewer
Extension Insights
Webhooks

The Settings section in the Umbraco backoffice has its own set of default dashboards.

For more information, see the article.

Packages

In this section, you can browse the different packages available for your Umbraco solution. You can also get an overview of all the packages you have installed or created.

For more information, see the article.

Users

The Users section allows administrators to manage user accounts, assign permissions, set user roles, and monitor user activity within the backoffice. It provides control over who can access and modify content, media, and settings in the CMS.

For more information, see the article.

Members

The Members section allows to create and manage member profiles, set up member groups, and control Member's access to restricted content on the website.

For more information, see the article.

Dictionary

The Dictionary section is where you create and manage Dictionary Items. By managing these dictionary items, you can ensure consistent and efficient content translation and maintenance across different languages.

For more information, see the article.

Add-Ons

To enhance Umbraco's functionality, you can integrate plugins and extensions tailored to specific needs. These add-ons expand Umbraco's capabilities, allowing for a more customized and powerful content management experience.

For example, you can start with core Umbraco features and later decide to integrate additional products. Currently, Umbraco supports add-on products like:

Forms: Simplifies the creation and management of Forms.
Deploy: Facilitates smooth deployment processes.
Workflow: Enhances content workflows and approval processes.
Commerce: Adds e-commerce capabilities to your site.

When you add an add-on product to Umbraco, it appears in the Backoffice as a new section, seamlessly extending your content management capabilities.

If you wish to explore the unique features and use cases of Umbraco products, see the article.

For more information about extending the Umbraco platform through packages and integrations, see the documentation.

Help Section

The Help section in Umbraco provides documentation and resources to assist in understanding and effectively using the Umbraco CMS. It typically includes the following in the Getting Started Dashboard:

Documentation: Comprehensive guides, tutorials, and references covering different aspects of Umbraco.
Community Forums: Access to forums where you can ask questions, share knowledge, and seek assistance from other Umbraco community members.
Resources: Stay updated with the latest news, access documentation, watch free video tutorials, and register for live demos.
Training

The Help section serves as a valuable resource hub in navigating and leveraging the capabilities of the Umbraco CMS effectively.

Custom Sections

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

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 .

Settings Dashboards

A guide displaying the options available in the Settings section in Umbraco CMS backoffice.

The Settings section of the Umbraco backoffice has its own set of default dashboards. In this article, you can get an overview of each dashboard available in the Settings section:

Welcome

The Welcome dashboard is the first dashboard in the Settings section. Like all dashboards, it has a customizable view and links to different resources for developing your Umbraco website.

For more information about creating custom dashboards, see the Dashboards article.

Examine Management

The Examine Management dashboard provides an overview of the Examine functionality available directly within the Umbraco backoffice. The Umbraco backoffice allows you to view details about your Examine indexes and searchers - all in one place. You can see which fields are being indexed and rebuild the indexes if there's a problem. You can also test keywords to see what results will be returned.

For more information about Examine Management, see the article.

Published Status

The Published Status dashboard displays the status of your site in the Published Cache Status section alongside the Content and Media nodes value. The Caches section provides three options: Memory Cache, Database Cache, and Internals.

Memory Cache - Reloads the in-memory cache by entirely reloading it from the database cache. Use it when you think that the memory cache has not been properly refreshed.
Database Cache - Rebuilds the database cache that is the content of the cmsContentNu

Models Builder

Models builder is a tool that can generate a complete set of strongly-typed published content models for Umbraco. Models are available in both controllers and views. When using the Models Builder, the content cache does not return IPublishedContent objects anymore but returns strongly typed models implementing IPublishedContent.

The Models Builder dashboard displays the following information:

Details on how Models Builder is configured, that is: InMemoryAuto

Health Check

Health Checks are used to determine the status of your Umbraco project. It is a handy list of checks to see if your Umbraco installation is configured according to best practices. It's possible to add your custom-built health checks.

For more information about Health Checks, see the articles.

Profiling

You can use the built-in performance profiler to assess the performance when rendering pages. To activate the profiler for a specific page rendering, add umbDebug=true to the querystring when requesting the page.

The Profiling dashboard provides a toggle option - Activate the profiler by default to keep the profiler active by default for all page renderings. You can use this option without having to set umbDebug=true on each page request. The toggle button sets a cookie named UMB-DEBUG in your browser, which then activates the profiler automatically.

For more information about MiniProfiler, see the section in the article.

Telemetry Data

The Telemetry Data dashboard is a consent screen that is used for collecting system and usage information from your installation. Here, you can see what type of data is being collected and even adjust the level of reporting. Currently, there are three levels available: Minimal, Basic, and Detailed.

Detailed is the default option where the data sent contains:

Anonymized site ID, Umbraco version, and packages installed.

Language Variants

Learn how to use language variants to output your content in multiple languages.

Language Variants allows you to vary content by culture, so you can allow a content node to exist in multiple languages.

This article will cover the different aspects of enabling and working with language variants on your Umbraco website.

Video tutorial

Video tutorial

How to enable Language Variants

To work with Language Variants you need to have more than one language enabled. This can be done from the Settings section:

You will always have one default language but each language can be set to mandatory.

Enabling Language Variants on Document Types

Now that there are two languages to vary the content with, it needs to be enabled on the Document Types. To do so:

Go to the Document Type in the structure section.
Open the settings page.
Toggle Allow vary by culture.

To allow a property on the Document Type to be varied it will have to be enabled for the property:

Working with Language Variants on content

When you return to your content node you will notice two things:

At the top of the Content tree there will now be a dropdown so you can show the Content tree in the language of your choice.
To the right of the content name there is now a dropdown where you can select a language. You can also open a split view so you can see two languages at once.

To read about how you render variant content in Templates, check out the .

Test your language variants

Culture and hostnames must be added to your language sites before the content can be tested for variants:

Click ... next to the Home node and select Culture and Hostnames.
Add a specific URL per language and save. For eg: An English language variant with English (United States) as the language can be given a specific URL https://yourwebsite.com/en-us and a Danish language variant can be given a specific URL https://yourwebsite.com/dk.

The Info content app should now show specific URLs for your language variants.

Control User Group permissions on language variants

This feature is available from Umbraco version 10.2.

When you are working with a multilingual site you might want to control who can edit the different variations of the content on the website.

This can be controlled on a User Group level. All default User Groups, except the Sensitive data group, have access to all languages out of the box.

When "Allow access to all languages" is not checked, languages can be added and/or removed. This is to determine which variants the users in the user group have access to.

Even though the language permissions have been set, a user will still be able to view and browse all the language variations. The permission setting will ensure that only the added languages are editable by users of the User Group.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:40264",
      "sslPort": 44360
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "Umbraco.Web.UI.NetCore": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "https://localhost:44360;http://localhost:40264"
    }
  }
}

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iis": {
      "applicationUrl": "https://testsite.local",
      "sslPort": 0
    },
    "iisExpress": {
      "applicationUrl": "http://localhost:40264",
      "sslPort": 44360
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS": {
      "commandName": "IIS",
      "launchBrowser": true,
      "launchUrl": "https://testsite.local",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "Umbraco.Web.UI.NetCore": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "https://localhost:44360;http://localhost:40264"
    }
  }
}

{
    "Umbraco": {
        "CMS": {
            "Global": {
                "MainDomLock" : "FileSystemMainDomLock"
            },
            "Hosting": {
                "LocalTempStorageLocation": "EnvironmentTemp"
            },
            "Examine": {
                "LuceneDirectoryFactory": "SyncedTempFileSystemDirectoryFactory"
            }
        }
    }
}

{
  "name": "UMBRACO__CMS__Global__MainDomLock",
  "value": "FileSystemMainDomLock",
  "slotSetting": false
},
{
  "name": "UMBRACO__CMS__Hosting__LocalTempStorageLocation",
  "value": "EnvironmentTemp",
  "slotSetting": false
},
{
  "name": "UMBRACO__CMS__Examine__LuceneDirectoryFactory",
  "value": "SyncedTempFileSystemDirectoryFactory",
  "slotSetting": false
}

using System.Text.Json.Serialization;

namespace UmbracoProject;

public class TimeOnlyValue
{
    /// <summary>
    /// The time value, represented as a <see cref="DateTimeOffset"/> for storage compatibility.
    /// </summary>
    [JsonPropertyName("date")]
    public DateTimeOffset Date { get; init; }
}

DateTime dateTime = DateTime.Now; // Your existing DateTime value
TimeOnly timeOnly = TimeOnly.FromDateTime(dateTime);
DateTimeOffset dateTimeOffset = new DateTimeOffset(DateOnly.MinValue, timeOnly, TimeSpan.Zero);

@{
    int students = Model.HasValue("students") ? Model.Value<int>("students") : 0;
    int teachers = Model.HasValue("teachers") ? Model.Value<int>("teachers") : 0;
    int totalTravellers = students + teachers;

    <p>@totalTravellers</p>
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 'students'
    content.SetValue("students", 20);
    
    // Save the change
    ContentService.Save(content);

}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'students'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.Students).Alias, 20);
}

@{
    if (Model.Value<string[]>("keyFeatureList").Length > 0)
    {
        <ul>
            @foreach (var item in Model.Value<string[]>("keyFeatureList"))
            {
                <li>@item</li>
            }
        </ul>
    }
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 'keyFeatureList'
    content.SetValue("keyFeatureList", "Awesome" + Environment.NewLine + "Super");

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'keyFeatureList'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.KeyFeatureList).Alias, "Awesome" + Environment.NewLine + "Super");
}

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

@using Umbraco.Cms.Core.Serialization
@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@inject IJsonSerializer Serializer
@{
    // 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 'superHeroes'.
    content.SetValue("superHeroes", Serializer.Serialize(new[] { "Umbraco", "CodeGarden"}));

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'superHeroes'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.SuperHeroes).Alias, Serializer.Serialize(new[] { "Umbraco", "CodeGarden"}));
}

@using Umbraco.Cms.Core
@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 document 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);
}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'featurePicker'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.FeaturePicker).Alias, udi.ToString());
}

@{
    // Perform an null-check on the field with alias 'pageTitle'
    if (Model.HasValue("pageTitle")){
        // Print the value of the field with alias 'pageTitle'
        <p>@(Model.Value("pageTitle"))</p>
    }
}

@{
    // Perform an null-check on the field with alias 'pageTitle'
    @if (!Model.HasValue(Model.PageTitle))
    {
        // Print the value of the field with alias 'pageTitle'
        <p>@Model.PageTitle</p>
    }
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 'pageTitle'
    content.SetValue("pageTitle", "Umbraco Demo");

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'pageTitle'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.PageTitle).Alias, "Umbraco Demo");
}

using System.Text.Json.Serialization;

namespace UmbracoProject;

public class DateOnlyValue
{
    /// <summary>
    /// The date value, represented as a <see cref="DateTimeOffset"/> for storage compatibility.
    /// </summary>
    [JsonPropertyName("date")]
    public DateTimeOffset Date { get; init; }
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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

    // Create a variable for the desired value
    var htmlValue = new HtmlString("Add some text <strong>here</strong>");

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

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'richText'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.RichText).Alias, htmlValue);
}

@using Umbraco.Cms.Core.Services;
@inject IUserService UserService;
@{
    
    if (Model.Value("userPicker") != null)
    {
        var us = UserService;
        var username = us.GetUserById(Model.Value<int>("userPicker")).Name;

        <p>This is the chosen person: @username</p>
        <p>This returns the id value of chosen person: @Model.Value("userPicker")</p>
    }
}

@using Umbraco.Cms.Core.Services;
@inject IUserService UserService;
@{
    if (Model.UserPicker != null)
    {

        var us = UserService;
        var user = us.GetUserById((int)Model.UserPicker);

        <p>This is the chosen person: @user.Name</p>
        <p>This returns the id value of chosen person: @user.Id)</p>
    }
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");
    
    // 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 'userPicker'. The value is the specific ID of the user
    content.SetValue("userPicker", -1);
            
    // Save the change
    ContentService.Save(content);
}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'userPicker'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.UserPicker).Alias, -1);
}

Nothing

SourceCodeAuto

SourceCodeManual

Scripts (.js files)

EditorUiAlias

IJsonSerializer

IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found");

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

// Save the change
_contentService.Save(content);

IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found");

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

// Save the change
_contentService.Save(content);

{
  "ConnectionStrings": {
    "umbracoDbDSN": "Data Source=|DataDirectory|/Umbraco.sqlite.db;Cache=Shared;Foreign Keys=True;Pooling=True",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.Sqlite"
  }
}

{
  "Umbraco": {
    "CMS": {
      "Unattended": {
        "InstallUnattended": true,
        "UnattendedUserName": "FRIENDLY_NAME",
        "UnattendedUserEmail": "EMAIL",
        "UnattendedUserPassword": "PASSWORD",
        "UnattendedTelemetryLevel": "Detailed"
      }
    }
  }
}

Umbraco__CMS__Unattended__InstallUnattended
Umbraco__CMS__Unattended__UnattendedUserName
Umbraco__CMS__Unattended__UnattendedUserEmail
Umbraco__CMS__Unattended__UnattendedUserPassword
Umbraco__CMS__Unattended__UnattendedTelemetryLevel

{
    "ConnectionStrings": {
        "umbracoDbDSN": "server=localhost;database=UmbracoUnicore;user id=sa;password='P@ssw0rd'"
    },
    "Umbraco": {
        "CMS": {
            "Unattended": {
                "InstallUnattended": true,
                "UnattendedUserName": "FRIENDLY_NAME",
                "UnattendedUserEmail": "EMAIL",
                "UnattendedUserPassword": "PASSWORD",
                "UnattendedTelemetryLevel": "Detailed"
            }
        }
    }
}

dotnet new umbraco -n MyNewProject --friendly-name "Friendly User" --email [email protected] --password password1234 --telemetry-level Detailed --connection-string "Server=(localdb)\Umbraco;Database=MyDatabase;Integrated Security=true" --version 10.0.0

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Infrastructure.Runtime.RuntimeModeValidators;

namespace MySite;

public class DockerChecksRemover : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.RuntimeModeValidators().Remove<UseHttpsValidator>();
}

{
  "name": "UMBRACO__CMS__Global__MainDomLock",
  "value": "FileSystemMainDomLock",
  "slotSetting": false
},
{
  "name": "UMBRACO__CMS__Hosting__LocalTempStorageLocation",
  "value": "EnvironmentTemp",
  "slotSetting": false
},
{
  "name": "UMBRACO__CMS__Examine__LuceneDirectoryFactory",
  "value": "TempFileSystemDirectoryFactory",
  "slotSetting": false
}

@using Umbraco.Cms.Core.Models
@{
    var links = Model.Value<IEnumerable<Link>>("footerLinks");
    if (links.Any())
    {
        <ul>
            @foreach (var link in links)
            {
                <li><a href="@link.Url" target="@link.Target">@link.Name</a></li>
            }
        </ul>
    }
}

@{
    var links = Model.FooterLinks;
    if (links.Any())
    {
        <ul>
            @foreach (var link in links)
            {
                <li><a href="@link.Url" target="@link.Target">@link.Name</a></li>
            }
        </ul>
    }
}

@using Umbraco.Cms.Core
@using Umbraco.Cms.Core.Serialization
@using Umbraco.Cms.Core.Services
@using Umbraco.Cms.Core.Models
@inject IContentService ContentService
@inject IJsonSerializer Serializer
@{
    // 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 media you want to assign to the footer links property 
    var media = Umbraco.Media("bca8d5fa-de0a-4f2b-9520-02118d8329a8");

    // Create an Udi of the media
    var mediaUdi = Udi.Create(Constants.UdiEntityType.Media, media.Key);

    // Get the content you want to assign to the footer links property 
    var contentPage = Umbraco.Content("665d7368-e43e-4a83-b1d4-43853860dc45");

    // Create an Udi of the Content
    var contentPageUdi = Udi.Create(Constants.UdiEntityType.Document, contentPage.Key);

    // Create a list with different link types
    var externalLinks = new List<Link>
    {
        // External Link
        new Link
        {
            Target = "_blank",
            Name = "Our Umbraco",
            Url = "https://our.umbraco.com/",
            Type = LinkType.External
        },
        // Media 
        new Link
        {
            Target = "_self",
            Name = media.Name,
            Url = media.MediaUrl(),
            Type = LinkType.Media,
            Udi = mediaUdi
        }, 
        // Content 
        new Link
        {
            Target = "_self",
            Name = contentPage.Name,
            Url = contentPage.Url(),
            Type = LinkType.Content,
            Udi = contentPageUdi
        }
    };

    // Serialize the list with links to JSON
    var links = Serializer.Serialize(externalLinks);


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

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'footerLinks'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.FooterLinks).Alias, links);
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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

    // Create markdown value
    var markdownValue = new HtmlString("#heading  \n**strong text**");
    
    // Set the value of the property with alias 'myMarkdownEditor'. 
    content.SetValue("myMarkdownEditor", markdownValue);

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'myMarkdownEditor'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.MyMarkdownEditor).Alias, markdownValue);
}

@using System.Net
@using Umbraco.Cms.Core
@using Umbraco.Cms.Core.Services
@using Umbraco.Cms.Core.PropertyEditors
@using Umbraco.Cms.Core.IO
@using Umbraco.Cms.Core.Serialization
@using Umbraco.Cms.Core.Strings
@inject MediaFileManager MediaFileManager
@inject IShortStringHelper ShortStringHelper
@inject IContentTypeBaseServiceProvider ContentTypeBaseServiceProvider
@inject IContentService ContentService
@inject IMediaService MediaService
@inject IJsonSerializer Serializer
@inject MediaUrlGeneratorCollection MediaUrlGeneratorCollection
@{
    // Create a variable for the GUID of the parent where you want to add a child item
    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

    // Create a variable for the file you want to upload, in this case the Our Umbraco logo
    var imageUrl = "https://our.umbraco.com/assets/images/logo.svg";

    // Create a request to get the file
    var request = WebRequest.Create(imageUrl);
    var webResponse = request.GetResponse();
    var responseStream = webResponse.GetResponseStream();

    // Get the file name 
    var lastIndex = imageUrl.LastIndexOf("/", StringComparison.Ordinal) + 1;
    var filename = imageUrl.Substring(lastIndex, imageUrl.Length - lastIndex);

    // Create a media file
    var media = MediaService.CreateMediaWithIdentity("myImage", -1, "File");
    media.SetValue(MediaFileManager, MediaUrlGeneratorCollection, ShortStringHelper, ContentTypeBaseServiceProvider, Constants.Conventions.Media.File, filename, responseStream);
    // Save the created media 
    MediaService.Save(media);

    // Get the published version of the media (IPublishedContent)
    var publishedMedia = Umbraco.Media(media.Id);

    // Set the value of the property with alias 'myFile' 
    content.SetValue("myFile", publishedMedia.Url());

    // Save the child item
    ContentService.Save(content);
}

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'myFile'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.MyFile).Alias, publishedMedia.Url();
}

@if (Model.HasValue("singleValueSlider"))
{
    var value = Model.Value<decimal>("singleValueSlider");
    <p>@value</p>
}

@if (Model.HasValue("multiValueSlider"))
{
    var value = Model.Value<Umbraco.Cms.Core.Models.Range<decimal>>("multiValueSlider");
    <p>@(value.Minimum) and @(value.Maximum)</p>
}

// with a range off
@if (Model.SingleValueSlider != null)
{
    var value = Model.SingleValueSlider;
    <p>@value</p>
}

// with a range on
@if (Model.MultiValueSlider != null)
{
    var minValue = Model.MultiValueSlider.Minimum;
    var maxValue = Model.MultiValueSlider.Maximum;
    <p>@minValue and @maxValue</p>
}

@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 'singleValueSlider'. 
    content.SetValue("singleValueSlider", 10);

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

@using Umbraco.Cms.Core.Models
@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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

    // Create a variable for the desired value of the 'multiValueSlider' property
    var range = new Range<decimal> {Minimum = 10, Maximum = 12};

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

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'singleValueSlider'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.SingleValueSlider).Alias, 10);

    // Set the value of the property with alias 'multiValueSlider'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.MultiValueSlider).Alias, new Range<decimal> {Minimum = 10, Maximum = 12});
}

@using Umbraco.Cms.Core.Serialization
@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@inject IJsonSerializer Serializer
@{
    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("9daf8585-6ab6-4ac2-98f0-28bf83aeea6e");

    // 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 'tags'. 
    content.SetValue("tags", Serializer.Serialize(new[] { "News", "Umbraco", "Example", "Setting Tags", "Helper" }));

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'tags'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.Tags).Alias, Serializer.Serialize(new[] {  "News", "Umbraco", "Example", "Setting Tags" }));
}

umbraco-package.json

{
    "name": "My.Editors",
    "version": "1.0.0",
    "extensions": [
        {
            "type": "propertyEditorUi",
            "alias": "My.Editor.Alias",
            (...)
            "meta": {
                "propertyEditorSchemaAlias": "Umbraco.Plain.String",
                (...)
            }
        }
    ]
}

IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found");

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

// Save the change
_contentService.Save(content);

using System.Text.Json.Serialization;

namespace UmbracoProject;

public class DateTimeUnspecified
{
    /// <summary>
    /// The date and time value, represented as a <see cref="DateTimeOffset"/> for storage compatibility.
    /// </summary>
    [JsonPropertyName("date")]
    public DateTimeOffset Date { get; init; }
}

import { UmbTiptapExtensionApiBase } from '@umbraco-cms/backoffice/tiptap';
import { Highlight } from '@tiptap/extension-highlight';

export default class UmbTiptapHighlightExtensionApi extends UmbTiptapExtensionApiBase {
    getTiptapExtensions = () => [Highlight];
}

import { UmbTiptapToolbarElementApiBase } from '@umbraco-cms/backoffice/tiptap';
import type { Editor } from '@umbraco-cms/backoffice/external/tiptap';

export default class UmbTiptapToolbarHighlightExtensionApi extends UmbTiptapToolbarElementApiBase {
    override execute(editor?: Editor) {
        editor?.chain().focus().toggleHighlight().run();
    }
}

manifests.ts

export const manifests: Array<UmbExtensionManifest> = [
    {
        type: 'tiptapExtension',
        kind: 'button',
        alias: 'My Highlight Tiptap Extension',
        name: 'My.Tiptap.Highlight',
        api: () => import('./highlight.tiptap-api.js'),
        meta:{
            icon: "icon-thumbnail-list",
            label: "Highlight",
            group: "#tiptap_extGroup_formatting"
        }
    },
    {
        type: 'tiptapToolbarExtension',
        kind: 'button',
        alias: 'My.Tiptap.Toolbar.Highlight',
        name: 'My Highlight Tiptap Toolbar Extension',
        js: () => import('./highlight.tiptap-toolbar-api.js'),
        forExtensions: ["My.Tiptap.Highlight"],
        meta:{
            alias: "highlight",
            icon: "icon-brush",
            label: "Highlight"
        }
    }
]

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

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:

You use cloud based auto-scaling appliances like
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

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 tasks:

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:

Recommended: by creating a custom IServerRegistrar, this means the front-end servers will never be used as the SchedulingPublisher server role.
Set the UmbracoApplicationUrl property in the

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:

- You use cloud based auto-scaling appliances like
- 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)

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.

ASP.NET Core supports multiple ways to share keys. Use the to find a description that fits your setup the best.

Session State and Distributed Cache

It is required to setup a distributed cache, like DistributedSqlServerCache or an alternative provider (see for more details). The distributed cache is used by the session in your application, which is used by the default TempDataProvider in MVC.

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.

Find steps on how to enable the feature for a load balanced setup in the article.

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.

Umbraco Training

Media Picker

Schema Alias: Umbraco.MediaPicker3

UI Alias: Umb.PropertyEditorUi.MediaPicker

Returns: IEnumerable<MediaWithCrops> or MediaWithCrops

This property editors returns one of the following:

A collection (IEnumerable<MediaWithCrops>) if the Pick multiple items setting is enabled.
A single MediaWithCrops item if the Pick multiple items setting is disabled.

Data Type Definition Example

Accepted types

Use setting to limit the picker to only select Media Items of these types.

Pick multiple items

Use this setting to enable the property to contain multiple items. When this is enabled the property editor returns an IEnumerable<MediaWithCrops>.

You can still set the maximum amount to 1. Do so when you want to retrieve a collection but only allow the Content Editors to select one Media Item.

Amount

Use this setting to enforce a minimum and/or maximum amount of selected Media Items.

It is not possible to set a maximum amount when the "Pick multiple items" feature is disabled.

Start node

This setting is used to limit the Media Picker to certain parts of the Media Tree.

Ignore user start nodes

Use this setting to overrule user permissions, to enable any user of this property to pick any Media Item of the chosen Start node.

When this setting is enabled, a user can access the media available under the selected "Start Node" (/Design in this case). This applies even if they normally lack access. The access is granted specifically when using this particular Media Picker.

Enable Focal Point

Enable the focal point setter, do only enable this if the focal point is used or if you have Image crops defined.

Image Crops

Define local image crops. Local image crop data is stored on the document in this property. This means it can differentiate between documents.

This is different from Global crops as they are defined on the Media Item, making the crops shared between all usage of that Media Item.

Global crops are configured on the Image Cropper property of the Image Media Type

Content Example

MVC View Example

Multiple enabled without Models Builder

Multiple enabled without Models Builder to retrieve IEnumerable data

While MediaWithCrops is the default return type, IPublishedContent may be used in backward-compatible implementations or when working directly with core APIs.

Multiple enabled with Models Builder

Multiple disabled without Models Builder

Multiple disabled with Models Builder

Using crops

Both local and global crops are retrieved using the method GetCropUrl. If crops with identical aliases are defined both locally and globally, the locally defined crops are always prioritized by GetCropUrl.

The following is an example of how to retrieve a crop from a MediaWithCrops entry:

Explicitly retrieving global crops

You can retrieve globally defined crops explicitly by using GetCropUrl on the UrlHelper:

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 .

The following sample will update a single image in a Media Picker.

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

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

using System.Text.Json.Serialization;

namespace UmbracoProject;

public class DateTimeWithTimeZone
{
    /// <summary>
    /// The date and time value, represented as a <see cref="DateTimeOffset"/>.
    /// </summary>
    [JsonPropertyName("date")]
    public DateTimeOffset Date { get; init; }

    /// <summary>
    /// The identifier of the time zone to pre-select in the editor. E.g., "Europe/Copenhagen".
    /// </summary>
    [JsonPropertyName("timeZone")]
    public string TimeZone { get; init; }
}

IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found");

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

// Save the change
_contentService.Save(content);

@if (Model.HasValue("categories"))
{
    var categories = Model.Value<IEnumerable<string>>("categories");
    <ul>
        @foreach (var category in categories)
        {
            <li>@category</li>
        }
    </ul>
}

@using Umbraco.Cms.Core.Serialization
@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@inject IJsonSerializer Serializer
@{
    // 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 'categories'. 
    content.SetValue("categories", Serializer.Serialize(new[] { "News" }));

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'categories'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.Categories).Alias, Serializer.Serialize(new[] { "News" }));
}

umbraco-package.json

{
  "name": "Document Type Localization",
  "extensions": [
    {
      "type": "localization",
      "alias": "DocumentType.Localize.En",
      "name": "English",
      "meta": {
        "culture": "en"
      },
      "js": "/App_Plugins/DocumentTypeLocalization/doctype-en.js"
    }
  ]
}

doctype-en.js

export default {
    contentTypes: {
        article: 'Article page',
        'article-desc': 'A textual, article-like page on the site. Use this as the main type of content.',
        landing: 'Landing page',
        'landing-desc': 'An inviting, very graphical page. Use this as an entry point for a campaign, and supplement with Article pages.'
    },
    tabs: {
        content: 'Page content',
        seo: 'SEO configuration',
    },
    groups: {
        titles: 'Page titles'
    },
    properties: {
        title: 'Main title',
        'title-desc': 'This is the main title of the page.',
        'title-message': 'The main title is required for this page.',
        subTitle: 'Sub title',
        'subTitle-desc': 'This is the sub title of the page.',
    }
};

@using Umbraco.Cms.Core.Models
@{
    var typedMultiMediaPicker = Model.Value<IEnumerable<MediaWithCrops>>("medias");
    foreach (var entry in typedMultiMediaPicker)
    {
        <img src="@entry.MediaUrl()" style="width:200px" />
    }
}

@using Umbraco.Cms.Core.Models
@{
    var listOfImages = Model.Value<IEnumerable<IPublishedContent>>("medias");
    foreach (var image in listOfImages)
    {
        <img src="@image.Url()" alt="@image.Name" />
    }
}

@using Umbraco.Cms.Core.Models
@{
    var typedMediaPickerSingle = Model.Value<MediaWithCrops>("media");
    if (typedMediaPickerSingle != null)
    {
        <img src="@typedMediaPickerSingle.MediaUrl()" style="width:200px" alt="@typedMediaPickerSingle.Value("alt")" />
    }
}

@using Umbraco.Cms.Core.Models
@{
    var typedMediaPickerSingle = Model.Media;
    if (typedMediaPickerSingle is MediaWithCrops mediaEntry)
    {
        <img src="@mediaEntry.MediaUrl()" style="width:200px"/>
    }
}

@using Umbraco.Cms.Core
@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 media you want to assign to the media picker 
    var media = Umbraco.Media("bca8d5fa-de0a-4f2b-9520-02118d8329a8");

    // Create an Udi of the media
    var udi = Udi.Create(Constants.UdiEntityType.Media, media.Key);

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

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'featuredBanner'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.FeaturedBanner).Alias, udi.ToString());
}

umbraco-package.json

{
    "name": "Name of your package",
    "alias": "My.Package",
    "extensions": [
        {
            "type": "tiptapToolbarExtension",
            "kind": "styleMenu",
            "alias": "MyCustom.Tiptap.StyleMenu",
            "name": "My Custom Tiptap Style Menu",
            "meta": {
                "alias": "myCustomStyleMenu",
                "icon": "icon-palette",
                "label": "My custom styles"
            },
            "items": [
                {
                    "label": "Headings",
                    "items": [
                        {
                            "label": "Heading 2",
                            "data": { "tag": "h2" },
                            "appearance": { "icon": "icon-heading-2" }
                        },
                        {
                            "label": "Heading 3",
                            "data": { "tag": "h3" },
                            "appearance": { "style": "font-size: large;" }
                        },
                        {
                            "label": "Heading 4",
                            "data": { "tag": "h4" }
                        }
                    ]
                },
                {
                    "label": "Attributes",
                    "items": [
                        {
                            "label": "Classes",
                            "data": { "class": "foo" }
                        },
                        { 
                            "label": "IDs",
                            "data": { "id": "bar" }
                        },
                        {
                            "label": "Mixed",
                            "data": { "tag": "span", "class": "foo", "id": "bar" }
                        }
                    ]
                }
            ]
        }
    ]
}

Image Cropper

Schema Alias: Umbraco.ImageCropper

UI Alias: Umb.PropertyEditorUi.ImageCropper

Returns: MediaWithCrops

Returns a path to an image, along with information about focal point and available crops.

When the Image Cropper is used on a Media Type the crops are shared between all usages of a Media Item. This is called global crops.

If the Image Cropper is used on a Document Type, the file and crops will be local to the Document.

Notice that it is possible make local crops on shared Media Items via the Media Picker Property Editor.

Settings

Define Crops

You can add, edit & delete crop presets the cropper UI can use.

Data Type Definition Example

Content Example

The Image Cropper provides a UI to upload an image, set a focal point on the image, and use predefined crops.

By default, images in the Image Cropper will be shown based on a set focal point and only use specific crops if they are available.

The Image Cropper comes with 3 modes:

Uploading an image
Setting a focal point
Cropping the image to predefined crops

Uploading images

The editor exposes a drop area for files. Select it to upload an image.

Set focal point

By default, the Image Cropper allows the editor to set a focal point on the uploaded image.

All the preset crops are shown to give the editor a preview of what the image will look like on the frontend.

Crop and resize

The editor can fit the crop to the image to ensure that the image is presented as intended.

Powered by ImageSharp.Web

is image processing middleware for ASP.NET.

We bundle this package with Umbraco and you can therefore take full advantage of all its features for resizing and format changing. Learn more about the built in processing commands in .

Sample code

The Image Cropper comes with an API to generate crop URLs. You can also access the raw data directly as a dynamic object.

For rendering a cropped media item, the .GetCropUrl is used:

The third parameter is HtmlEncode and is by default set to true. This means you only need to define the parameter if you want to disable HTML encoding.

Example to output a "banner" crop from a cropper property with the property alias "customCropper"

Or, alternatively using the MediaWithCrops extension method:

Example to dynamically create a crop using the focal point - in this case 300 x 400px image

CSS background example to output a "banner" crop

Set the htmlEncode to false so that the URL is not HTML encoded

Add values programmatically

To update a content property value you need the .

The following sample demonstrates how to add or change the value of an Image Cropper property programmatically. The sample creates an API controller with an action, which must be invoked via a POST request to the URL written above the action.

If you use Models Builder to generate source code (modes SourceCodeAuto or SourceCodeManual), you can use nameof([generated property name]) to access the desired property without using a magic string:

Get all the crop urls for a specific image

Crop URLs are not limited to usage within a view. IPublishedContent has a GetCropUrl extension method, which can be used to access crop URLs anywhere.

The following sample demonstrates how to use GetCropUrl to retrieve URLs for all crops defined on a specific image:

Sample on how to change the format of the image

Below the example to output a PNG using ImageSharp.Web command.

Block List

Schema Alias: Umbraco.BlockList

UI Alias: Umb.PropertyEditorUi.BlockList

Returns: IEnumerable<BlockListItem>

This article is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.

Block List is a list editing property editor, using Element Types to define the list item schema.

The Block List replaces the obsolete Nested Content editor.

Configure Block List

The Block List property editor is configured in the same way as any standard property editor, via the Data Types admin interface.

To set up your Block List Editor property, create a new Data Type and select Block List from the list of available property editors.

Then you will see the configuration options for a Block List as shown below.

The Data Type editor allows you to configure the following properties:

Available Blocks - Here you will define the Block Types to be available for use in the property. Read more on how to set up Block Types below.
Amount - Sets the minimum and/or maximum number of blocks that should be allowed in the list.
Single block mode - When in Single block mode, the output will be BlockListItem<> instead of BlockListModel

Setup Block Types

Block Types are Element Types which need to be created before you can start configuring them as Block Types. This can be done either directly from the property editor setup process, or you can set them up beforehand and add them to the block list after.

Once you have added an element type as a Block Type on your Block List Data Type you will have the option to configure it further.

Each Block has a set of properties that are optional to configure. They are described below.

Editor Appearance

By configuring the properties in the group you can customize the user experience for your content editors when they work with the blocks in the Content section.

Label - Define a label for the appearance of the Block in the editor. The label uses to display values of properties. The label is also used for search in the Add Block dialog during content editing. If no label is defined, the block will not be searchable. The search does not fall back to the block’s name.
Overlay editor size - Set the size for the Content editor overlay for editing this block.

Data Models

It is possible to use two separate Element Types for your Block Types. Its required to have one for Content and optional to add one for Settings.

Content model - This 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 - Add a Settings section to your Block based on a given Element Type. When picked you can open the Element Type or choose to remove the settings section again.

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 - Define a background color to be displayed beneath the icon or thumbnail. Eg. #424242.
Icon color - Change the color of the Element Type icon. Eg. #242424.
Thumbnail - Pick an image or SVG file to replace the icon of this Block in the catalogue.

The thumbnails for the catalogue are presented in the format of 16:10, and we recommend a resolution of 400px width and 250px height.

Advanced

These properties are relevant when you work with custom views.

Force hide content editor - If you made a custom view that enables you to edit the content part of a block and you are using default editing mode (not inline) you might want to hide the content-editor from the block editor overlay.

Editing Blocks

When viewing a Block List editor in the Content section for the first time, you will be presented with the option to Add content.

Clicking the Add content button brings 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 list.

Depending on whether your Block List Editor is setup to use default or inline editing mode you will see one of the following things happening:

In default mode you will enter the editing overlay of that Block:

In inline editing mode the new Blocks will expand to show its inline editor:

More Blocks can be added to the list by clicking the Add content button or using the inline Add content button that appears on hover between or above existing Blocks.

To reorder the Blocks, click and drag a Block up or down to place in the desired order.

To delete a Block click the trash-bin icon appearing on hover.

Rendering Block List Content

Rendering the stored value of your Block List property can be done in two ways.

1. Default rendering

You can choose to use the built-in rendering mechanism for rendering blocks via a Partial View for each block.

The default rendering method is named GetBlockListHtml() and comes with a few options to go with it. The typical use could be:

"MyBlocks" above is the alias for the Block List editor.

If using ModelsBuilder the example can be simplified:

Example:

To make this work you will need to create a Partial View for each block, named by the alias of the Element Type that is being used as Content Model.

These partial views must be placed in this folder: Views/Partials/BlockList/Components/. Example: Views/Partials/BlockList/Components/MyElementTypeAliasOfContent.cshtml.

A Partial View will receive the model of Umbraco.Core.Models.Blocks.BlockListItem. This gives you the option to access properties of the Content and Settings section of your Block.

In the following example of a Partial view for a Block Type, the MyElementTypeAliasOfContentand MyElementTypeAliasOfSettings should correspond with the selected Element Type Alias for the given model in your case.

Example:

With ModelsBuilder:

2. Build your own rendering

A built-in value converter is available to use the data as you like. Call the Value<T> method with a generic type of IEnumerable<BlockListItem> and the stored value will be returned as a list of BlockListItem entities.

Example:

Each item is a BlockListItem entity that contains two main properties Content and Settings. Each of these is a IPublishedElement which means you can use all the value converters you are used to using.

Example:

Extract Block List Content data

In some cases, you might want to use the Block List Editor to hold some data and not necessarily render a view since the data should be presented in different areas on a page. An example could be a product page with variants stored in a Block List Editor.

In this case, you can extract the variant's data using the following, which returns IEnumerable<IPublishedElement>.

Example:

If using ModelsBuilder the example can be simplified:

Example:

If you know the Block List Editor only uses a single block, you can cast the collection to a specific type T using .OfType<T>() otherwise the return value will be IEnumerable<IPublishedElement>.

Build a Custom Backoffice View

Building Custom Views for Block representations in Backoffice is the same for all Block Editors.

Blocks

Blocks enable editors to insert structured content elements directly into the Rich Text Editor (RTE). Blocks are Element Types and can be configured with custom properties, styling, and behavior.

Blocks can be added to the Rich Text Editor when:

Available Blocks are specified as part of the Rich Text Editor Data Type configuration.
The Insert Block toolbar option is enabled in the Rich Text Editor.

Configure Blocks

Blocks are Element Types that must be created before configuring them as blocks in the Rich Text Editor. You can create Element Types in the Settings > Document Types section

Blocks functionality can then be configured through the Rich Text Editor Data Type configuration as follows.

Navigate to Settings > Data Types.
Select your Rich Text Editor Data Type or create a new one.
Locate the Available Blocks section.
Add the Element Types you want to make available as blocks.

Editor Appearance

Configure how blocks appear and behave in the Content section:

Label - Define how the block appears in the editor. Umbraco 16 uses (UFM) syntax for dynamic labels. Use {=propertyAlias} to display property values (e.g., {=author} for a text property containing the name of an author, or Written by: {=author} for a label with static text and dynamic content).
Display Inline - When enabled, blocks remain inline with surrounding text. When disabled, blocks appear on separate lines.
Overlay size

Data Models

Configure the content structure for your blocks:

Content model - The Element Type that defines the main content properties for the block (required).
Settings model - Optional Element Type that defines additional settings or configuration options for the block.

Catalogue Appearance

Control how blocks appear in the block picker:

Background color - Background color displayed behind the block icon or thumbnail.
Icon Color - Color of the Element Type icon.
Thumbnail - Custom image to replace the default Element Type icon.

Working with Blocks

Adding Blocks to Content

Editors can add blocks to rich text content using the Insert Block toolbar button:

Position the cursor where you want to insert the block
Click the Insert Block button in the Rich Text Editor toolbar
Select the desired Block from the available options

The block appears in the editor as a structured element.

Rendering Blocks

To display blocks on the frontend, create Partial Views for each Block.

Rich Text Editor blocks use a different view location than Block List blocks. RTE blocks are placed in Views/Partials/RichText/Components/, while Block List blocks use Views/Partials/BlockList/Components/.

File Structure

Location: Views/Partials/RichText/Components/.
Naming: Use the exact Element Type alias as the filename (e.g., quoteBlock.cshtml for alias quoteBlock).
Model: Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem.

The different folder structure ensures that RTE blocks and Block List blocks can have separate rendering implementations, even when using the same Element Types.

The view filename must match the Element Type alias exactly. If you see the error ArgumentException: ~/Views/Partials/richtext/Components/[filename].cshtml does not match any available view, verify that your view filename matches your Element Type alias precisely.

Example Partial View

For a Block Type with Element Type alias quoteBlock:

Example with Settings Model

For a Call To Action block with Element Type alias callToActionBlock and settings model callToActionBlockSettings:

Type-Safe Rendering with Models Builder

When using Models Builder, specify the Content and Settings models for type-safe access:

Build a Custom Backoffice View

Building Custom Views for Block representations in Backoffice is the same for all Block Editors. .

Best Practices

Content Design

Design blocks for reusable content patterns.
Keep block content focused on a single purpose.
Use descriptive labels that help editors understand the block's function.

Performance

Avoid creating too many Blocks - this can overwhelm content editors.
Use appropriate caching strategies for block rendering.
Consider the impact of complex blocks on editor performance.

Accessibility

Ensure block markup follows accessibility guidelines.
Provide meaningful labels and descriptions.
Test block rendering with screen readers.

Log Viewer

Information on using the Umbraco log viewer

Umbraco ships with a built-in Log Viewer feature. This allows you to filter, view log entries, perform complex search queries, and analyze logs for debugging. You can find the Log viewer in the Settings section of the Umbraco backoffice.

Benefits

Ever needed to find all log entries containing the same request ID? Or locate all logs where a property called Duration exceeds 1000ms?

With structured logging and a query language, you can efficiently search and identify log items for specific scenarios. This helps in debugging and finding patterns in your logs, making it easier to resolve issues.

Example Queries

Here are some example queries to help you get started. For more details on the syntax, see the https://github.com/serilog/serilog-filters-expressions project.

Find all logs that are from the namespace 'Umbraco.Core'StartsWith(SourceContext, 'Umbraco.Core')

Find all logs that have the property 'Duration' and the duration is greater than 1000msHas(Duration) and Duration > 1000

Find all logs where the message has localhost in it with SQL like@Message like '%localhost%'

Saved Searches

If you frequently use a custom query, you can save it for quick access. Type your query in the search box and click the heart icon to save it with a friendly name. Saved queries are stored in the umbracoLogViewerQuery table in the database.

Implementing Your Own Log Viewer Source

Umbraco allows you to implement a custom ILogViewerRepository and ILogViewerService to fetch logs from alternative sources, such as Azure Table Storage.

Creating a Custom Log Viewer Repository

To fetch logs from Azure Table Storage, extend the LogViewerRepositoryBase class from Umbraco.Cms.Infrastructure.Services.Implement.

This implementation requires the Azure.Data.Tables NuGet package.

Azure Table Storage requires entities to implement the ITableEntity interface. Since Umbraco's default log entity does not implement this, a custom entity (AzureTableLogEntity) must be created to ensure logs are correctly fetched.

Creating a custom log viewer service

The next thing to do is create a new implementation of ILogViewerService. Amongst other things, this is responsible for figuring out whether a provided log query is allowed. Again a base class is available.

Register implementations

Umbraco needs to be made aware that there is a new implementation of an ILogViewerRepository and an ILogViewerService. These need to replace the default ones that are shipped with Umbraco.

Configuring Logging to Azure Table Storage

With the above three classes, the setup is in place to view logs from an Azure Table. However, logs are not yet persisted into the Azure Table Storage account. To enable persistence, configure the Serilog logging pipeline to store logs in Azure Table Storage.

Install Serilog.Sinks.AzureTableStorage from NuGet.
Add a new sink to appsettings.json with credentials to persist logs to Azure.

The following sink needs to be added to the array.

For more in-depth information about logging and how to configure it, see the article.

Compact Log Viewer - Desktop App

. A desktop tool is available for viewing and querying JSON log files in the same way as the built-in Log Viewer in Umbraco.

appsettings.json

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

{
    "Umbraco": {
        "CMS": {
            "Runtime": {
                "Mode" : "Development"
            },
            "ModelsBuilder":{
                "ModelsMode": "SourceCodeAuto"
            }
        }
    }
}

{
  "Umbraco": {
    "CMS": {
      "Runtime": {
        "Mode": "Production"
      },
      "Hosting": {
        "Debug": false
      },
      "Global": {
        "UseHttps": true
      },
      "ModelsBuilder": {
        "ModelsMode": "Nothing"
      },
      "WebRouting": {
        "UmbracoApplicationUrl": "https://<REPLACE_WITH_YOUR_PRIMARY_DOMAIN>/"
      }
    }
  }
}

using System.Diagnostics.CodeAnalysis;
using Microsoft.Extensions.Options;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Configuration.Models;
using Umbraco.Cms.Infrastructure.Runtime;
using Umbraco.Cms.Infrastructure.Runtime.RuntimeModeValidators;

public class RuntimeModeValidatorComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.RuntimeModeValidators()
            .Remove<UmbracoApplicationUrlValidator>()
            .Add<DisableElectionForSingleServerValidator>();
}

public class DisableElectionForSingleServerValidator : IRuntimeModeValidator
{
    private readonly IOptionsMonitor<GlobalSettings> _globalSettings;

    public DisableElectionForSingleServerValidator(IOptionsMonitor<GlobalSettings> globalSettings) => _globalSettings = globalSettings;

    public bool Validate(RuntimeMode runtimeMode, [NotNullWhen(false)] out string? validationErrorMessage)
    {
        if (runtimeMode == RuntimeMode.Production && _globalSettings.CurrentValue.DisableElectionForSingleServer == false)
        {
            validationErrorMessage = "Disable primary server election (and support for load balancing) to improve startup performance.";
            return false;
        }

        validationErrorMessage = null;
        return true;
    }
}

Templates                    Short Name               Language          Tags
------------------------------------------------------------------------------------------------------
Umbraco Project              umbraco                  [C#]              Web/CMS/Umbraco
Umbraco Extension            umbraco-extension        [C#]              Web/CMS/Umbraco/Extension/Plugin/Razor Class Library
Umbraco Docker Compose       umbraco-compose                            Web/CMS/Umbraco

Umbraco Project (C#)
Author: Umbraco HQ
Description: An empty Umbraco project ready to get started.

Usage:
  dotnet new umbraco [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template
                          creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <project>        Specifies the template type to instantiate.

Template options:
  -r, --release <Latest|LTS>                 The Umbraco release to use, either latest or latest long term supported
                                             Type: choice
                                               Latest  The latest umbraco release
                                               LTS     The most recent long term supported version
                                             Default: Latest
  --use-https-redirect                       Adds code to Startup.cs to redirect HTTP to HTTPS and enables the UseHttps setting.
                                             Type: bool
                                             Default: false
  -da, --use-delivery-api                    Enables the Delivery API
                                             Type: bool
                                             Default: false
  --add-docker                               Adds a docker file to the project.
                                             Type: bool
                                             Default: false
  --no-restore                               If specified, skips the automatic restore of the project on create.
                                             Type: bool
                                             Default: false
  --exclude-gitignore                        Whether to exclude .gitignore from the generated template.
                                             Type: bool
                                             Default: false
  --minimal-gitignore                        Whether to only include minimal (Umbraco specific) rules in the .gitignore.
                                             Type: bool
                                             Default: false
  --connection-string <connection-string>    Database connection string used by Umbraco.
                                             Type: string
  --connection-string-provider-name          Database connection string provider name used by Umbraco.
  <connection-string-provider-name>          Type: string
                                             Default: Microsoft.Data.SqlClient
  --development-database-type <choice>       Database type used by Umbraco for development.
                                             Type: choice
                                               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 <friendly-name>            Used to specify the name of the default admin user when using unattended install on
                                             development (stored as plain text).
                                             Type: string
  --email <email>                            Used to specify the email of the default admin user when using unattended install on
                                             development (stored as plain text).
                                             Type: string
  --password <password>                      Used to specify the password of the default admin user when using unattended install on
                                             development (stored as plain text).
                                             Type: string
  --telemetry-level <telemetry-level>        Used to specify the level of telemetry the installation will report (Minimal, Basic or Detailed).
                                             Type: string
  --no-nodes-view-path <no-nodes-view-path>  Path to a custom view presented with the Umbraco installation contains no published
                                             content.
                                             Type: string
  -dm, --development-mode <choice>           Choose the development mode to use for the project.
                                             Type: choice
                                               BackofficeDevelopment  Enables backoffice development, allowing you to develop from
                                             within the backoffice, this is the default behaviour.
                                               IDEDevelopment         Configures appsettings.Development.json to Development runtime
                                             mode and SourceCodeAuto models builder mode, and configures appsettings.json to
                                             Production runtime mode, Nothing models builder mode, and enables UseHttps
                                             Default: BackofficeDevelopment
  -mm, --models-mode <choice>                Choose the models builder mode to use for the project. When development mode is set to
                                             IDEDevelopment this only changes the models builder mode appsetttings.development.json
                                             Type: choice
                                               Default           Let DevelopmentMode determine the models builder mode.
                                               InMemoryAuto      Generate models in memory, automatically updating when a content
                                             type change, this means no need for app rebuild, however models are only available in
                                             views.
                                               SourceCodeManual  Generate models as source code, only updating when requested
                                             manually, this means a interaction and rebuild is required when content type(s) change,
                                             however models are available in code.
                                               SourceCodeAuto    Generate models as source code, automatically updating when a
                                             content type change, this means a rebuild is required when content type(s) change,
                                             however models are available in code.
                                               Nothing           No models are generated, this is recommended for production assuming
                                             generated models are used for development.
                                             Default: Default
  -sk, --starter-kit <choice>                Choose a starter kit to install.
                                             Type: choice
                                               None                   No starter kit.
                                               Umbraco.TheStarterKit  The Umbraco starter kit.
                                             Default: None

Remove the EnableCanvasEditing element

<plugins>
    <plugin loadOnFrontend="true">code</plugin>
    <plugin loadOnFrontend="true">paste</plugin>
    <plugin loadOnFrontend="true">umbracolink</plugin>
    <plugin loadOnFrontend="true">anchor</plugin>
    <plugin loadOnFrontend="true">charmap</plugin>
    <plugin loadOnFrontend="true">table</plugin>
    <plugin loadOnFrontend="true">lists</plugin>
</plugins>

@if (Model.Photo is not null)
{
    var cropUrl = Url.GetCropUrl(Model.Photo, "square", false);
    <style>
        .myCssClass {
            background-image: url("@cropUrl");
            height: 400px;
            width: 400px;
        }
    </style>
    <div class="product-image-container myCssClass"></div>
}

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.PropertyEditors.ValueConverters;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Services;

namespace Umbraco.Docs.Samples.Web.Property_Editors_Add_Values;

[ApiController]
[Route("/umbraco/api/createimagecroppervalues")]
public class CreateImageCropperValuesController : Controller
{
    private readonly IContentService _contentService;
    private readonly IMediaService _mediaService;
    private readonly MediaUrlGeneratorCollection _mediaUrlGeneratorCollection;
    private readonly IJsonSerializer serializer;

    public CreateImageCropperValuesController(
        IContentService contentService,
        IMediaService mediaService,
        MediaUrlGeneratorCollection mediaUrlGeneratorCollection, IJsonSerializer serializer)
    {
        _contentService = contentService;
        _mediaService = mediaService;
        _mediaUrlGeneratorCollection = mediaUrlGeneratorCollection;
        this.serializer = serializer;
    }

    // /Umbraco/Api/CreateImageCropperValues/CreateImageCropperValues
    [HttpPost("createimagecroppervalues")]
    public ActionResult<bool> CreateImageCropperValues()
    {
        // Create a variable for the GUID of the page you want to update
        var contentKey = Guid.Parse("89974f8b-e213-4c32-9f7a-40522d87aa2f");

        // Get the page using the GUID you've defined
        IContent? content = _contentService.GetById(contentKey);
        if (content == null)
        {
            return false;
        }

        // Create a variable for the GUID of the media item you want to use
        var mediaKey = Guid.Parse("b6d4e98a-07c0-45f9-bfcc-52994f2806b6");

        // Get the desired media file
        IMedia? media = _mediaService.GetById(mediaKey);
        if (media == null)
        {
            return false;
        }

        // Create a variable for the image cropper and set the source
        var imageCropperValue = new ImageCropperValue
        {
            Src = media.GetUrl("umbracoFile", _mediaUrlGeneratorCollection)
        };

        // Serialize the image cropper value
        var propertyValue = serializer.Serialize(imageCropperValue);

        // Set the value of the property with alias "cropper"
        // - remember to add the "culture" parameter if "cropper" is set to vary by culture
        content.SetValue("cropper", propertyValue);

        return _contentService.Save(content).Success;
    }
}

// Set the value of the "Cropper" property on content of type MyContentType
// - remember to add the "culture" parameter if "cropper" is set to vary by culture
content.SetValue(nameof(MyContentType.Cropper).ToFirstLowerInvariant(), propertyValue);

public Dictionary<string, string> GetCropUrls(IPublishedContent image)
{
    // Get the Image Cropper property value for property with alias "umbracoFile"
    ImageCropperValue? imageCropperValue = image.Value<ImageCropperValue>("umbracoFile");
    if (imageCropperValue?.Crops == null)
    {
        return new Dictionary<string, string>();
    }

    // Return all crop aliases and their corresponding crop URLs as a dictionary
    var cropUrls = new Dictionary<string, string>();
    foreach (ImageCropperValue.ImageCropperCrop crop in imageCropperValue.Crops)
    {
        // Get the cropped URL and add it to the dictionary that I will return
        var cropUrl = crop.Alias != null
            ? image.GetCropUrl(crop.Alias)
            : null;
        if (cropUrl != null)
        {
            cropUrls.Add(crop.Alias!, cropUrl);
        }
    }

    return cropUrls;
}

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockListItem>;
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;
@{
    var content = (ContentModels.MyElementTypeAliasOfContent)Model.Content;
    var settings = Model.Settings as ContentModels.MyElementTypeAliasOfContent; // Cast Model.Settings safely using 'as' to avoid null reference exceptions
}

@* Output the value of field with alias 'heading' from the Element Type selected as Content section *@
<h1>@content.Value("heading")</h1>

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage;
@using Umbraco.Cms.Core.Models.Blocks;
@{
    var blocks = Model.Value<IEnumerable<BlockListItem>>("myBlocksProperty");
    foreach (var block in blocks)
    {
        var content = block.Content;

        @Html.Partial("MyFolderOfBlocks/" + content.ContentType.Alias, block)
    }
}

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage;
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;
@using Umbraco.Cms.Core.Models.Blocks;
@{
    var blocks = Model.Value<IEnumerable<BlockListItem>>("myBlocksProperty");
    foreach (var block in blocks)
    {
        var content = (ContentModels.MyAliasOfContentElementType)block.Content;
        var settings = (ContentModels.MyAliasOfSettingsElementType)block.Settings;

        <h1>@content.MyExampleHeadlinePropertyAlias</h1>
    }
}

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage;
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;
@using Umbraco.Cms.Core.Models.Blocks;
@{
    var variants = Model.Value<IEnumerable<BlockListItem>>("variants").Select(x => x.Content);
    foreach (var variant in variants)
    {
        <h4>@variant.Value("variantName")</h4>
        <p>@variant.Value("description")</p>
    }
}

@inherits Umbraco.Web.Mvc.UmbracoViewPage
@using ContentModels = Umbraco.Web.PublishedModels;
@{
    var variants = Model.Variants.Select(x => x.Content).OfType<ProductVariant>();
    foreach (var variant in variants)
    {
        <h4>@variant.VariantName</h4>
        <p>@variant.Description</h4>
    }
}

Learn more about that in the Data Types Migrations

Migrating data types

When migrating content from Umbraco 7 to Umbraco 8, the Data Type 'pre-value' structure has changed. In Umbraco 8, the term 'pre-values' no longer exists and is instead referred to as property editor configuration.

In Umbraco 8, property editor configuration is a strongly typed object. There are plenty of examples in the Umbraco-CMS codebase.

This configuration is stored differently in Umbraco 8 than it was in Umbraco 7. In Umbraco 7, each pre-value property was stored as a different row in a different database table. In Umbraco 8 this is simplified and property editor configuration is stored as the JSON serialized version of the strongly typed configuration object.

When upgrading from Umbraco 7 to Umbraco 8, Umbraco has no way of knowing how custom property editors have intended to structure their configuration data. During the upgrade, Umbraco will convert the key/value pairs from the old pre-value database table into a serialized JSON version of those values. There is a reasonable chance that the end result of this data conversion is not compatible with the custom property editor.

There are 3 options that a developer can choose to do to work around this automatic data conversion:

1: Implement a custom IPreValueMigrator

This option requires you to create a custom C# migrator for each of your custom property editors that store custom configuration data. It will also require that you implement these migrators before you run the Umbraco 8 content migration.

To do this, you will create an implementation of IPreValueMigrator or inherit from the base class .

There are plenty of examples of this in the .

You will then need to register them in a composer:

When running the migrations and encountering a custom configuration, Umbraco will utilize the PreValueMigrator when converting the old pre-values into the new JSON format.

2: Update your Angular configuration (pre-value) and property editor

This option means that you will choose to use the automatically converted JSON data format. In this case, it will mean updating your pre-value and property editors to use the new JSON configuration data. The converted data won't be much different than the original/intended data format so this might not be too much work.

3: Update the Angular configuration (pre-value) editor

With this option the configuration/pre-value editor needs to be updated to transform the JSON converted data into the data structure you want. When this is done and when the Data Type is saved again, the JSON data structure will be saved back to the database. Your property editor will then continue to work.

This will require you to update and save all custom pre-value editors to transform the converted structures back to your intended data structure.

Content Picker

Schema Alias: Umbraco.ContentPicker

UI Alias: Umb.PropertyEditorUi.DocumentPicker

Returns: IEnumerable<IPublishedContent>

The Content Picker enables choosing the type of content tree to display and which specific part to render. It also allows you to set a dynamic root node for the content based on the current document using the Content Picker.

The Content Picker was formerly known as the Multinode Treepicker in version 13 and below.

The renaming is purely a client-side UI change, meaning the property editor still uses the Umbraco.MultiNodeTreePicker schema alias.

The change was made as the word Content in the backoffice acts as an umbrella term covering Documents, Media, and Members.

Are you looking for the original Content Picker?

The Content Picker from version 13 and below has been renamed .

Data Type Definition Example

Minimum/maximum number of items

Define a limit on the number of items allowed to be selected.

Ignore user start nodes

Checking this field allows users to choose nodes they normally cannot access.

Node Type

This option allows for configuring what type of content is available when using the Data Type. The available types of content are Content, Members, or Media items.

When selecting Content from the dropdown, the option to specify a root node, also called the origin, becomes available.

When picking the origin there are several different options available:

The following options are available when picking the origin:

Root: The root is the first level item of the sub-tree of the current node.
Parent: The parent is the nearest ancestor of the current node.
Current: The current node.
- A picker that uses the current node, cannot pick anything when the current node is created, as it will not have any children.

When an origin has been specified, it becomes possible to continue to build a Dynamic Root by adding additional query steps.

Navigate the content tree relative to the specified origin to execute multiple query steps and find the root node needed.

The following options are available:

Nearest Ancestor or Self: Find the nearest ancestor or current item that fits with one of the configured Document Types.
Furthest Ancestor or Self: Find the furthest ancestor or current item that fits with one of the configured Document Types.
Nearest Descendant or Self: Find the nearest descendant or current item that fits with one of the configured Document Types.
Furthest Descendant or Self:

The options above are all based on navigating the document hierarchy by locating ancestors and descendants. It is possible to execute custom steps to build even more complex queries. Once a custom query is available it will be added to the bottom of the Append steps to query dialog. Learn more about .

Each query step takes the output from the origin or the previous step as input. It is only ever the result of the last query step that is passed to the next step.

Adding a custom query step

Custom query steps can be used to solve specific use cases, such as traversing sibling documents or matching property values. Before the custom query steps can be selected in the Data Type settings, they must be defined via code.

When implementing a query step it requires a collection of origins and information about the query step. The collection is taken from where the name specified in the UI can be found.

Specifying the origin is required for the custom query step to become available.

Read the above to learn more about this.

You can inject dependencies into the constructor. These dependencies could be custom repositories or the IVariationContextAccessor, if you want to use the current culture.

The ExecuteAsync method receives a set of content keys from the last executed query step or the origin. It has to return a new set of content keys.

To register the custom query step, append it to the existing query steps, DynamicRootSteps(). This is done from a composer as shown below.

Finally, register the custom query step on the client side and provide a brief description.

You can do this in an umbraco-package.json file, as shown below:

Allow items of type

Choose which types of content should be available to pick using the Content Picker.

This is done by selecting one or more Document Types.

Query Example

Consider the following tree structure where the Document Type alias is presented in square brackets.

Codegarden
- 2023 [year]
  - Talks [talks]

Consider configuring a Content Picker on the talk Document Type to select a stage for the talk. Here, you want to display only the stages for the actual year. To do this, you need to set the parent as the origin.

For instance, if you are on the Umbraco anno MMXXIII node, the collection of content keys passed into the first query step will only contain the Talks content node.

First, query for the nearest ancestors of the type year. This will return 2023.
Second, query for the nearest descendants of the type stages.

When opening the picker on the Umbraco anno MMXXIII node, it will now show the children of the node on the path Codegarden > 2023 > Stages.

MVC View Example

Without Models Builder

With Models Builder

Add values programmatically

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

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

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

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem>

@{
    var quoteText = Model.Content.Value("quoteText")?.ToString();
    var citation = Model.Content.Value("citation")?.ToString();
}

<blockquote class="quote-block">
    @if (!string.IsNullOrEmpty(quoteText))
    {
        <p class="quote-text">@Html.Raw(quoteText)</p>
    }

    @if (!string.IsNullOrEmpty(citation))
    {
        <cite class="quote-citation">@citation</cite>
    }
</blockquote>

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem>
@using Umbraco.Cms.Core.Models

@{
    // Get link from Multi URL Picker
    var linkPicker = Model.Content.Value<IEnumerable<Link>>("link");
    var link = linkPicker?.FirstOrDefault();

    // Get style from settings (if settings model exists)
    var style = "primary"; // Default style
    if (Model.Settings != null)
    {
        var settingsStyle = Model.Settings.Value("style")?.ToString();
        if (!string.IsNullOrEmpty(settingsStyle))
        {
            style = settingsStyle.ToLower();
        }
    }

    // CSS class based on style setting
    var cssClass = $"cta-button cta-button--{style}";
}

@if (link != null && !string.IsNullOrEmpty(link.Url))
{
    <div class="cta-block">
        <a href="@link.Url"
           class="@cssClass"
           @(link.Target == "_blank" ? Html.Raw("target=\"_blank\" rel=\"noopener noreferrer\"") : Html.Raw(""))>
            @(!string.IsNullOrEmpty(link.Name) ? link.Name : "Learn More")
        </a>
    </div>
}

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem<QuoteBlock, QuoteBlockSettings>>
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;

@{
    var style = "";
    if (Model.Settings?.Color != null)
    {
        style = $"style=\"border-left-color: {Model.Settings.Color};\"";
    }
}

<blockquote class="quote-block" @Html.Raw(style)>
    @if (!string.IsNullOrEmpty(Model.Content.QuoteText))
    {
        <p class="quote-text">@Html.Raw(Model.Content.QuoteText)</p>
    }

    @if (!string.IsNullOrEmpty(Model.Content.Citation))
    {
        <cite class="quote-citation">@Model.Content.Citation</cite>
    }
</blockquote>

using Azure;
using Azure.Data.Tables;
using Serilog.Events;
using Serilog.Formatting.Compact.Reader;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Logging.Viewer;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Infrastructure.Logging.Serilog;
using Umbraco.Cms.Infrastructure.Services.Implement;

namespace My.Website;

public class AzureTableLogsRepository : LogViewerRepositoryBase
{
    private readonly IJsonSerializer _jsonSerializer;

    public AzureTableLogsRepository(UmbracoFileConfiguration umbracoFileConfig, IJsonSerializer jsonSerializer) : base(
        umbracoFileConfig)
    {
        _jsonSerializer = jsonSerializer;
    }

    protected override IEnumerable<ILogEntry> GetLogs(LogTimePeriod logTimePeriod, ILogFilter logFilter)
    {
        // This example uses a connection string compatible with the Azurite emulator
        // https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite
        var client =
            new TableClient(
                "UseDevelopmentStorage=true",
                "LogEventEntity");

        // Filter by timestamp to avoid retrieving all logs from the table, preventing memory and performance issues
        IEnumerable<AzureTableLogEntity> results = client.Query<AzureTableLogEntity>(
            entity => entity.Timestamp >= logTimePeriod.StartTime.Date &&
                      entity.Timestamp <= logTimePeriod.EndTime.Date.AddDays(1).AddSeconds(-1));

        // Read the data and apply logfilters
        IEnumerable<LogEvent> filteredData = results.Select(x => LogEventReader.ReadFromString(x.Data))
            .Where(logFilter.TakeLogEvent);

        return filteredData.Select(x => new LogEntry
        {
            Timestamp = x.Timestamp,
            Level = Enum.Parse<Core.Logging.LogLevel>(x.Level.ToString()),
            MessageTemplateText = x.MessageTemplate.Text,
            Exception = x.Exception?.ToString(),
            Properties = MapLogMessageProperties(x.Properties),
            RenderedMessage = x.RenderMessage(),
        });
    }

    private IReadOnlyDictionary<string, string?> MapLogMessageProperties(
        IReadOnlyDictionary<string, LogEventPropertyValue>? properties)
    {
        var result = new Dictionary<string, string?>();

        if (properties is not null)
        {
            foreach (KeyValuePair<string, LogEventPropertyValue> property in properties)
            {
                string? value;

                if (property.Value is ScalarValue scalarValue)
                {
                    value = scalarValue.Value?.ToString();
                }
                else if (property.Value is StructureValue structureValue)
                {
                    var textWriter = new StringWriter();
                    structureValue.Render(textWriter);
                    value = textWriter.ToString();
                }
                else
                {
                    value = _jsonSerializer.Serialize(property.Value);
                }

                result.Add(property.Key, value);
            }
        }

        return result;
    }

    public class AzureTableLogEntity : ITableEntity
    {
        public required string Data { get; set; }

        public required string PartitionKey { get; set; }

        public required string RowKey { get; set; }

        public DateTimeOffset? Timestamp { get; set; }

        public ETag ETag { get; set; }
    }
}

public class AzureTableLogsService : LogViewerServiceBase
{
    public AzureTableLogsService(
        ILogViewerQueryRepository logViewerQueryRepository,
        ICoreScopeProvider provider,
        ILogViewerRepository logViewerRepository)
        : base(logViewerQueryRepository, provider, logViewerRepository)
    {
    }

    // Change this to what you think is sensible.
    // As an example, check whether more than 5 days off logs are requested.
    public override Task<Attempt<bool, LogViewerOperationStatus>> CanViewLogsAsync(LogTimePeriod logTimePeriod)
    {
        return logTimePeriod.EndTime - logTimePeriod.StartTime < TimeSpan.FromDays(5)
            ? Task.FromResult(Attempt.SucceedWithStatus(LogViewerOperationStatus.Success, true))
            : Task.FromResult(Attempt.FailWithStatus(LogViewerOperationStatus.CancelledByLogsSizeValidation, false));
    }

    public override ReadOnlyDictionary<string, LogLevel> GetLogLevelsFromSinks()
    {
        var configuredLogLevels = new Dictionary<string, LogLevel>
        {
            { "Global", GetGlobalMinLogLevel() },
            { "AzureTableStorage", LogViewerRepository.RestrictedToMinimumLevel() },
        };

        return configuredLogLevels.AsReadOnly();
    }
}

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Infrastructure.DependencyInjection;
using Umbraco.Cms.Core.Services;

namespace My.Website;

public class AzureTableLogsComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.Services.AddUnique<ILogViewerRepository, AzureTableLogsRepository>();
            builder.Services.AddUnique<ILogViewerService, AzureTableLogsService>();
        }
    }
}

{
    "Name": "AzureTableStorage",
    "Args": {
        "storageTableName": "LogEventEntity",
        "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact",
        "connectionString": "DefaultEndpointsProtocol=https;AccountName=ACCOUNT_NAME;AccountKey=KEY;EndpointSuffix=core.windows.net"
    }
}

[RuntimeLevel(MinLevel = RuntimeLevel.Upgrade, MaxLevel = RuntimeLevel.Upgrade)] // only on upgrades
public class PreValueMigratorComposer : IUserComposer
{
    public void Compose(Composition composition)
    {
        composition.WithCollectionBuilder<PreValueMigratorCollectionBuilder>()
            // Append all of the migrators required
            .Append<MyCustomPreValueMigrator>()
            .Append<AnotherPreValueMigrator>();
    }
}

public class MyCustomDynamicRootQueryStep : IDynamicRootQueryStep
{
    private readonly IMyCustomRepository _myCustomRepository;

    public MyCustomDynamicRootQueryStep(IMyCustomRepository myCustomRepository)
    {
        _myCustomRepository = myCustomRepository;
    }

    // The string below is what you specify in the UI to execute this custom query step.
    public virtual string SupportedDirectionAlias { get; set; } = "MyCustomStep";

    public async Task<Attempt<ICollection<Guid>>> ExecuteAsync(ICollection<Guid> origins, DynamicRootQueryStep filter)
    {
        if (filter.Alias != SupportedDirectionAlias)
        {
            return Attempt<ICollection<Guid>>.Fail();
        }

        if (origins.Any() is false)
        {
            return Attempt<ICollection<Guid>>.Succeed(Array.Empty<Guid>());
        }

        // Replace the following with your custom logic
        var result = await _myCustomRepository.GetWhateverIWantAsync(origins);

        return Attempt<ICollection<Guid>>.Succeed(result);
    }
}

{
  "$schema": "../../umbraco-package-schema.json",
  "name": "My.Test.Extension",
  "version": "0.1.0",
  "extensions": [
    {
      "type": "dynamicRootQueryStep",
      "alias": "Umb.DynamicRootQueryStep.MyCustomStep",
      "name": "Dynamic Root Query Step: My Custom Step",
      "meta": {
        "queryStepAlias": "MyCustomStep",
        "label": "My Custom Step",
        "description": "My custom step description.",
        "icon": "icon-coffee"
      },
      "weight": 0
    }
  ]
}

@{
    var typedContentPicker = Model.Value<IEnumerable<IPublishedContent>>("featuredArticles");
    if (typedContentPicker != null) {
        foreach (var item in typedContentPicker)
        {
            <p>@item.Name</p>
        }
}

@using Umbraco.Cms.Core
@using Umbraco.Cms.Core.Services
@inject IContentService ContentService
@{
    // 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 pages you want to assign to the Content Picker
    var page = Umbraco.Content("665d7368-e43e-4a83-b1d4-43853860dc45");
    var anotherPage = Umbraco.Content("1f8cabd5-2b06-4ca1-9ed5-fbf14d300d59");

    // Create Udi's of the pages
    var pageUdi = Udi.Create(Constants.UdiEntityType.Document, page.Key);
    var anotherPageUdi = Udi.Create(Constants.UdiEntityType.Document, anotherPage.Key);

    // Create a list of the page udi's
    var udis = new List<string>{pageUdi.ToString(), anotherPageUdi.ToString()};

    // Set the value of the property with alias 'featuredArticles'.
    content.SetValue("featuredArticles", string.Join(",", udis));

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

@using Umbraco.Cms.Core.PublishedCache
@inject IPublishedContentTypeCache PublishedContentTypeCache
@{
    // Set the value of the property with alias 'featuredArticles'
    content.SetValue(Home.GetModelPropertyType(PublishedContentTypeCache, x => x.FeaturedArticles).Alias, string.Join(",", udis));
}

Defining Content

Here you'll find an explanation of how content is defined in Umbraco

Before a piece of content can be created in the Umbraco backoffice, first it needs to be defined. That is why, when opening a blank installation of Umbraco, it is not possible to create content in the Content section.

All content needs a blueprint that holds information about what kind of data can be stored on the content node or which editors are used.

Additionally, it also needs information on how it is organized, where in the structure it is allowed, and so forth. This blueprint or definition is called a Document Type.

What is a Document Type?

Document Types define what kind of content can be created in the Content section and what an end-user sees and can interact with.

It can define entire pages or more limited content that can be reused on other nodes ie. a Search Engine Optimization (SEO) group. This means that you are in complete control of what type of content can be created and where.

Another example is if there is a "Blog post" Document Type that has some properties containing a thumbnail, a name, and an author image. Then all blog posts using the "Blog post" Document Type, will allow the end user to fill in a thumbnail, author name, and an author image.

A Document Type contains fieldsets (or groups) where you can apply rules about where the content can be created, allowed template(s), backoffice icons, etc.

1. Creating a Document Type

A Document Type is created using the Document Type editor in the Settings section.

Go to the Settings section in the backoffice.
On the Document Types node click the menu icon (•••) to bring up the context menu.
Here choose Document Type with Template. This will create a new Document Type with a template. The Template can be found under Templates in the Settings section which will be assigned as the default template for the Document Type.

You can also choose to create a Document Type without a template and create Folders to organize your Document Types. Other options are to create Compositions and Element types, which you can read more about in the section.

2. Defining the root node

Name the Document Type

First, we're prompted to give the Document Type a name. This first Document Type will be the root node for our content, name it "Home".

The alias of the Document Type is automatically generated based on the property name. If you want to change the auto-generated alias, click the "lock" icon. The alias must be in camel case. For example: homePage.

Having a root node lets you quickly query content as you know everything will be under the root node.

Adding Icons to the Document Type

Choosing appropriate icons for your content nodes is a good way to give editors a better overview of the content tree.

To set an icon for the Document Type click the document icon in the top left corner. This will open the icon select dialog. Search for "Home"and select the icon. This icon will be used in the content tree.

Setting Permissions

This will allow this Document Type to be created as the first content in the Content section.

Go to the Structure tab
Tick the Allow as root toggle
Save the Document Type by clicking save in the bottom right corner.

3. Creating the content

Now that we have the Document Type in place, we can create the content.

Go to the Content section
Click on the menu icon next to Content
Select the "Home" Document Type. We'll name it "Home"

As we haven't created our properties, all we can see on the "Home" node is the Properties tab. This tab contains the default properties that are available on all content nodes in Umbraco.

Let's add some properties of our own.

4. Groups and properties

In order to add the option to create different content on the same Document Type, some groups and properties need to be added.

Groups

Groups are a way to organize and structure the properties within the content, making it more manageable. It also makes it more user-friendly for content editors when creating or editing content on a website.

A name can be added to the group and after properties can be added.

Properties

Each field on a Document Type is called a property. The property is given a name, an alias (used to output the properties contained in a template), and an editor.

The editor determines what type of data the property will store and the input method. There is a wide range of default and you can .

Some editors require configuration where a configured editor is saved as a Data Type and can be reused for multiple properties and document types. These can be seen in the Settings section under Data Types.

Go to the Settings section
Expand Document Types by clicking the arrow to the left
Select the "Home" Document Type.

Keyboard Shortcuts

Keyboard shortcuts are available when you are working with the Document Type editor. To see which shortcuts are available, click ALT + SHIFT + K.

Adding groups

Before we start adding properties to the Document Type we need to create a group to hold the property.

Click Add group and name the group "Content".

If you have multiple groups and/or properties you can order them with drag and drop or by entering a numeric sort order value. This is done by clicking Reorder.

To convert a group to a tab, see the section in the article.

Adding properties

Now that we have created a group we can start adding properties. Let's add a Rich Text editor to the Content group.

Click the Add property link in the Content group. This opens the property settings dialog. Here you can set the metadata for each property (name, alias, description)
Choose which Data Type/property editor to use, and add validation if needed.
Give the property a name. The name will be shown to the editor to make it relevant and understandable. Notice the alias is automatically generated based on the name. We'll name this "Body Text".

Property Editors

Clicking Select Editor will open the Select Editor dialog. Here, you can choose between all the available editors on the Create a new Configuration tab. This will create a new configuration or already configured editors in the Available Configurations tab.
To make it easier to find what you need use the search field to filter by typing "Rich". Filtering will display configured properties first (under Available configurations) and all available editors under that.
Select the Rich Text editor under Create new. This will let you configure the editor settings - the Rich Text editor for this property.

The name of the Data Type is based on the name of the Document Type, the name of the property, and the property editor. Flor example: Home - Body Text - Rich Text editor.

Let's rename it to "Basic Rich Text editor" and only select the most necessary options.
- bold
- italic

Selecting the Mandatory toggle makes the property mandatory and the content cannot be saved if no value is entered (in this case, the Richtext editor).

You have the option to add additional validation by selecting a predefined validation method under the Custom validation dropdown (such as email, number, or URL). Or by selecting a custom validation and adding a regular expression.

Save the Document Type.
If you go to the Content section and click on the Home node you will now see the Contentgroup with the Body Text property.

Property descriptions

The description of the property is not necessary, but it´s a best practice as it guides the editor to use the property correctly. The property description supports some markdown and one custom collapse syntax:

Bold

You can make text in the description bold by wrapping it with **

Italic

You can make text in the description italic by wrapping it with *

Links

You can make links by using the syntax:

Note: Links will always have thetarget="_blank" set. This is currently not configurable.

Images

You can embed images by using this syntax:

Collapsible description

You can make the description collapsible by using this syntax:

Now if we put it all together we get something like this:

5. Defining child nodes

Next up we'll create a text page Document Type that will be used for subpages on the site.

Go back to the Settings section
Create a new Document Type
Name it "Text Page".
Add a group called "Content

Creating child nodes

Before creating a Text Page in Content section, allow the Text Page Document Type to be created as a child node to the Home node.

Select the "Home" Document Type
Go to the Structure group.
Click Add child
Select "Text Page

Go to the Content section
Click the menu icon (•••) next to the "Home" node
Select the "Text page" Document Type. We'll name the page "About us". We now have a basic content structure.

Document Types are flexible and can be used for defining pieces of reusable content or an entire page, to act as a container or repository.

6. Exporting/Importing the Document Type

You can also export document types from an already existing project/installation and import them into another project/installation.

Go to the Settings section
Click ... next to the Document type
Select Export. When you click on the Export button, the Document Type is saved as a *.udt file.

To import a Document Type:

Go to the Settings section
Click ... next to the Document type
Select Import Document Type
Click on the Import button and browse to the Document Type you exported. The Name and

If your Document Type contains compositions or inherits from another Document Type, then you need to export/import the Composition/Document Type too.
You cannot export/import document types on Umbraco Cloud.

More information

Tutorials

This is **bold**
This is *italic*
[This is an absolute link](https://google.com)
[This is a relative link](/umbraco#/media)
--
![Image alt text](https://media.giphy.com/media/bezxCUK2D2TuBCJ7r5/giphy.gif)

App_Plugins/Login/umbraco-package.json

{
    "alias": "login.extensions",
    "name": "Login extensions",
    "version": "1.0.0",
    "allowPublicAccess": true,
    "extensions": [
        {
            "type": "localization",
            "alias": "Login.Localize.EnUS",
            "name": "English",
            "js": "/App_Plugins/Login/en-us.js",
            "meta": {
                "culture": "en-US"
            }
        }
    ]
}

App_Plugins/Login/en-us.js

export default {
  auth: {
    instruction: "Log in again to continue",
    greeting0: "Is is Sunday",
    greeting1: "Is is Monday",
    greeting2: "Is is Tuesday",
    greeting3: "Is is Wednesday",
    greeting4: "Is is Thursday",
    greeting5: "Is is Friday",
    greeting6: "Is is Saturday",
  }
}

"Umbraco": {
    "CMS": {
      "Global": {
        "Id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "Smtp": {
          "From": "[email protected]",
          "Host": "127.0.0.1",
          "Username": "username",
          "Password": "password"
        }
      }
    }
}

"Umbraco": {
    "CMS": {
      "Content": {
        "LoginBackgroundImage": "../myImagesFolder/myLogin.jpg",
        "LoginLogoImage": "../myImagesFolder/myLogo.svg",
        "LoginLogoImageAlternative": "../myImagesFolder/myLogo.svg"
      }
   }
}

{
    "alias": "login.extensions",
    "name": "Login extensions",
    "version": "1.0.0",
    "allowPublicAccess": true,
    "extensions": [
        {
            "type": "appEntryPoint",
            "alias": "MyCustomLoginScreen",
            "name": "My Custom Login Screen",
            "js": "/App_Plugins/Login/my-custom-login-screen.js"
        }
    ]
}

App_Plugins/Login/umbraco-package.json

{
    "alias": "login.extensions",
    "name": "Login extensions",
    "version": "1.0.0",
    "allowPublicAccess": true,
    "extensions": [
        {
            "type": "localization",
            "alias": "Login.Localize.EnUS",
            "name": "English",
            "js": "/App_Plugins/Login/en-us.js",
            "meta": {
                "culture": "en-US"
            }
        }
    ]
}

App_Plugins/Login/en-us.js

export default {
  auth: {
    instruction: "Log in again to continue",
    greeting0: "Is is Sunday",
    greeting1: "Is is Monday",
    greeting2: "Is is Tuesday",
    greeting3: "Is is Wednesday",
    greeting4: "Is is Thursday",
    greeting5: "Is is Friday",
    greeting6: "Is is Saturday",
  }
}

Block Grid

Schema Alias: Umbraco.BlockGrid

UI Alias: Umb.PropertyEditorUi.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.

This article is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.

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.
Click ... next to 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 .
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.

Setup Block Types

Block Types are based on . 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.

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. The label is also used for search in the Add Block dialog during content editing. If no label is defined, the block will not be searchable. The search does not fall back to the block’s name.

Label example: "My Block {=myPropertyAlias}" will be shown as: "My Block FooBar".

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 .
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 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.

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:

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:

In the sample above "myGrid" is the alias of the Block Grid editor.

If you are using ModelsBuilder, the example will look like this:

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:

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.

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:

Stylesheet

Using the default rendering together with your layout stylesheet will provide what you need for rendering the layout.

To use the Default Layout Stylesheet, 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.

A set of built-in Partial Views are responsible for rendering the Blocks and Areas in a Block Grid. If you want to tweak or change the way the Block Grid is rendered, you can use the built-in Partial Views as a template:

Clone the views from . They can be found in src/Umbraco.Web.UI/Views/Partials/blockgrid .
Copy the cloned views to the local folder Views/Partials/blockgrid/

2. Build custom 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:

If you do not want to use Partial Views, you can access the block item data directly within your rendering:

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.

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:

Build a Custom Backoffice View

Building Custom Views for Block representations in Backoffice is based on the same API for all Block Editors.

Creating a Block Grid programmatically

In this example, we will be creating content programmatically for a "spot" Blocks in a Block Grid.

Create an element type to represent block content called Spot Element with the following properties:

A property called title with the editor of Textstring
A property called text with the editor of Textstring

Create an element type to represent block content called Spot Settings with the following properties:

A property called featured with the editor of True/false.

Add a property called blockGrid in a Document Type.
Select Block Grid as the property editor.
Click Add in the Blocks Settings and select Spot Element.
Select Spot Settings in the

The raw input data for the spots looks like this:

The resulting JSON object stored for the Block Grid will look like this:

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

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.

Create a class called Model.cs containing the following to transform the raw data into Block Grid-compatible JSON:

Create a class called BlockGridTestController.cs. By injecting IContentService and IContentTypeService into an API controller, the raw data can be transformed into Block Grid JSON. It can then be saved to the target content item.

For the above code IContent? content = _contentService.GetById(Guid.Parse("efba7b97-91b6-4ddf-b2cc-eef89ff48c3b")); change the id with your content node that is using the Block Grid.

To test this implementation, run the project and send a POST request to /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.

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)

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)

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);
    }
}

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>
    }
}

<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>

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 }
}

{
   "contentData":[
      {
         "contentTypeKey":"fd01539a-5bcf-48f7-aee5-8ad925c75902",
         "udi":null,
         "key":"019f2a7a-35b4-45b3-b867-910b3f340f25",
         "values":[
            {
               "editorAlias":"Umbraco.TextBox",
               "culture":null,
               "segment":null,
               "alias":"title",
               "value":"Item one"
            },
            {
               "editorAlias":"Umbraco.TextBox",
               "culture":null,
               "segment":null,
               "alias":"text",
               "value":"This is item one"
            }
         ]
      },
      {
         "contentTypeKey":"fd01539a-5bcf-48f7-aee5-8ad925c75902",
         "udi":null,
         "key":"063f8062-8610-441a-97f1-ea6d73fe2678",
         "values":[
            {
               "editorAlias":"Umbraco.TextBox",
               "culture":null,
               "segment":null,
               "alias":"title",
               "value":"Item two"
            },
            {
               "editorAlias":"Umbraco.TextBox",
               "culture":null,
               "segment":null,
               "alias":"text",
               "value":"This is item two"
            }
         ]
      }
   ],
   "settingsData":[
      {
         "contentTypeKey":"03c43074-a4ba-4bd2-92b1-c3a35a0eed4d",
         "udi":null,
         "key":"5b2d74bc-3e85-4aa3-b684-4b1f11522d7c",
         "values":[
            {
               "editorAlias":"Umbraco.TrueFalse",
               "culture":null,
               "segment":null,
               "alias":"featured",
               "value":0
            }
         ]
      },
      {
         "contentTypeKey":"03c43074-a4ba-4bd2-92b1-c3a35a0eed4d",
         "udi":null,
         "key":"1c6599fc-6558-4a0b-9da8-4f002925f59f",
         "values":[
            {
               "editorAlias":"Umbraco.TrueFalse",
               "culture":null,
               "segment":null,
               "alias":"featured",
               "value":1
            }
         ]
      }
   ],
   "expose":[
      {
         "contentKey":"019f2a7a-35b4-45b3-b867-910b3f340f25",
         "culture":null,
         "segment":null
      },
      {
         "contentKey":"063f8062-8610-441a-97f1-ea6d73fe2678",
         "culture":null,
         "segment":null
      }
   ],
   "Layout":{
      "Umbraco.BlockGrid":[
         {
            "columnSpan":12,
            "rowSpan":1,
            "areas":[

            ],
            "contentUdi":null,
            "settingsUdi":null,
            "contentKey":"019f2a7a-35b4-45b3-b867-910b3f340f25",
            "settingsKey":"5b2d74bc-3e85-4aa3-b684-4b1f11522d7c"
         },
         {
            "columnSpan":12,
            "rowSpan":1,
            "areas":[

            ],
            "contentUdi":null,
            "settingsUdi":null,
            "contentKey":"063f8062-8610-441a-97f1-ea6d73fe2678",
            "settingsKey":"1c6599fc-6558-4a0b-9da8-4f002925f59f"
         }
      ]
   }
}

Models.cs

using System.Text.Json.Serialization;

namespace My.Site.Models;

// this is the "root" of the block grid data
public class BlockGridData
{
    public BlockGridData(BlockGridElementData[] contentData, BlockGridElementData[] settingsData, BlockGridExposeData[] expose, BlockGridLayout layout)
    {
        ContentData = contentData;
        SettingsData = settingsData;
        Expose = expose;
        Layout = layout;
    }

    [JsonPropertyName("contentData")]
    public BlockGridElementData[] ContentData { get; }

    [JsonPropertyName("settingsData")]
    public BlockGridElementData[] SettingsData { get; }

    [JsonPropertyName("expose")]
    public BlockGridExposeData[] Expose { get; }

    [JsonPropertyName("Layout")]
    public BlockGridLayout Layout { get; }
}

// this represents an item in the block grid content or settings data collection
public class BlockGridElementData
{
    public BlockGridElementData(Guid contentTypeKey, Guid key, BlockGridValueData[] values)
    {
        ContentTypeKey = contentTypeKey;
        Key = key;
        Values = values;
    }

    [JsonPropertyName("contentTypeKey")]
    public Guid ContentTypeKey { get; }

    [JsonPropertyName("key")]
    public Guid Key { get; }

    [JsonPropertyName("values")]
    public BlockGridValueData[] Values { get; }
}

public class BlockGridValueData
{
    public BlockGridValueData(string alias, string editorAlias, object? value)
    {
        Alias = alias;
        EditorAlias = editorAlias;
        Value = value;
    }

    [JsonPropertyName("alias")]
    public string Alias { get; }

    [JsonPropertyName("editorAlias")]
    public string EditorAlias { get; }

    [JsonPropertyName("value")]
    public object? Value { get; }
}

// this represents an item in the block grid expose data collection
public class BlockGridExposeData
{
    public BlockGridExposeData(Guid contentKey) => ContentKey = contentKey;

    [JsonPropertyName("contentKey")]
    public Guid ContentKey { get; }
}

// this is a wrapper for the block grid layout, purely required for correct serialization
public class BlockGridLayout
{
    public BlockGridLayout(BlockGridLayoutItem[] layoutItems) => LayoutItems = layoutItems;

    [JsonPropertyName("Umbraco.BlockGrid")]
    public BlockGridLayoutItem[] LayoutItems { get; }
}

// this represents an item in the block grid layout collection
public class BlockGridLayoutItem
{
    public BlockGridLayoutItem(int columnSpan, int rowSpan, Guid contentKey, Guid settingsKey)
    {
        ColumnSpan = columnSpan;
        RowSpan = rowSpan;
        ContentKey = contentKey;
        SettingsKey = settingsKey;
    }

    [JsonPropertyName("columnSpan")]
    public int ColumnSpan { get; }

    [JsonPropertyName("rowSpan")]
    public int RowSpan { get; }

    [JsonPropertyName("contentKey")]
    public Guid ContentKey { get; }

    [JsonPropertyName("settingsKey")]
    public Guid SettingsKey { get; }

    [JsonPropertyName("areas")]
    // areas are omitted from this sample for abbreviation
    public object[] Areas { get; } = [];
}

BlockGridTestController.cs

using Microsoft.AspNetCore.Mvc;
using My.Site.Models;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Services;

namespace My.Site.Controllers;

[ApiController]
[Route("/umbraco/api/blockgridtest")]
public class BlockGridTestController : Controller
{
    private readonly IContentService _contentService;
    private readonly IContentTypeService _contentTypeService;
    private readonly IJsonSerializer _serializer;

    public BlockGridTestController(IContentService contentService, IContentTypeService contentTypeService, IJsonSerializer serializer)
    {
        _contentService = contentService;
        _contentTypeService = contentTypeService;
        _serializer = serializer;
    }

    // POST: /umbraco/api/blockgridtest/create
    [HttpPost("create")]
    public ActionResult Create()
    {
        // get the item content to modify
        IContent? content = _contentService.GetById(Guid.Parse("7ed0bd1f-2a52-4b45-9811-2560b907fe48"));
        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 contentData = new List<BlockGridElementData>();
        var settingsData = new List<BlockGridElementData>();
        var exposeData = new List<BlockGridExposeData>();
        var layoutItems = new List<BlockGridLayoutItem>();
        foreach (var data in rawData)
        {
            // generate new keys for block content and settings
            var contentKey = Guid.NewGuid();
            var settingsKey = Guid.NewGuid();

            // create new content data
            var contentValues = new BlockGridValueData[]
            {
                new("title", "Umbraco.TextBox", data.Title),
                new("text", "Umbraco.TextBox", data.Text),
            };
            contentData.Add(new BlockGridElementData(spotContentType.Key, contentKey, contentValues));

            // create new settings data
            var settingValues = new BlockGridValueData[]
            {
                new("featured", "Umbraco.TrueFalse", data.Featured ? "1" : "0"),
            };
            settingsData.Add(new BlockGridElementData(spotSettingsType.Key, settingsKey, settingValues));

            // create a new expose item
            exposeData.Add(new BlockGridExposeData(contentKey));

            // create a new layout item
            layoutItems.Add(new BlockGridLayoutItem(data.ColumnSpan, data.RowSpan, contentKey, settingsKey));
        }

        // construct the block grid data from layout, content and settings
        var blockGridData = new BlockGridData(
            [.. contentData],
            [.. settingsData],
            [.. exposeData],
            new BlockGridLayout([.. layoutItems]));

        // serialize the block grid data as JSON and save it to the "blockGrid" property on the content item
        var propertyValue = _serializer.Serialize(blockGridData);
        content.SetValue("blockGrid", propertyValue);
        _contentService.Save(content);

        return Ok("Saved");
    }
}

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.

Version Specific Upgrades

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 17

System dates are updated to UTC

In earlier versions of Umbraco, system dates have been primarily persisted as server time without time zone information, with some stored as UTC. With Umbraco 17, system dates are now always stored in UTC.

To ensure that existing stored system dates align, a migration will run when upgrading to Umbraco 17.

The migration consists of:

Determining the current time zone for the server.

Umbraco 16

TinyMCE is removed

In Umbraco 15, two property editors were available for a rich text editor: TinyMCE and TipTap.

With Umbraco 16, only TipTap is available as an option out of the box. TinyMCE's precludes us from shipping it with the MIT-licensed Umbraco CMS.

When upgrading to Umbraco 16, any data types using TinyMCE will be migrated to use TipTap.

To continue to use TinyMCE, a third-party package must be installed prior to the upgrade. This will disable the migration and allow you to continue with TinyMCE.

Package migrations are asynchronous

Umbraco 16 adds support for asynchronous migrations and part of this work involved creating a new base class for package migrations. This leads to a source-compatible but binary-incompatible breaking change. In practice, this means that package code using migrations and calling base class helper methods such as

Umbraco 15

Snapshots are removed

Snapshots have been removed, meaning any code using IPublishedSnapshot, and by extension IPublishedSnapshotAccessor, must be updated. Inject IPublishedContentCache or IPublishedMediaCache and use those directly instead.

Modelsbuilder models needs to be rebuilt

Models generated by ModelsBuilder used the IPublishedSnapshot

Umbraco 14

Read more about the release of Umbraco 14 in the .

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

This is by far the most impactful update of Umbraco in years. We’ve fundamentally changed the way you extend Umbraco. If you are experienced in developing Web Components you can now use your preferred framework for this. If you are unsure how to proceed, you can implement it with TypeScript and the Lit library like we’ve done. In this case, start with this article on how to .

The new Backoffice (Bellissima) is entirely built on the Umbraco UI Library. This means that you might experience some of your components not being rendered on the page because the name has been changed. You should be able to find equivalents to what you were used to. For example, the

Umbraco 14 RC Versions

Below you can find the list of breaking changes introduced in Umbraco 14 RC release versions.

RC 5

Umbraco 14 Beta Versions

Below you can find the list of breaking changes introduced in Umbraco 14 Beta release versions.

Beta 3

Umbraco 13

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

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 11

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

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 .

The breaking changes in TinyMCE are also documented in the official migration guides for and from .

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 10

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.

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

Release notes

You can find a list of all the released Umbraco versions on 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 instead, as it requires a few steps specific to Umbraco Cloud.

13.latest to the latest version

Update _ViewImports.cshtml file

In Umbraco 14, Smidge has been removed from the CMS.

In the _ViewImports.cshtml of your project, remove the following lines:

Otherwise, it will cause an error on the front end.

Update program.cs file

Remove u.UseInstallerEndpoints(); from the program.cs

10.latest to 13.latest

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 that you upgrade to the closest 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 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:

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 .

IPublishedContent breaking changes in 8.1.0

Due to the 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

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.

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:

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.

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

7.4.0 to 7.6.0

Find a list of all the breaking changes below and

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.

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

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

7.1.0 to 7.2.0

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

Follow the to complete the upgrade.

7.0.2 to 7.1.0

Remove the /Install folder.

Follow the 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:

The usercontrol value has changed to: /create/user.ascx

7.0.0 to 7.0.1

Remove all uGoLive dlls from /bin
- These are not compatible with V7

6.latest to 7

Read and follow

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 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 and run it after the upgrade process is finished.

Version 4.8.0 to 4.10.0

Delete the

TableExists

umb-button

uui-button

umb-box

uui-box

Value(alias, culture)

bin/umbraco.linq.core.dll

{
    ...
    "ConnectionStrings": {
        "umbracoDbDSN": "Data Source=|DataDirectory|/Umbraco.sqlite.db;Cache=Shared;Foreign Keys=True;Pooling=True",
        "umbracoDbDSN_ProviderName": "Microsoft.Data.Sqlite",
        "umbracoCommerceDbDSN": "Data Source=|DataDirectory|/Umbraco.Commerce.sqlite.db;Mode=ReadWrite;Foreign Keys=True;Pooling=True;Cache=Shared",

    {
      "type": "mfaLoginProvider",
      "alias": "my.2fa.provider",
      "name": "My 2fa Provider",
      "forProviderName": "UmbracoUserAppAuthenticator",
      "meta": {
        "label":

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

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.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.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.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.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.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

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

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

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

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>();
            });
}

@{
    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>

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

App_Plugins

17.latest (LTS)

Fundamentals

Get to know Umbraco

Umbraco CMS Documentation

Legacy Documentation

Legacy versions on GitHub

Our Umbraco

Setup

Requirements

Built-in Property Editors

Installation

Install the latest .NET Software Development Kit (SDK)

Install Umbraco using CLI

Alternative Methods for Installing Umbraco

Running Umbraco on Linux/macOS

How to get started running Umbraco CMS on Linux or macOS

Upgrade your project

Upgrade Guides

Block Editors

Logging With Load Balancing

Block Grid

Customizing Block Editors

Creating custom views for blocks

Requirements

Browsers

Local Development

Hosting

Recommendation requirements to run Umbraco

Other recommendation

Database Account Roles

Property Editors

More information

Tutorials

Upgrade Unattended

Enable the unattended upgrade feature

Run the upgrade

Boot order

Unattended upgrades in a load-balanced setup

Server setup

Secure Sockets Layer (SSL) and HTTPS

Sidebar

Customize

Upgrades in Umbraco

What is involved in an upgrade

Database schema and content

Label

Data Type Definition Example

Load Balancing the Backoffice

Server Role Accessor

SignalR In Load Balanced Environments

Introducing a SignalR Backplane

Radiobutton List

Data Type Definition Example

Downgrades and Re-running Migrations

Downgrades are not strictly supported

Entity Data Picker

Textarea

Date Time Editors

Load Balancing Repository Caches

SignalR

Background Jobs

Temporary File Storage

Code examples

Using existing infrastructure

Azure SignalR Service

Particular downgrades are possible and safe

Downgrade process

Re-running Migrations

Without Models Builder

Supported features

Project customizations

Third-party packages

Considerations for major version upgrades

Before you upgrade

Value type

Content Example

MVC View Example

Without Models Builder

With Models Builder

Add values programmatically