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

1. Open your command line.

2. Install the Umbraco templates:

dotnet new install Umbraco.Templates

1. Create a new project:

dotnet new umbraco --name MyProject

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

cd MyProject

1. Build and run the newly created Umbraco site:

dotnet run

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

dotnet dev-certs https --trust

1. Open your browser and navigate to that URL.

2. Follow the instructions to finish up the installation of Umbraco.

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 installation

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

Visual Studio installation

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

Run Umbraco on IIS

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

VS Code installation

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

Installing Nightly Builds

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

Running Umbraco on Linux/macOS

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

Install Umbraco unattended

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

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

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

• One of the

• One of the following .NET Tools or Editors:

  • with the

  • 2022 version 17.12 or higher.

    • Optional: version 2022.3 and higher

• and higher

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.

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 .

How to install and configure your Umbraco installation.

Requirements

Defines the system requirements to run Umbraco.

Installation

Umbraco installation steps and guidelines.

Upgrade your project

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

Server setup

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

Configuration

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

Installing Nightly Builds

How to install the latest nightly builds.

This documentation platform covers only supported versions of the Umbraco CMS, excluding version 8. If you use an unsupported version, you need to go elsewhere.

Learn more about how long each major version of Umbraco is supported.

Legacy versions on GitHub

When a major version of Umbraco CMS goes End of Life (EOL), the documentation for this version will be unpublished 3 months later.

The documentation for all EOL versions will continue to be available on the UmbracoDocs GitHub repository.

Our Umbraco

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

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

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

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

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

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

For more information, see SeriLog Provided Sinks.

This feature enables you to work with your content without losing the context of what you are doing.

Document Types are in different sections than content but the sidebar enables you to make changes to them directly from the content you are editing.

In the example showcased above, new options are being added to a Data Type, without losing the context of the content. The example also shows how you can edit images, without being sent to the 'Media' section.

Customize

The sidebar is a feature that comes out of the box with Umbraco. The feature can be customized, which enables you as a developer to improve the workflow for your editors.

Schema Alias: Umbraco.DateTime

UI Alias: Umb.PropertyEditorUi.DatePicker

Returns: Date

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

Data Type Definition Example

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

Content Example

MVC View Example - displays a datetime

Typed

Dynamic (Obsolete)

The Block Editors are property editors that enabled you to build advanced editor tools using a set of predefined Document Types.

Umbraco CMS currently ships with two Block Editors: the Block List and the Block Grid.

Customizing Block Editors

Learn how to create custom views for the blocks used in your Block Grid or Block List property editors.

This section focuses on how to create data using the Umbraco backoffice.

There are three kinds of content in Umbraco:

• Your normal website content exists in the content section.

• Media content such as images, videos, and PDFs are stored in the Media section.

• Finally, Members, are used for user profiles and frontend authentication which you can find in the Members section.

A fundamental principle in Umbraco is that all content types have a definition (Document Types, Media Types, Member Types). These definitions are highly customizable, meaning you can add properties and have complete control over how the data is organized.

Defining Document Types, adding properties, and creating content.

Defining Media Types and uploading files to the media section, using upload fields and image cropper.

Defining Member Types and creating members for authentication and user profiles.

Creating and editing Data Types.

Schedule when content should be published / unpublished automatically.

Overview of how to add and reorder tabs, convert a group to a tab, and manage the “Generic” tab

Control who has access to the Umbraco backoffice and what permissions they have.

An introduction to Relations and Relation Types, creating, and managing relationships between different entities in Umbraco.

Using Dictionary Items, you can store a value for each language. Dictionary Items have a unique key that is used to fetch the value of the Dictionary Item.

How to keep the noise down whilst ensuring your important content versions stick around indefinitely.

On this page, you will find the default Document Types in Umbraco. If you want to use these Document Types, you can create them in the Settings section.

Document Type

A Document Type defines the content structure and fields that can be used across different content items. When creating a Document Type without a template, you focus solely on structured content without tying it to a specific design or layout. This is ideal for content that doesn’t require direct front-end rendering, such as reusable blocks or items managed within a headless CMS setup.

Use a Document Type without a template for structured, reusable content like metadata schemas, settings, or components such as product details and author profiles.

Document Type with Template

A Document Type with a Template combines the content structure with a predefined visual presentation. This approach links your structured content with a specific page design, ensuring a consistent and cohesive look and feel across your site. It allows you to manage content and its appearance separately, which makes updates more efficient.

Use a Document Type with a template for pages like blog posts, landing pages, or services that appear directly on the website.

Element Type

An Element Type is a Document Type without a template designed for reusabale and repeatable set of properties. These are primarily used in editors like the Block List Editor or Block Grid Editor to create structured, nested content.

Element Types are not part of the Content tree and cannot render directly on the front end. When created, the Is an Element Type flag in the Permissions tab is automatically set to True.

Use an Element Type when defining building blocks for complex page layouts, such as grid blocks or call-to-action sections. They are an essential part of modular content design.

Folder

The Folder in the Document Types section is used to organize and structure your Document Types within the Settings section. It serves purely as an organizational container, with no impact on the Content section or site functionality.

Use a Folder to create logical groupings, like a folder named Compositions to hold all your Composition Document Types. This makes it easier to navigate and manage your Document Types, especially in larger projects.

Folders are a powerful tool to keep your Document Types organized and your backoffice tidy.

Secure Sockets Layer (SSL) and HTTPS

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

File & folder permissions

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

Hosting v9+ in IIS

Information about hosting a v9 application using IIS.

Load Balanced setup

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

Running Umbraco on Azure Web Apps

Best practices for running Umbraco on Azure Web Apps.

Runtime modes

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

Templates

Creating, managing, and reusing templates in Umbraco.

Rendering content

Querying and rendering published content.

Rendering media

Querying and rendering media items.

Partial Views

Working with partial views in Umbraco's templates.

Stylesheets and JavaScript

Working with CSS and JavaScript in Umbraco's templates.

The Razor Cheatsheet is a collection of common methods used for building templates and views in Umbraco CMS.

Get the Umbraco 11 Cheatsheet: https://umbra.co/razorCheatsheet

You can also find the cheatsheet on GitHub where you can give feedback, contribute, or download the template used to generate the sheet.

Use the cheatsheet if you:

• Use Models Builder on your project and

• Use Umbraco 11.

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

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

Built-in Property Editors in Umbraco

Umbraco comes pre-installed with many useful property editors.

More information

• Customizing Data Types

Tutorials

• How to create a custom Property Editor

Schema Alias: Umbraco.DateTime

UI Alias: Umb.PropertyEditorUi.DatePicker

Returns: DateTime

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

Data Type Definition Example

There is one setting available for manipulating the DateTime property.

The setting involves defining the format. The default date format in the Umbraco backoffice is YYYY-MM-DD HH:mm:ss, but you can change it to a different format. See MomentJS.com for the supported formats.

Content Example

MVC View Example - displays a datetime

With Models Builder

@Model.DatePicker

Without Models Builder

@Model.Value("datePicker")

Add values programmatically

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

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

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

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

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

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

Schema Alias: Umbraco.Decimal

UI Alias: Umb.PropertyEditorUi.Decimal

Returns: decimal

Data Type Definition Example

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

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

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

Content Example

MVC View Example

With Models Builder

@Model.MyDecimal

Without Models Builder

@Model.Value("MyDecimal")

Add values programmatically

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

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

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

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

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

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

Schema Alias: Umbraco.EmailAddress

UI Alias: Umb.PropertyEditorUi.EmailAddress

Returns: String

Displays an email address.

Settings

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

Content Example

MVC View Example

Without Modelsbuilder

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

With Modelsbuilder

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

Add value programmatically

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

@using Umbraco.Cms.Core.Services;

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

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

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

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

Schema Alias: Umbraco.ColorPicker.EyeDropper

UI Alias: Umb.PropertyEditorUi.EyeDropper

Returns: string

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

Data Type Definition Example

Content Example

Example with Models Builder

@{
    var color = Model.Color?.ToString();

    if (color != null)
    {
        <body style="background-color: @color"></body>
    }
}

Example without Models Builder

@{
    var color = Model.Value<string>("Color");

    if (color != null)
    {
        <body style="background-color: @color"></body>
    }
}

Add values programmatically

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

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

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

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

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

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

Schema Alias: Umbraco.Label

UI Alias: Umb.PropertyEditorUi.Label

Returns: String

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

Data Type Definition Example

Value type

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

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

Content Example

MVC View Example

Without Models Builder

@{
    if (Model.HasValue("pageLabel")){
        <p>@(Model.Value("pageLabel"))</p>
    }
}

With Models Builder

@{
    if (!string.IsNullOrEmpty(Model.PageLabel))
    {
        <p>@Model.PageLabel</p>
    }
}

Add values programmatically

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

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

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

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

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

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

Schema Alias: Umbraco.MemberGroupPicker

UI Alias: Umb.PropertyEditorUi.MemberGroupPicker

Returns: string

The Member Group Picker opens a panel to pick one or more member groups from the Member section. The value saved is of type string (comma separated IDs).

Data Type Definition Example

Content Example

MVC View Example

Without Models Builder

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

With Models Builder

@if (!string.IsNullOrEmpty(Model.MemberGroup))
{
    <p>@Model.MemberGroup</p>
}

Add values programmatically

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

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

You can also add multiple groups by creating a comma separated string with the desired member group IDs.

@{
    // Set the value of the property with alias 'memberGroup'. 
    content.SetValue("memberGroup", "1067","1068");
}

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

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

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

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

Schema Alias: Umbraco.TextArea

UI Alias: Umb.PropertyEditorUi.TextArea

Returns: String

Textarea is an HTML textarea control for multiple lines of text. It can be configured to have a fixed character limit, as well as define how big the space for writing can be. By default, there is no character limit unless it's specifically set to a specific value like 200 for instance. If you don't specify the number of rows, 10 will be the amount of rows the textarea will be occupying, unless changed to a custom value.

Data Type Definition Example

Settings

Content Example

Without a character and rows limit

With a character limit and rows limit

MVC View Example

Without Models Builder

@{
    if (Model.HasValue("description")){
        <p>@(Model.Value<string>("description"))</p>
    }
}

With Models Builder

@if (!Model.HasValue(Model.Description))
{
   <p>@Model.Description</p>
}

Add value programmatically

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

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

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

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

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

@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!");
}

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 Element Types 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 Umbraco Flavored Markdown is used):

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.

In this article you can learn about the different options you have for configuring the Rich Text Editor (RTE).

Toolbar

You have full control over which options should be available on the RTE.

In the example above, all 38 options have been enabled. These options include font styles like bold and italics, bullet lists, and options to embed videos and insert images.

You can customize the look of the toolbar:

• Enhance the capabilities of the toolbar by enabling or disabling extensions.

• Use the Toolbar designer to group together items and add additional rows if needed.

Statusbar

As well as the toolbar, you can configure extensions for the statusbar.

Stylesheets

To apply custom styles to the Rich Text Editor, you can select from any existing stylesheets.

Stylesheets can be created in the Settings section. To learn more about this feature, see the Stylesheets in the Backoffice article.

Dimensions

Define height and width of the editor displayed in the content section.

Maximum size for inserted images

Define the maximum size for images added through the Rich Text Editor.

If inserted images are larger than the dimensions defined here, the images will be resized automatically.

Overlay Size

Select the width of the link picker overlay. The overlay size comes in three sizes: Small, Medium, Large, and Full.

Available Blocks

Blocks can be added as elements in the Rich Text Editor. Configuration and rendering of Blocks are described in the Blocks in Rich Text Editor article.

Image Upload Folder

Images added through the RTE are by default added to the root of the Media library.

Sometimes you might want to add the images to a specific folder. This folder can be configured using the "Image Upload Folder" setting.

Ignore User Start Nodes

Some of the backoffice users might be restricted to a specific part of the content tree. When the "Ignore User Start Nodes" is checked, the users can pick any piece of content from the content tree, when adding internal links through the RTE.

API Users allow for authorizing external access to the Management API.

An API User is identical to a regular User except for one thing: It has no password. In fact, API Users are not allowed to log into the backoffice like regular Users.

Instead, API Users hold the Client Credentials used to authorize against the Management API. When an external source authorizes using Client Credentials, it effectively assumes the identity of the API User.

Since API Users are identical to regular Users their backoffice access can be controlled in the same way. This allows for imposing detailed access control on the external sources connected to the Management API.

Creating an API User

To create an API User:

1. Go to the Users section in the backoffice.

2. Select Create -> API User.

3. Enter the Name and Email of the new API user.

4. Select which User group the new user should be added to.

5. Click Create user.

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

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

Setting up prerequisites

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

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

Add permissions to NuGet cache folder

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

When the site is published these files are copied from the NuGet cache folder to wwwroot/umbraco and wwwroot/App_Plugins and these folders will typically have the correct permissions. For more information on setting permissions, see the article.

Add new launch profile

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

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

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

And finally the site is running from your local IIS:

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

1. Go to and download VS Code for free.

2. Once installed, launch VS Code.

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

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!

Umbraco 15 changes the internal data format of all .

If you maintain a large Umbraco site with extensive Block Editor usage, the upgrade to Umbraco 15+ might require a long-running content migration. For the duration of the migration, your site will be unresponsive and unable to serve requests.

You can track the progress of the migration in the logs.

It is advised to before upgrading. This will make the migration run faster.

Parallelizing the content migration

It is possible to parallelize the content migration. This will speed up the migration for large sites.

For certain content structures, parallel content migration will fail. Therefore, parallel content migration is strictly opt-in.

If parallel content migration fails, the database state will be rolled back to the last known good state. You can then disable parallel content migration, and try the migration again.

To enable parallel content migration, add an IComposer implementation to configure the ConvertBlockEditorPropertiesOptions before initiating the upgrade process:

Opting out of the content migration

It is strongly recommended to let the migration run as part of the upgrade. However, if you are upgrading to Umbraco versions 15, 16, or 17, you can opt out of the migration. Your site will continue to work, albeit with a certain degree of performance degradation.

You can opt out of migrating each Block Editor type individually. To opt-out, add an IComposer implementation to configure the ConvertBlockEditorPropertiesOptions before initiating the upgrade process:

Subsequently, you are responsible for performing the content migration yourself. This must be done before upgrading past Umbraco 17.

Custom code is required to perform the content migration. You can find inspiration in the core migrations:

• for Block List properties.

• for Block Grid properties.

• for Rich Text Editor properties.

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

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.

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:

1. The HstsCheck health check - This will result in a failed healthcheck.

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

Schema Alias: Umbraco.CheckBoxList

UI Alias: Umb.PropertyEditorUi.CheckBoxList

Returns: IEnumerable<string>

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

Data Type Definition Example

Content Example

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

Schema Alias: Umbraco.ListView

UI Alias: Umb.PropertyEditorUi.Collection

Returns: IEnumerable<IPublishedContent>

Collection displays a collection of categories when it is enabled on a Document Type with children.

Configure Collection

Once Collections are configured, the parent content item displays its child items in a list view format within the content item itself. If Collections are not configured, the child items are displayed directly in the Content Tree, rather than being grouped within the parent content item.

Settings

Columns Displayed

It is possible to add more columns to the collection, via adding the properties through the picker modal. These properties are based on the Data Types which are used by the Document Type. The properties will listed for selection.

Once you have selected a column you want to display, define what its heading label should be and what kind of value it should display. You can also move the headers around, re-ordering how they should look. This is done by the move icon on the left side of the alias.

The template section is where you define what kind of value you want to display. The value of the column is in the value variable.

Layouts

Collection comes with two layouts by default. A list and a grid view. These views can be disabled if you are not interested in any of them.

You can also make your own layout and add it to the settings. For example, if you wanted to change the width or length of the grid, you will be able to do so.

Order By

Will sort your collection by the selection you choose in the dropdown. By default it selects "Last edited" and you get the following three columns:

• Last edited - When the content node was last edited and saved.

• Name - Name of the content node(s).

• Created by - This is the user who the content node was created by.

You can add more sorting to this collection by adding more datatypes to the columns in the "Columns Displayed" section.

Order Direction

You can select order of the content nodes displayed, "Ascending [a-z]" or "Descending [z-a]". The order is affected by the "Order By" selection.

Page Size

Defines how many child content nodes you want to see per page. This will limit how many content items you will see in your collection. If you set it to 5, then only 5 content items will be shown in the collection.

Workspace View icon

Changes the icon in the backoffice of the collection. By default it will look like the image below.

Workspace View name

You can change the name of the collection itself. Default if empty: 'Child Items'.

Show Content Workspace View First

Enable this to show the Content Workspace View by default instead of the collection's.

Content Example

Generic field value

This example shows how to use a generic field from a child item and display its value in a collection.

You can use the syntax to display the label value. Here, the {=value} placeholder retrieves the value of the Email property and displays it in the collection, as shown in the image below:

Content name

First, a Content Picker property needs to be present on the content item. In this example, the child item has gotten a Content Picker Data Type with the alias of contentPicker.

The child item has a document and the value that should be displayed is the name of the picked value. The next step is to reconfigure the template value in the collection setting.

This will take the value picked up by the content picker.

And display it in the collection. Shown in the example below:

Schema Alias: Umbraco.ContentPicker

UI Alias: Umb.PropertyEditorUi.DocumentPicker

Returns: IPublishedContent

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

Data Type Definition Example

Document Picker Example

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

Schema Alias: Umbraco.MemberPicker

UI Alias: Umb.PropertyEditorUi.MemberPicker

Returns: IPublishedContent

The member picker opens a panel to pick a specific member from the member section. The value saved is of type IPublishedContent.

Data Type Definition Example

Content Example

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

Schema Alias: Umbraco.MultipleTextstring

UI Alias: Umb.PropertyEditorUi.MultipleTextString

Returns: array of strings

The Repeatable textstrings property editor enables a content editor to make a list of text items. For best use with an unordered-list.

Data Type Definition Example

Content Example

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

Schema Alias: Umbraco.Integer

UI Alias: Umb.PropertyEditorUi.Integer

Returns: Integer

Numeric is an HTML input control for entering numbers. Since it's a standard HTML element the options and behaviour are all controlled by the browser and therefore is beyond the control of Umbraco.

Data Type Definition Example

Minimum

This allows you to set up a minimum value. If you will always need a minimum value of 10 this is where you set it up and whenever you use the datatype the value will always start at 10. It's not possible to change the value to anything lower than 10. Only higher values will be accepted.

Step Size

This allows you to control by how much value should be allowed to increase/decrease when clicking the up/down arrows. If you try to enter a value that does not match with the step setting then it will not be accepted.

Maximum

This allows you to set up a maximum value. If you will always need a maximum value of 100 this is where you set it up. It's not possible to change the value to anything higher than 100. Only lower values will be accepted.

Settings

Content Example

MVC View Examples

Rendering the output casting to an int (without Models Builder)

By casting the output as an int it's possible for you to do mathematical operations with the value.

Rendering the output casting to a string (Without Models Builder)

You can also render the output by casting it to a string, which means you will not be able to do mathematical operations

With Models Builder

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 .

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:

Schema Alias: Umbraco.RadioButtonList

UI Alias: Umb.PropertyEditorUi.RadioButtonList

Returns: string

Pretty much like the name indicates this Data type enables editors to choose from list of radio buttons and returns the value of the selected item as string.

Data Type Definition Example

Content Example

MVC View Example

Typed

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

Schema Alias: Umbraco.TextBox

UI Alias: Umb.PropertyEditorUi.TextBox

Returns: String

Textbox is an HTML input control for text. It can be configured to have a fixed character limit. The default maximum amount of characters is 512 unless it's specifically changed to a lower amount.

Data Type Definition Example

Content Example

Without a character limit

With a character limit

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

Schema Alias: Umbraco.UserPicker

UI Alias: Umb.PropertyEditorUi.UserPicker

Returns: IPublishedContent

The user picker opens a panel to pick a specific user from the Users section. The value saved is of type IPublishedContent.

Data Type Definition Example

Content Example

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

The Rich Text Editor (RTE) in Umbraco is based on the open-source editor .

Out of the box, Tiptap has limited capabilities and everything is an extension by design. Basic text formatting features such as bold, italic, and underline are their own extensions. This offers great flexibility, making the rich text editor highly configurable. The implementation in Umbraco offers a wide range of built-in extensions to enhance the Tiptap editor capabilities.

Using the same extension points, this article will show you how to add a custom extension to the rich text editor.

Native Tiptap extensions

Tiptap has a library of supported native extensions. You can find a list of these extensions on the . While many of these are open source, there are also available for commercial subscriptions.

Tiptap extension types

There are two types of extension: tiptapExtension and tiptapToolbarExtension.

The tiptapExtension extension is used to register a native . These will enhance the capabilities of the rich text editor itself. For example, to enable text formatting, drag-and-drop functionality and spell-checking.

The tiptapToolbarExtension extension adds a toolbar action that interacts with the Tiptap editor (and native Tiptap extensions).

Adding a native extension

In this example, you will take the native Tiptap open-source extension . Then register it with the rich text editor and add a toolbar button to invoke the Task List action.

1. Install the Highlight extension from the npm registry.

1. Create the code to register the native Tiptap extensions in the rich text editor.

1. Create the toolbar action to invoke the Highlight extension.

Once you have the above code in place, they can be referenced using a .

Upon restarting Umbraco, the new extension and toolbar action will be available in the Tiptap Data Type configuration settings.

On this page you will find the media types and Data Types in Umbraco. These types are not created automatically after an upgrade. If you want to use the new types, you can create them yourself.

Data Types

UploadArticle

The UploadArticle Data Type has the following configuration:

• Property editor: FileUpload

• Accepted file extensions: pdf, docx, doc

UploadAudio

The UploadAudio Data Type has the following configuration:

• Property editor: FileUpload

• Accepted file extensions: mp3, weba, oga, opus

UploadVectorGraphics

The UploadVectorGraphics Data Type has the following configuration:

• Property editor: FileUpload

• Accepted file extensions: svg

UploadVideo

The UploadVideo Data Type has the following configuration:

• Property editor: FileUpload

• Accepted file extensions: mp4, webm, ogv

Media Types

UmbracoMediaArticle

The UmbracoMediaArticle media type has the following properties:

• umbracoFile - Upload File

• umbracoExtension - Label (string)

• umbracoBytes - Label (bigint)

UmbracoMediaAudio

The UmbracoMediaAudio media type has the following properties:

• umbracoFile Upload Audio

• umbracoExtension Label (string)

• umbracoBytes Label (bigint)

UmbracoMediaVectorGraphics

The UmbracoMediaVectorGraphics media type has the following properties:

• umbracoFile - Upload Vector Graphics

• umbracoExtension Label (string)

• umbracoBytes Label (bigint)

UmbracoMediaVideo

The UmbracoMediaVideo media type has the following properties:

• umbracoFile - Upload Video

• umbracoExtension - Label (string)

• umbracoBytes - Label (bigint)

A Data Type defines the type of input for a property. So when adding a property (on Document Types, Media Types and Members) and selecting the Type you are selecting a Data Type. There are preconfigured Data Types available in Umbraco and more can be added in the Settings section.

What is a Data Type?

A Data Type can be something basic such as TextString, Number, True/False and so on. Or it can be more complex such as Multi Node Tree Picker, Image Cropper, Block Grid and so on.

The Data Type references a Property Editor and if the Property Editor has settings these are configured on the Data Type. This means you can have multiple Data Types referencing the same Property Editor.

An example of this could be to have two dropdown Data Types both referencing the same dropdown Property Editor. One configured to show a list of cities, the other a list of countries.

Creating a new Data Type

Follow these steps to create a new Dropdown Data Type:

1. Go to the Settings section within the backoffice.

2. Select the + icon to the right of the Data Types folder.

3. Choose New Data Type....

4. Name the Data Type.

5. Click on Select a property editor.

6. Find and click on the Dropdown editor.

7. Click Select.

8. Choose whether to enable multiple selections.

9. Add options.

10. Save the Data Type once you have added the required configuration.

When you're happy with the list press Save. It is now possible to select this Data Type for a property on Document Types, Media Types, and Members. Doing this will then create a dropdown list for the editor to choose from and save the choice as a string.

Customizing Data Types

To customize an existing Data Type go to the Settings section, expand the Data Types folder and select the Data Type you want to edit.

Besides the Data Types that are available out of the box there are some additional Property Editors. For example, think of the Slider and Block List.

Viewing Data Type References

To view the Data Type reference, go to the Settings section and expand the Data Types folder. Select the Data Type you wish to view the reference for and click the Info tab.

This gives you an overview of the Types that currently use the Data Type.

Learn more about viewing references or implementing tracking in the article.

More information

Related Services

Umbraco Learning Base Channel

Here's a list of the default Data Types that come installed with Umbraco. There are plenty more that you can create based on the installed .

Approved Color

Adds a list of approved colors. The approved colors are added as hex values by using the color picker. Optionally, you can enable labels to give the colors different names.

Checkbox List

Displays a list of preset options as a list of checkbox controls. The preset options are added when configuring a Property Editor using the Data Type. Alternatively, the options can also be updated in the Settings section under Data Types. The value saved is a comma-separated string of IDs.

Content Picker

The Content Picker opens a modal to pick a specific page from the content structure. The value saved is the selected page's ID.

Date Picker

Displays a calendar UI for selecting date and time. The value saved is a standard DateTime value but does not contain time information.

Date Picker with time

Displays a calendar UI for selecting date and time. The value saved is a standard DateTime value.

Dropdown

Displays a list of preset options as a list where only a single value can be selected. The default Data Type does not contain any predefined options. The value saved is the selected value as a string.

Dropdown multiple

Displays a list of preset options as a list where multiple values can be selected. The default Data Type does not contain any predefined options. The value saved is a comma-separated string of IDs.

Image Cropper

Allows to upload and crop images by using a focal point. Specific crop definitions can also be added. This Data Type is used by default on the Image Media Type.

Image Media Picker

The Image Media Picker opens a modal to pick images from the Media tree or images from your Computer. The value saved is the selected media node UDI.

Label

Is a non-editable control and can be used to only display the value. It can also be used in the Media section to load in values related to the node, such as width, height and file size.

There are six Label Data Types:

• Label (bigint) - Allows to save a big integer value for a Label.

• Label (datetime) - Allows to set a DateTime value for a Label.

• Label (decimal) - Allows to set a decimal value for a Label.

• Label (integer) - Allows to set an integer value for a Label.

• Label (string) - Allows to set a long string value for a Label.

• Label (time) - Allows to set time for a Label

List View - Content

This Data Type is used by Document Types that are set to display as a Collection.

List View - Media

This Data Type is used by Media Types that is set to display as a Collection.

List View - Members

This Data Type is used by Member Types that is set to display as a Collection.

Media Picker

The picker opens a modal to pick a specific media item from the Media tree. The value saved is the selected media node UDI.

Member Picker

Displays a dropdown with all the available members. A single member can be selected. The value saved is the ID of the member.

Multi URL Picker

This Data Type allows an editor to add an array of links. These can either be internal Umbraco pages external URLs or links to media in the Media section. The Data Type can be configured by limited number of links it is possible to add.

Multiple Image Media Picker

The picker opens a modal to pick multiple images from the Media tree. The value saved is a comma separated string of media node UDIs.

Multiple Media Picker

The picker opens a modal to pick multiple media items from the Media tree. The value saved is a comma separated string of media node UDIs.

Numeric

A textbox to input a numeric value.

Radiobox

This Data type enables editors to choose from a list of radiobuttons.

Richtext Editor

A TipTap-based What You See Is What You Get (WYSIWYG) editor. This is the standard editor used to edit a larger amount of text. The editor has a lot of settings, which can be changed on the Richtext editor Data Type in the Settings section.

Learn more about the configuration options in the .

Tags

A textbox that allows you to use multiple tags on a Document Type. You can specify a Tag Group for the Data Type, if you need to use Tags on different sections of your site.

Textarea

A textarea provides a multi-line plain-text editing control. You can set the maximum allowed characters for the textarea and the number of rows, if any.

Textstring

A normal HTML input text field.

True/False

A checkbox which saves either 0 or 1, depending on the checkbox being checked or not. A common use is to create a property with the 'umbracoNaviHide' alias and the Data Type True/False. This will provide editors with the option to hide nodes in the navigation menu on the website.

Upload

Adds an upload field, which allows documents or images to be uploaded to Umbraco. This does not add them to the media library, they are added to the document data.

There are five Upload Data Types:

• Upload Article - Used for uploading and storing documents.

• Upload Audio - Used for uploading and storing digital audio files.

• Upload File - Used for uploading and storing different types of files in the Media section

• Upload Vector Graphics - Used for uploading and storing Scalable Vector Graphics (svg) files which are text files containing source code to draw the desired image.

• Upload Video - Used for uploading and storing video files.

In this section, an overview is given of how to add and reorder tabs, convert a group to a tab and manage the “Generic” tab.

Adding a tab

Using tabs, you can organize properties in the backoffice to provide a tailored and efficient workflow for editors creating and maintaining Content, Media and Members.

Tabs allow you to add horizontal organization in your Document Types, Media Types and Member Types. This is handy for types that need a more defined hierarchy or have many properties and groups.

To add a tab, follow these steps:

1. Go to Settings.

2. Create or select a Document Type/Media Type/Member Type and click Add tab.

Reordering tabs

To reorder tabs, follow these steps:

1. Go to Settings.

2. Select a Document Type/Media Type/Member Type.

3. Select Reorder.

4. You can drag the tab where you want, manually add a numeric value next to the tab name or use the arrows to set a value.

   This is important when using compositions, as you want to always display a tab/group at a certain position by setting a manual numeric value.
5. Select I am done reordering.

6. Click Save.

Convert a group to a tab

To convert a group to a tab, follow these steps:

1. Go to Settings.

2. Select a Document Type/Media Type/Member Type.

3. Select Reorder.

4. You can drag the group to the Convert to tab option.

5. Select I am done reordering.

6. Click Save.

Managing the “Generic” tab

Once you start adding tabs, you might see a “Generic” tab appear. This is done to hold groups and properties that are not assigned to a tab. For example, a group of properties coming from a composition that has no tab. In order to display the groups and properties correctly and have a solid data structure, they will be displayed under the “Generic” tab.

To manage the Generic tab on a Document Type/Media Type:

1. Go to the Composition Document Type/Media Type.

2. Click Add tab and enter the Name for the tab. All existing groups and properties are added to the tab.

3. Go to the Document Type/Media Type, the Generic tab will now be replaced by the tab from the composition.

Each document in Umbraco can be scheduled for publishing and unpublishing on a pre-defined date and time.

You can find the options to do this click on the arrow next to the Save and publish button and pick Schedule...

This will open a Schedule Publishing dialog where you can specify dates and time.

Timezones

Your server may be in a different timezone than where you are located. You are able to select a date and time in your timezone and Umbraco will make sure that the item gets published at that time. So, if you select 12 PM then the item will be published at 12PM in the timezone you are in. This may be 8 PM on the server, which is indicated when you select the date and time.

If you are in the same timezone as the server, this message will not appear under the date picker.

Permissions

All users with access to the Content section in the Umbraco backoffice are able to schedule content for publishing/unpublish.

Configuration

In some cases you will need to adjust your configuration to ensure that scheduled publishing/unpublishing works. The schedule works by the server sending an HTTP(S) request to itself.

If you are in a load balanced environment special care must be given to ensure you've configured this correctly,

If you are not load balancing, the way that Umbraco determines the base URL to send the scheduled HTTP(S) request to is as follows:

• umbracoSettings:settings/web.routing/@umbracoApplicationUrl if it exists (see for details)

• Else umbracoSettings:settings/scheduledTasks/@baseUrl if it exits (deprecated)

• Else umbracoSettings:distributedCall/servers if we have the server in there (deprecated, see load balance docs)

• Else it's based on the first request that the website receives and uses the base URL of this request (default)

If the umbracoApplicationUrl is used, the value also specifies the scheme (either HTTP or HTTPS). The request for scheduled publishing will always be sent over HTTPS if the appSettings umbracoUseSSL is set to true.

Troubleshooting

If your scheduled publishing/unpublishing is not working as expected it is probably an issue that your server cannot communicate with the scheduled publishing endpoint. This can be caused by a number of reasons such as:

• Url rewrites in place that prevent the endpoint from being reached

• DNS misconfiguration not allowing the server to communicate to the base URL used in the first request that the website receives - which could be directly affected by a firewall/Network Address Translation (NAT)/load balancer that your server sites behind

• Secure Sockets Layer (SSL) and/or umbracoUseSSL misconfiguration not allowing the server to communicate to the scheduled publishing endpoint on the correct http/https scheme

To better diagnose the issue you can temporarily change your log4net config settings to be DEBUG instead of INFO. This will give you all sorts of information including being able to see whether or not the scheduled publishing endpoint is being reached or not.

In some cases it might be easiest to specify the setting. This is to ensure that your server is communicating to itself on the correct URL.

Umbraco sections are built around the concept of 'trees' and there is an implicit relationship between items in a section tree.

We refer to these relationships in the manner of a 'Family Tree'. One content item might be the 'Parent' of some content items, and those items would be referred to as the 'Children' of that parent. Items within the same branch of the tree can also be described as 'Ancestors' or 'Descendants' of an item.

There are methods available to support querying content items by their relative position to the current page. This is possible using the following concepts: Model.Ancestors(), Model.Children(), or Model.Descendants().

In some cases there are no direct relationships between two items in a tree, but they are still somehow 'related'. This could be the alternate language translation pages of a content page.

In other cases there is a 'relation' between different types of entities. This could be a relation between Content and Member, or Member and MediaFolder. You might need to be able to retrieve and display the uploaded images from a specific logged-in Member.

These are the scenarios where the concept of Umbraco Relations provides a solution.

The Concept of Umbraco Relations

Umbraco Relations allow you to relate almost any object in Umbraco to almost any other Umbraco object. This is done by defining a new Relation Type.

How is this different to pickers?

With a Content, Member, or Media picker the relationship only works as a 1-way street. The content item knows it has 'picked' another content item but that other content item does not know where it has been picked.

Umbraco Relations works as a 2-way street. When creating a relation between two different types of entities, it will be possible to find one entity from the other and vice versa. As an example this provides the option to list out all the pages that a content banner had been picked on.

Relation Types

A Relation Type specifies how two types of entities are related. Two items might be related under multiple Relation Types, and you might only be interested in your 'Related Language Page' Relation Type.

Viewing Relations

It is possible to view the existing Relation Types from the Umbraco backoffice:

1. Access the Umbraco Backoffice.

2. Navigate to the Settings section.

3. Locate the Advanced group in the sidebar.

4. Select Relations.

On the dashboard all defined relations will be listed. Select a Relation to view a list of all the objects that have been related for that specific Relation Type.

Creating Relations

You can create Relations using the RelationService API via code.

Use cases

You might want to create a 'Relation' between two objects either as:

• A response to a backoffice event. For example, a content item being published that has picked other content items. Storing a relationship between these items would make querying between them easier. Perhaps show all the pages on which a particular 'banner' has been picked.

• A logged-in member on the front end of an Umbraco website might have the facility to upload images. In response, the implementation could store the photos programmatically in the Media Section and at the same time, create a Relation to record the relationship between the member and their uploaded pictures. On an image gallery page, it would be possible to display all the gallery images for the current logged-in Member using the relations.

Community Packages

Some of the community packages that use Relations are listed below:

• - a content picker that automatically creates Relations.

• - allows you to relate two items via the Backoffice.

• - Provides a LinkedPages context item to show, edit, and add relations between content pages.

A new version is created whenever you save and publish a content item in Umbraco. This is how you can roll back to a previous version. Every saved version stores a record in the database, not only for the version but also for each content item property for that version. In a multi-lingual site, further rows are added for every culture variation. Over time this amount of data can build and swallow up the capacity of your SQL Server and slow the performance of the Umbraco backoffice.

How it works

The default cleanup policy will:

• Not delete any versions created over the previous 4 days. The recent version history is preserved. See the KeepAllVersionsNewerThanDays setting.

• 'Prune' versions 4 days after they are created. The last version of a content item saved on a particular day will be kept but earlier versions from that day will be deleted.

• Delete all versions older than 90 days. See the KeepLatestVersionPerDayForDays setting.

• Never delete any versions that are currently 'published'.

• Never delete any specific versions marked as 'Prevent Cleanup' in the Backoffice version history.

The feature can be configured in the appSettings.json:

For sites with stricter requirements, it is possible to opt-out of both options globally, see and by Document Type.

Additionally, it is possible to keep the feature enabled but mark specific versions to keep forever.

It is worth noting that whilst we delete rows, we do not shrink database files or rebuild indexes. For upgraded sites with a lot of history you may wish to perform these tasks. If they are not part of your regular database maintenance plan already.

Overriding global settings

It is possible to override the global settings per Document Type in the backoffice to prevent unwanted cleanup. This can be managed in the "permissions" Content App for each Document Type.

Prevent cleanup of important versions

It is possible to mark important content versions as "prevent cleanup" to ensure they are never removed. This happens via the new and improved rollback modal which can be found on the "info" content app for each document.

1. Open rollback modal.
2. Click Prevent cleanup button for each important version.

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

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

How to get started running Umbraco CMS on Linux or macOS

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

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

To do this follow the guide.

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

To create a project, there are two options:

• Continue creating projects using the .NET CLI.

• Create new projects using Visual Studio (only macOS).

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

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

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

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

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

1. Create a folder and navigate into it:

mkdir MyDockerProject
cd MyDockerProject

1. Create a new Umbraco project with Docker support:

dotnet new umbraco -n MyDockerProject --add-docker

1. Add Docker Compose files:

dotnet new umbraco-compose -P "MyDockerProject"

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

    • setup.sql

    • startup.sh

  • MyDockerProject/

    • Your project files

    • Dockerfile

    • .dockerignore

  • .env

  • docker-compose.yml

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.

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

docker compose up

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

Option 2: Using SQLite

1. Create a new folder and navigate into it:

mkdir MyDockerSqliteProject
cd MyDockerSqliteProject

1. Create a new Umbraco project:

dotnet new umbraco -n MyDockerSqliteProject

1. Add a Dockerfile

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

1. Build the container:

docker build -t umbraco-sqlite .

1. Run the container:

docker run -p 8080:8080 umbraco-sqlite

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

• 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

• /Views

• /models

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.

• -p or --Port: Used to specify the port the site will run on. Defaults to 44372.

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

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:

• Overview of DFS Replication in Windows Server 2008 R2

• Watch an intro to installing and working with DFS

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

{
    "Umbraco": {
        "CMS": {
            "Examine": {
                "LuceneDirectoryFactory" : "TempFileSystemDirectoryFactory"
            }
        }
    }
}

• ~/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 Azure Web Apps

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.

{
    "Umbraco": {
        "CMS": {
            "Examine": {
                "LuceneDirectoryFactory" : "TempFileSystemDirectoryFactory"
            }
        }
    }
}

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

{
    "Umbraco": {
        "CMS": {
            "Examine": {
                "LuceneDirectoryFactory" : "SyncedTempFileSystemDirectoryFactory"
            }
        }
    }
}

Advanced techniques

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

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

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

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

• SchedulingPublisher - The Umbraco instance usually used for backoffice access, responsible for running scheduled tasks.

• Subscriber - A scalable instance that subscribes to content updates from the SchedulingPublisher server, not recommended to be used for backoffice access.

Explicit SchedulingPublisher server

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

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

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

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

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

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

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

Now that your subscriber servers are using your custom SubscriberServerRoleAccessor class, they will always be deemed 'Subscriber' servers and will not attempt to run the automatic server role election process or task scheduling.

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

Subscriber servers - Read-only database access

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

• umbracoServer

• umbracoNode

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

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

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

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

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

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

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

Options:

• TimeToRetainInstructions - The timespan to keep instructions in the database; records older than this number will be pruned.

• MaxProcessingInstructionCount - The maximum number of instructions that can be processed at startup; otherwise the server cold-boots (rebuilds its caches)

• TimeBetweenSyncOperations - The timespan to wait between each sync operations

• TimeBetweenPruneOperations - The timespan to wait between each prune operation

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

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:

Shows how to perform common logical tasks in Razor like if/else, foreach loops, switch statements and using the @ character to separate code and markup.

The @ symbol

The @ symbol is used in Razor to initiate code, and tell the compiler where to start interpreting code, instead of returning the content of the file as text. Using a single character for this separation, results in cleaner, compact code which is easier to read.

@* Writing a value inside a html element *@

<p>@Model.Name</p>

@* Inside an attribute *@
<a href="@Model.Url()">@Model.Name</a>

@* Using it to start logical structures *@
@if (selection?.Length > 0)
{
    <ul>
        @foreach (var item in selection)
        {
            <li>
                <a href="@item.Url(PublishedUrlProvider)">@item.Name</a>
            </li>
        }
    </ul>
}

Embedding comments in razor

Commenting your code is important, use comments to explain what the code does. @* *@ indicates a comment, which will not be visible in the rendered output.

@* Here we check if the name is equal to foobar *@
@if (Model.Name == "foobar")
{
    @foreach (var child in Model.Children())
    {
        @* here we write stuff for each child page *@
        <p>write stuff</p>
    }
}

If/else

If/else statements perform one task if a condition is true, and another if the condition is not true

@if (Model.Name == "home")
{
    <p>This is the homepage!</p>
}

@if (Model.NodeTypeAlias == "TextPage")
{
    <p>This is a textpage</p>
}
else
{
    <p>This is NOT a textpage</p>
}

Foreach loops