Resources and links for older versions of Umbraco CMS.
This documentation platform covers only major versions of the Umbraco CMS since Umbraco 9. If you are using an older version of Umbraco CMS, you will need to go elsewhere.
The documentation for Umbraco 7 and 8 lives on .
Get to know Umbraco
All the fundamentals of using Umbraco - from making a local installation to extending the backend.
In this part of the Umbraco CMS documentation, you can get to know the product and the default functionality. It is here you start your Umbraco journey with the installation, setup, and basics of working with the CMS.
Find requirements for both local development and hosting as well as guides for installing and upgrading Umbraco CMS.
Backoffice
Learn about the different sections found in the Umbraco CMS backoffice and get an overview of the available features.
Data
Dive a little deeper and learn how to create different types of data directly from the Umbraco CMS backoffice.
Design
Get to know the different options the Umbraco CMS backoffice provides for designing your website.
Code
A high-level overview of working with some of the more advanced elements like services and notifications.
Umbraco CMS Documentation
Your main resource when building and managing an Umbraco CMS website.
Umbraco CMS is a flexible and editor-friendly Content Management System (CMS) that allows you to create beautiful and modern websites. Use the latest version of .NET, integrate with your favorite services, and help your customers launch a website tailored to their specific needs.
Learn more about Umbraco CMS and get an overview of the top features on Umbraco.com.
The documentation for Umbraco CMS provides information for experienced Umbraco and .NET developers. It also offers guides and high-level articles for people starting out with the CMS.
Learn the basics of working with Umbraco CMS. How to install and setup your first site is also included in this section.
Install Umbraco CMS
Ready to get started with Umbraco? Head over to the Setup section to learn how to install Umbraco CMS.
Tutorials
Find detailed step-by-step guides on everything from building a site from scratch to implementing a custom maintenance page.
Built-in Property Editors
Logging With Load Balancing
Umbraco v8+ uses Serilog for logging. When load balancing Umbraco consideration should be given as to how the log files from each server will be accessed.
There are many Serilog Sinks available. One of these may be appropriate to store logs for all servers in a central repository such as Azure Application Insights or Elmah.io.
Below you can find the minimum requirements to run Umbraco 13 on your machine:
One of the
One of the following .NET Tools or Editors:
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 .
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 the above, as Umbraco version 13 is based on .NET 8 you will need to follow the .NET 8 supported versions.
For more information, see thearticle 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 .
Property Editors
Learn more about the default property editors that ships with an Umbraco installation.
A Property Editor is the editor that a Data Type references. A Data Type is defined by a user in the Umbraco backoffice and references a Property Editor. In Umbraco a Property Editor is defined in a JSON manifest file and associated JavaScript files.
When creating a Data Type, specify the property editor for the Data Type to use by selecting from the "Property editor" list (as shown below).
Umbraco comes pre-installed with many useful property editors.
More information
Tutorials
Infinite Editing
This section explains how the concept of infinite editing in the Umbraco backoffice works.
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 infinite editing enables you to make changes to them directly from the content you are editing.
Infinite Editing
In the example showcased above, prevalues are being added to a Data Type, without losing the context of the content that's being worked on. The example also shows how you can edit images, without being sent to the 'Media' section.
Customize
Infinite editing 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.
Read more
Block Editors
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.
Learn how to create custom views for the blocks used in your Block Grid or Block List property editors.
Get an overview of available configurations for the label properties.
Decimal
Alias: Umbraco.Decimal
Returns: decimal
Data Type Definition Example
Date
Returns: Date
Displays a calendar UI for selecting dates which are saved as a DateTime value.
Data Type Definition Example
The only setting that is available for manipulating the Date property is to set a format. By default the format of the date in the Umbraco backoffice will be
Configuring The Grid Layout
A grid layout contains multiple configuration options to allow developers to tailor the grid to a very specific site design. Configuring the layout can be divided into 2 overall parts:
Layouts
A layout is the general grid "container", it contains one or more sections which content editors can use to insert preconfigured rows. There are 2 main usage scenarios of layouts:
Running Umbraco on Linux/macOS
Since Umbraco 9 it has been possible to run Umbraco CMS natively on Linux or macOS High Sierra 10.13 and newer.
With Umbraco CMS on .NET Core, Linux and macOS is natively supported with SQLite as the database.
In the below section, we describe how to get started with running Umbraco CMS on Linux or macOS.
How to get started running Umbraco CMS on Linux or macOS
To get started with Umbraco CMS first have a look at the
The grid layout editor offers non-technical editors a more visual editing environment to layout content pages and enter content of many different kinds.
The editor offers many configuration options, and as a website implementor, you could be tempted to use the grid for nearly every kind of content entry - this is however not encouraged.
To help developers determine when to use the grid layout, we've outlined the 2 major use-cases below.
1. As a RTE Replacement
The grid should primarily be used to replace content entry in a rich text editor (RTE). Where editors before would struggle with aligning images, lists and text or using tables inside the editor to layout content in columns.
The grid solves this scenario, giving editors predefined layouts and editors to enter content. They do not have to worry about how the content is rendered, since everything is stored in a very semantic format passing on that responsibility to the developer implementing the website.
2. Managing widgets
Another common scenario the grid layout editor supports are managing and inserting widgets on a page. Using the grid, editors can pick pre-made components, either text, images, embedded elements or macros and insert them in a sidebar on the page.
This could replace various setups involving content pickers, repeatable content editors and other kinds of collections of content nodes and macros.
Limitations
With the above usage scenarios in mind, consider the grids limitations. First of all, all content entered into the grid is stored as a single property value on the content node, as a big JSON object. This means that as soon as the values are stored in the database, there is no managed API to drill into the grid content and target specific cell content. A grid layout is not a recommended storage of reusable content - it wasn't designed for this scenario. If you wish to reuse content in multiple pages, it is still recommended that you store these pieces of content as separate content nodes, so they can be stored, cached and queried as usual.
Customisation
Keep all customisation in the /App_Plugins/ folder. This makes it easier to share across multiple projects and ensures that nothing is lost in an update process.
Keep it basic
The grid cannot solve every problem, neither was it meant to. It absolutely shines when configured correctly and designed to solve well-defined editor tasks, like entering content in a pre-defined layout and preconfigured options.
If you put a standard grid editor on every page, expecting editors to do magic, you will be disappointed - and so will your editor.
So keep the use cases basic, spend time to configure and tune the grid in detail, this will truly make your editors love you.
.
Once you've made sure you meet the requirements it is time to install the Umbraco Templates on your system.
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
Content Example
MVC View Example
With Modelsbuilder
Without Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Data Type Definition Example
YYYY-MM-DD
, but you can change this to something else. See
for the supported formats.
Content Example
Content Example
MVC View Example - displays a datetime
Typed
Dynamic (Obsolete)
See Common pitfalls for more information about why the dynamic approach is obsolete.
A single column layout which to the content editor will act like a full page canvas to insert elements on
A multiple column layout with a main content body, and one or more sidebar columns to insert lists or other sidebar widgets on.
You can however configure as many layouts and layout sections as you wish, each section in the layout must be given a width in columns, so editors gets an accurate preview of their layout.
Row configurations
A row in the grid editor contains one or more cells, which divide the row into areas where editors can enter content. So a row is merely a container of areas to insert content into. When you add a new row, you are asked to give it a name, then define cells inside the row by clicking the "+" icon. Each cell has a default width set to 4, but by clicking the inserted cell you can control its width.
It is possible to setup configurable attributes(class, rel, href) and inline styling on rows.
You can add as many cells as you like. If they overflow the total width of the row, they will be arranged after each other horizontally as you'd expect in a grid system.
Each cell can by default contain any type of editor such as textstring editors, imagespicker, embedded media or Umbraco macros. To override this behavior, uncheck the allow all editors option and you can specify which editors will be available for the row.
Server setup
This section describes different ways of setting up servers for use with Umbraco
This section describes different ways of setting up servers for use with Umbraco
Secure Sockets Layer (SSL) and HTTPS
We strongly encourage the use of HTTPS with Umbraco installations especially in production environments. Using HTTPS will greatly enhance the security of your website, see the Security reference for more information.
To ensure a stable and smoothly running Umbraco installation, these permissions need to be set correctly.
Information about hosting a v9 application using IIS.
Information on how to deploy Umbraco in a Load Balanced scenario and other details to consider when setting up Umbraco for load balancing.
Best practices for running Umbraco on Azure Web Apps.
The runtime mode setting optimizes Umbraco for the best development experience or optimal production environment.
Overview of topics to consider when running Umbraco in Docker.
DateTime
Alias: Umbraco.DateTime
Returns: DateTime
Displays a calendar UI for selecting dates which are saved as a DateTime value.
Data Type Definition Example
There are two settings available for manipulating the DateTime property.
One is to set a format. By default the format of the date in the Umbraco backoffice will be YYYY-MM-DD HH:mm:ss, but you can change this to something else. See for the supported formats.
The second setting is "Offset time". When enabling this setting the displayed time will be offset with the servers timezone. This can be useful in cases where an editor is in a different timezone than the hosted server.
Content Example
MVC View Example - displays a datetime
With Modelsbuilder
Without Modelsbuilder
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 example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Data
This section focuses on how to create data using the Umbraco backoffice
This section focuses on how to create data using the Umbraco backoffice.
There are three kinds of content in Umbraco:
Your normal website content that exists in the content section.
Media content such as images, videos and PDFs that are stored in the Media section.
Finally Members, 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 Documents 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 which 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.
Grid Layout (Legacy)
We highly recommend that you use the Block Grid instead.
The Grid Layout has been marked as obsolete and development on the property editor has been discontinued. It will be removed as a core property editor with the release of Umbraco 14, planned for Summer 2024.
Returns: JSON
Gives editors a grid layout editor which allows them to insert different types of content in a predefined layout.
The basic concept of Grid Layouts.
How to setup your Grid Layout data type.
Add settings and styles.
Explanation of default Grid editors and how to customise them.
Build your own Grid editor from the ground up.
Render content created with Grid Layouts in your templates.
General guidelines when contemplating Grid Layout implementation.
Example how to add values programmatically.
Rendering Grid In a Template
Using @Html.GetGridHtml
To render a property based on the grid inside a template you should use the HtmlHelper extension:
@Html.GetGridHtml(Model, "propertyAlias")
This will render the grid item with the alias "propertyAlias" from the current page models' content.
This will by default use the view /views/partials/grid/bootstrap3.cshtml you can also use other provided grid template rendering files - for example, the built-in bootstrap2.cshtml view by overloading this helper:
You can create your own custom grid rendering file for your favorite or custom grid framework implementation. Tip: copy one of the existing files as a starting point. By convention, if you create your mycustomrenderer.cshtml file in /views/partials/grid you can render the grid property like so:
Possible paths where you can add the custom Grid layout views:
What Are Grid Layouts?
To understand how the grid layout editor works, we must first understand the structure of the grid layouts.
Grid layouts consists of two main areas that need to be configured, grid layout area and grid rows.
Grid Layout
The layout area is where the overall page layout is defined. Layout areas are divided in to layout sections e.g. a sidebar section and content section. The size of the layout sections is defined in columns. For a full-width content area use max number of columns (12 for Bootstrap 3). Each layout section contains one or more rows.
Grid Rows
Grid rows is where the actual content goes. Each row is divided into cells that contain the property editors. The size of the cells is defined in columns. Unlike the layouts sections it is possible to add more cells than the max number of columns - they will stack as they should in a grid system.
Textarea
Alias: Umbraco.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.
Eye Dropper Color Picker
Alias: Umbraco.ColorPicker.EyeDropper
Returns: string
The Eye Dropper Color picker allows you to choose a color from the full color spectrum using HEX and RGBA.
Data Type Definition Example
Member Picker
Alias: Umbraco.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.
Member Group Picker
Alias: Umbraco.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).
Radiobutton List
Alias: Umbraco.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 Types
Learn about the data types in Umbraco.
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 (textstring, number, true/false,...) or it can be more complex (multi node tree picker, image cropper, Grid Layout).
Rich Text Editor Styles
It is possible to define specific styles and fonts for the Rich Text Editor (RTE). Once you have defined the styles, and enabled them on the RTE Data Type, the styles can be accessed directly in the Content section.
Creating RTE Styles
The RTE styles are created and managed in the Umbraco backoffice.
Email Address
In this article you can learn how to use the build in email property editor
Alias: Umbraco.EmailAddress
Returns: String
Displays an email address.
Settings
Default Document Types
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 with template
Creating document types with templates allows you to define both the content structure and the visual presentation of a particular type of content item. It ensures a consistent and cohesive look and feel across your website while also enabling structured content management. This approach helps separate content from design, making it easier to manage and update your website's content and appearance independently through templates.
Scheduled Publishing
Each document in Umbraco can be scheduled for publishing and unpublishing on a pre-defined date and time.
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.
Toggle
Returns: Boolean
Toggle is a standard checkbox which saves either 0 or 1, depending on the checkbox being checked or not.
Data Type Definition Example
@Model.MyDecimal
@Model.Value("MyDecimal")
@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Set the value of the property with alias 'myDecimal'.
content.SetValue("myDecimal", 3);
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;
@{
// Set the value of the property with alias 'myDecimal'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MyDecimal).Alias, 3);
}
@(Model.Content.GetPropertyValue<DateTime>("datePicker").ToString("dd MM yyyy"))
@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = new Guid("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Set the value of the property with alias 'datePicker'
content.SetValue("datePicker", DateTime.Now);
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'datePicker'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.DatePicker).Alias, DateTime.Now);
}
Data Type Definition Example
Without a character limit
Textarea Data Type Definition
With a character limit
Textarea Data Type Definition With Limits
Settings
Content Example
Without a character and rows limit
Textarea Content Example
With a character limit and rows limit
Textbox Content Example With Limits
MVC View Example
Without Modelsbuilder
With Modelsbuilder
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Eye Dropper Color Picker Data Type Definition
Content Example
Eye Dropper Color Picker Content
Example with Modelsbuilder
Example without Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Data Type Definition Example
Media Picker Data Type Definition
Content Example
Member Picker Content
MVC View Example
Without Modelsbuilder
With Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Data Type Definition Example
Member Group Picker Type Definition
Content Example
Member Grouep Picker Content
MVC View Example
Without Modelsbuilder
With Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
You can also add multiple groups by creating a comma separated string with the desired member group IDs.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Data Type Definition Example
Radiobutton List Data Type Definition
You can use dictionary items to translate the values of a Radiobutton List property editor in a multilingual setup. For more details, see the Creating a Multilingual Site article.
Content Example
Radiobutton List Content
MVC View Example
Typed
Without Modelsbuilder
With Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
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
To create a new Data Type, go to the Settings section within the backoffice. Thereafter click the menu icon to the right of the Data Types folder and select Create->New Data Type. Name the Data Type - we'll call it Dropdown Cities.
Dropdown List
Property Editor: This is where you pick the Property Editor that our Dropdown Cities Data Type will be referencing. Pick the Dropdown and now you will see the configuration options that are available for a Data Type referencing the Dropdown Property Editor.
Enable multiple choice: By enabling this it will be possible to select multiple options from the dropdown.
Add prevalue: Here you can add prevalues to the Data Type by entering the value you want into the input field and pressing the add button or hitting Enter on your keyboard.
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.
Content Picker References
This gives you an overview of the Types that currently use the Data Type.
Learn more about viewing references or implementing tracking in the Tracking References article.
Find the Stylesheets folder in the Settings section.
Right-click the folder and select Create....
Choose New Rich Text Editor style sheet file.
Give the new stylesheet a name and Save it.
This will generate an empty CSS file in your project.
At this point, you can start adding specific styles, that your editors can then use in the Content section when creating and writing new content.
Add specific RTE styles
The image above is an example of how an RTE style can be configured. When working with these styles, the Preview feature will show you how the style will look when applied.
Every style you add, will automatically be added to the CSS file. The file will be placed in the same location as the rest of your CSS files. It is possible to edit the file directly from the backoffice as well. Access it from the Code tab in the top-right corner.
Edit CSS file directly in the backoffice
Using RTE Styles
In order for your editors to be able to use the styles when working with content, two things needs to be done.
1. Enable "Style select"
The styles will be accessed by the editors using the "Formats" dropdown in the toolbar of the RTE. In order the enable the dropdown, the "Style select" toolbar option needs to be checked.
This can be done by accessing the RTE Data Type directly from the "Info" tab on the Content. You can also find the RTE Data Type in the Settings section of the backoffice and make the changes from there. Learn more about the configuration options in the RTE Config article.
2. Select the styles
You can have as many different styles for your RTEs as you want. You might want to have different styles for different RTE Data Types.
When configuring your RTE Data Types, you can select which stylesheets your content editors should be able to use.
Choose stylesheets on the Data Type
Rich Text Editor Styles
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.
Mandatory Checkbox Example
Content Example
Single email address content example
MVC View Example
Without Modelsbuilder
With Modelsbuilder
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.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
The value sent to an EmailAddress property needs to be a correct email address, For example: [email protected].
It is recommended that you set up validation on this property, in order to verify whether the value added is in the correct format.
Document type
Creating a Document Type (without a template) is about defining the content structure and fields that can be used across different content items. You might use document types without templates for creating consistent, structured content that doesn't require a predefined page layout. For example blog posts or product listings.
Compositions
Compositions provide a way to create reusable sets of properties that can be added to one or more document types. This can help simplify the management and consistency of content types across your website.
When using a mixed setup, you can take advantage of nesting and use compositions by clicking on "Compositions..." option.
If you create 2 compositions that contain some common properties it is only possible to pick one of the compositions in a Document Type. If preferred, those compositions that cannot be used can be marked as hidden by checkmarking the Hide unavailable options.
Element Type
An Element Type is a Document Type without a template containing schema configurations for repeating a set of properties. These are for defining schema in the Block List Editor, Block Grid Editor, or other Element Type based editors.
Element Types cannot be used to create content that resides in the Content tree. When you create an Element type, it automatically sets the Is Element Type flag to True on the Permissions tab.
Element Types are created using the same workflow as regular Document Types but usually contain fewer properties. You can also create Element Types as part of configuring a Block Grid or Block List Data Type.
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 12PM then the item will be published at 12PM in the timezone you are in. This may be 8PM on the server, which is indicated when you select the date and time.
Scheduled publishing
If you are in the same timezone as the server, this message will not appear under the date picker.
In Umbraco versions lower than 7.5, the time you select has to be the time on the server. These older versions of Umbraco do not detect your local timezone.
Permissions
All users with access to the Content section in the Umbraco backoffice are able to schedule content for publish/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, see the docs here
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 (seethese docsfor 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.
The Toggle property has a setting which allows you to set the default value of the checkbox, either checked (true) or unchecked (false).
It is also possible to define a label, that will be displayed next to the checkbox on the content.
Content Example
No Edit Content Example
MVC View Example
Without Modelsbuilder
With Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
True/False Data Type Definition
Install using .NET CLI
We have made custom Umbraco templates that are available for use with dotnet new. The steps below will demonstrate the minimum amount of actions required to get you going and set up an Umbraco project from the command line using .NET templates.
Video Tutorial
Install the template
Install the latest .
Run dotnet new install Umbraco.Templates to install the project templates.
&#xNAN;The solution is packaged up into the NuGet packageand can be installed into the dotnet CLI.
Once that is complete, you can see that Umbraco was added to the list of available projects types by running dotnet new --list:
In some cases the templates may silently fail to install (usually this is an issue with NuGet sources). If this occurs you can try specifying the NuGet source in the command by running dotnet new install Umbraco.Templates --nuget-source "https://api.nuget.org/v3/index.json".
To get help on a project template with dotnet new run the following command:
dotnet new umbraco -h
From that command's output, you will get a better understanding of what are the default template options, as well as those command-line flags specific to Umbraco that you can use (as seen below):
Create an Umbraco project
Create a new empty Umbraco solution:
dotnet new umbraco -n MyCustomUmbracoProject
You will now have a new project with the name MyCustomUmbracoProject, or the name you chose to use. The new project can be opened and run using your favorite IDE or you can continue using the CLI commands.
If you want to create a solution file as well you can run the commands below.
dotnet new slndotnet sln add MyCustomUmbracoProject
Run Umbraco
Navigate to the newly created project folder:
cd MyCustomUmbracoProject
Build and run the new Umbraco .Net Core project:
dotnet builddotnet run
The project is now running on the and has assigned a free available port to run it on. Look in the terminal window after the dotnet run command to see the URLs.
The next step is to run through the Umbraco CMS installation. If you chose to use MS SQL Server/Azure you will need to add your connection string during this setup process to get access to the Umbraco backoffice.
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.
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:
Local IIS With Umbraco
This article describes how to run an Umbraco 9 site on a local IIS server.
This is a quick guide on getting your Umbraco website running locally on IIS.
The guide will assume you already have IIS configured and know your way around it, as well as having a local website you wish to host.
Setting up prerequisites
First, you need to ensure you have "Development time IIS support installed". To check this, go to the Visual Studio installer, click modify and check on the right side under "ASP.NET and web development":
Once that is installed you should set up a new IIS site - and make sure to add the hostname to your hosts file as well. Here is my setup for an example:
For the path you want to point it at the root of your site - where the .csproj file is.
Add permissions to NuGet cache folder
You might need to change permissions for the NuGet cache folder - C:\users\<username>\.nuget\packages. The user or group (IIS_IUSRS) that the IIS site is running on requires Read permissions on this folder because this is where some of the files for Umbraco and Umbraco packages are being served from during development. If the IIS user or group does not have permission to read from the NuGet cache folder, you could run into a DirectoryNotFoundException while running the site.
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:
Restart IIS (net stop was /y followed by net start w3svc)
Create a site in IIS and ensure that the .NET Common Language Runtime (CLR) version is set to No Managed Code for the Application Pool.
Publish website for manual deployment to IIS
You can use the dotnet CLI to compile and collate all files required for hosting
Alternatively, you can use the File Transfer Protocol (FTP) publishing in Visual Studio to compile and collate all the required files for the application to run.
In Visual Studio, select the Umbraco web project in the Solution Explorer and choose the Publish... command.
Deploy a website for automated deployment with Azure DevOps to IIS
You can use the to deploy your website to your Web Server. This task is a wrapper for MSDeploy.exe and can be configured as preferred.
Environment Variables in ApplicationHost.config
In the Management section you find the Configuration Editor:
One section is of particular interest:
In the first, left hand dropdown list (Section:) choose: system.webServer/aspNetCore section.
In the second, right hand dropdown list (From:) choose: ApplicationHost.config <location path='[YOUR-SITENAME]'>. This ensures your settings will be stored in a machine specific file. The configuration files might end in a public repository and should not contain sensitive data like Connection Strings or Simple Mail Transfer Protocol (SMTP) configuration with username and password. Additionally, by default the configuration file will be overwritten during each publish processes.
Find the line named environmentVariables and open the dialog to add environment variables. These work similar to the launchSettings. You can define ASPNETCORE_ENVIRONMENT and create an appSettings.[ASPNETCORE_ENVIRONMENT].json file. Or even better create environment variables for sensitive settings like passwords. There are some differences to launchSettings.json configuration:
Variable names need to change the object structure form JSON by combining the segments with double underscore __ e.g. ConnectionStrings__umbracoDbDSN
Escaped backslashes \\ e.g. serverName\\databaseInstanceName are replaced by single backslash \ e.g. DATABASESERVER123\SQL2017
IIS Hosting models
IIS can host .NET applications using 2 different hosting models
In-process hosting runs a .NET app in the same process as its IIS worker process
- to enable this model you need to edit your .csproj file and add:
Out-of-process .NET apps run separately from the IIS worker process. The module controls the management of the Kestrel server and requests are proxied between them.
Add Values Programmatically
Configuration
For this example, the default grid configuration has been used.
Grid configuration
Set value
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 Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Install using Visual Studio
A guide to install Umbraco CMS using Visual Studio.
In Visual Studio 2022, the .NET CLI templates are enabled to appear, by default. For information on how to enable .NET CLI templates in Visual Studio 2019, see the article.
Check the to ensure you have everything you need to start your Umbraco project.
Quick Start
This is an abbreviated version of the installation steps. Jump to the section for a more thorough guide.
Open Visual Studio.
Go to File > New > Project, search for Umbraco.
Video Tutorial
Create a new Umbraco project
To install Umbraco we first need to install Umbraco's dotnet new templates.
For more information check the first 2 steps of .
Create the Visual Studio project
Go to File > New > Project and search for Umbraco in the Search for templates field.
Once you select Umbraco Project (Umbraco HQ) navigate to the next step by clicking Next.
Configure project
In this step, you will be able to give your project a name specific to the project you are creating.
Refrain from changing the Solution name, as this will cause a namespace conflict with the CMS itself.
Additional information
In the next step, you are able to specify some additional parameters like the Target framework. The rest are optional.
You can then click the Create button and your Umbraco Project will be ready for you.
Running the site
You can now run the site through Visual Studio using F5 or the Debug button.
Follow the installation wizard and after a few steps, you will get a message saying the installation was a success.
Next steps
You are now ready to start building your Umbraco project. Have a look below for different resources on the next steps.
Sections
In this article you can learn more about the various sections you can find within the Umbraco Backoffice.
A section in Umbraco is where you perform specific tasks related to a particular area of Umbraco. For example Content, Settings and Users are all sections. You can navigate between the different sections by clicking the corresponding icon in the section menu which is positioned at the top of the Backoffice.
The Section menu is the horizontal menu located at the top of the Umbraco Backoffice.
There are eight default sections that come with Umbraco:
Content
The Content section contains the content of the website. Content is displayed as nodes in the content tree. Nodes can also show content state:
Grayed out nodes have not been published
Nodes have unpublished versions (but are currently published)
Nodes are protected from the public (can only be accessed by a logged in Member)
In order to create content, you must define it using Document Types.
Media
The Media section contains the media for the website. By default, you can create folders and upload media files (images and PDFs). You can customize the existing media types or define your own from the Settings section.
Settings
The Settings section is where you can work with the website layout files, languages, and define media and content types. In this section, you can also find the Log Viewer to browse through your log files.
The Settings tree consists of:
Document Types
Media Types
Member Types
The Settings section of the Umbraco backoffice has its own set of default dashboards. For more information, see the article.
Packages
In this section, you can browse and install packages into your Umbraco solution. You can also get an overview of all the installed packages as well as uninstall packages you no longer need.
Users
Manage, create, and customize Backoffice users and user groups.
Members
Manage, create, and customize members and member groups.
Forms
You can install Umbraco Forms directly from the Backoffice by clicking the install button. Once installed, this section is where you create and manage your forms.
Translation
This is the section where you create and manage your dictionary items.
Help sections
In the top-right corner, you'll find a search tool, which is also accessible by hitting CTRL + Space on your keyboard.
Next to the search tool, there is a help section. In the help section you can find Backoffice tours and links to Umbraco resources such as documentation and UmbracoTV.
There is also a small 'user section' with shortcuts to edit the currently logged in user, and view their most recent activities.
Custom Sections
Along with the default sections that come with Umbraco, you can create your own .
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 .
Document Type Localization
Here you will learn how to apply localization for Document Types in Umbraco.
The Umbraco backoffice is fully localized to match the user's configured language. When defining Document Types, you can apply localization to:
Document Type names and descriptions.
Property names and descriptions.
Custom property validation messages.
Tab and group names.
Setting up localization for Document Types is a two-step process:
Create the localizations in .
Apply the localizations to the Document Types.
Everything in this article also applies to defining .
Creating localizations
User defined language files are created in /config/lang and must be named {language}.user.xml. For example: en-us.user.xml.
There are no specific requirements as to how localizations should be structured for use in Document Types. The following localizations have been used for the samples in this article:
Umbraco must be restarted to pick up on changes to language files.
Applying localizations
The localizations are applied by using the syntax #{area alias}_{key alias}.
Create a Document Type with template called #contentTypes_article with alias: articlePage.
Under the newly created Document Type follow these steps:
Name the description to #contentTypes_article-desc.
Create a new tab called #tabs_content.
Add a new group called #groups_titles
Add a property called #properties_subTitle with aliassubTitle.
Set description to #properties_subTitle-desc.
When creating and editing the content, you will see that the backoffice now uses the configured localizations.
Create a new "Article" content:
When trying to save the content without adding the mandatory content, you will see a warning as expected:
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 is displayed next to the Settings tree and consists of a view that can be customized. The Welcome dashboard consists of links to different resources that can be used when developing your Umbraco website.
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 (NuCache).
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.
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:
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.
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.
Textbox
How to use the TextBox property editors in Umbraco CMS.
Alias: Umbraco.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 Modelsbuilder
With Modelsbuilder
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 example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Numeric
Alias: Umbraco.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 Modelsbuilder)
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 Modelsbuilder)
You can also render the output by casting it to a string, which means you will not be able to do mathematical operations
With Modelsbuilder
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 example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Label
Alias: Umbraco.Label
Returns: String
Label is a non-editable control and can only be used to display a pre-set value.
Data Type Definition Example
Value type
If you want to set a value other than a String, you can define the data using one of the other available Data Types. These include Decimal, Date/time, Time, Integer, and Big integer.
There is also a Value Type: Long string if you need to set a long string value for your Label.
Content Example
MVC View Example
Without ModelsBuilder
With ModelsBuilder
Add values programmatically
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 example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
File And Folder Permissions
Information on file and folder permissions required for Umbraco sites
To ensure a stable and smoothly running Umbraco installation, these permissions need to be set correctly. These permissions should be set up before or during the installation of Umbraco.
The main account that requires 'modify' file permissions to be set on the folders below, is the account used start Umbraco. If Umbraco is hosted in IIS this will be the Application Pool Identity for the IIS website. Usually IIS APPPOOL\appPoolName or a specific local account or in some circumstances Network Service. If in doubt, ask your server admin / hosting company. Additionally, the Internet User (IUSR) account and IIS_IUSRS account only require 'read only' access to the site's folders.
Generally, when developing locally with Visual Studio or Rider, permissions do not need to be strictly applied.
If you have any specific static files/media items/etc, you should add the appropriate permissions accordingly.
The permissions documentation should allow you to run a plain Umbraco install successfully.
File / folder
Permission
Comment
File Upload
Alias: Umbraco.UploadField
Returns: string
Adds an upload field, which allows documents or images to be uploaded to Umbraco.
You can define which file types should be accepted through the upload field.
Backoffice
Learn more about the Umbraco backoffice which is the admin side of your Umbraco website.
In this article you can learn more about the common terms and concepts that are used throughout the Umbraco backoffice.
When you go to the backoffice for the first time, you're presented with the login screen.
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 that must be upgraded from Umbraco 8. You can then use the steps to upgrade from Umbraco 10 to the latest version.
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
Multi Url Picker
Alias: Umbraco.MultiUrlPicker
Returns: IEnumerable<Link> or Link
Multi Url Picker allows an editor to pick and sort multiple urls. This property editor returns a single item if the "Maximum number of items" Data Type setting is set to 1 or a collection if it is 0. These can either be internal, external or media.
Standalone File System
No file replication is configured, deployment handles updating files on the different servers.
If the file system on your servers isn't performing any file replication then no Umbraco configuration file changes are necessary. However Media will need to be configured to use a shared location such as Blob storage or S3.
Depending on the configuration and performance of the environment's local storage you might need to consider and the .
List View
Alias: Umbraco.Listview
Returns: IEnumerable<IPublishedContent>
List View display a list of categories when it is enabled on a Document Type that has children.
Slider
Alias: Umbraco.Slider
Returns: decimal or Umbraco.Core.Models.Range<decimal>
Pretty much like the name indicates this Data type enables editors to choose a value with a range using a slider.
There are two flavors of the slider. One with a single value picker. One with a minimum and maximum value.
Repeatable Textstrings
Alias: Umbraco.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.
Color Picker
Alias: Umbraco.ColorPicker
Returns: String (Hexadecimal)
Returns: Umbraco.Cms.Core.PropertyEditors.ValueConverters.ColorPickerValueConverter.PickedColor (When using labels)
The Color picker allows you to set some predetermined colors that the editor can choose between.
It's possible to add a label to use with the color.
Dropdown
Alias: Umbraco.DropDown.Flexible
Returns: String or IEnumerable<string>
Displays a list of preset values. Either a single value or multiple values (formatted as a collection of strings) can be returned.
Build Your Own Editor
The samples in this section have not been verified against the latest version of Umbraco.
A new Property Editor called the Block based Grid editor will soon be available as a substitute for the existing Grid Layout editor. For more information, see the in the Umbraco Roadmap.
Create a file in /App_Plugins/yourpackage/editor.html and add the following to the editor.html file:
Install using Visual Studio Code
Follow these steps to set up an Umbraco project with Visual Studio Code. The benefit of using Visual Studio Code is that it is super quick to get up and running.
Installing and setting up Visual Studio Code
Go to
Content Picker
Alias: Umbraco.ContentPicker
Returns: IPublishedContent
The content picker opens a panel to pick a specific page from the content structure. The value saved is the selected nodes
Default Data/Media Types
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.
After upgrading, the default media types are not created automatically. If you create them manually, make sure to:
Set the permission for each of the media types to
Checkbox List
Alias: Umbraco.CheckBoxList
Returns: IEnumerable<string>
Displays a list of preset values as a list of checkbox controls. The text saved is an IEnumerable collection of the text values.
Unlike other property editors, the Prevalue IDs are not directly accessible in Razor.
@{
if (Model.HasValue("description")){
<p>@(Model.Value<string>("description"))</p>
}
}
@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 'description'
content.SetValue("description", "This is some text for the text area!");
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'description'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Description).Alias, "This is some text for the text area!");
}
@{
var color = Model.Color?.ToString();
if (color != null)
{
<body style="background-color: @color"></body>
}
}
@{
var color = Model.Value<string>("Color");
if (color != null)
{
<body style="background-color: @color"></body>
}
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Set the value of the property with alias 'color'.
content.SetValue("color", "#6fa8dc");
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'color'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Color).Alias, "#6fa8dc");
// Set the value of the property with alias 'theme'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Theme).Alias, "rgba(111, 168, 220, 0.7)");
}
@{
if (Model.HasValue("author"))
{
var member = Model.Value<IPublishedContent>("author");
@member.Name
}
}
@{
if (Model.Author != null)
{
var member = Model.Author;
@member.Name
}
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@using Umbraco.Cms.Core;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
var udi = Udi.Create(Constants.UdiEntityType.Member, authorId);
// Set the value of the property with alias 'author'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Author).Alias, udi);
}
@if (Model.HasValue("memberGroup"))
{
var memberGroup = Model.Value<string>("memberGroup");
<p>@memberGroup</p>
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = 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);
}
@{
// Set the value of the property with alias 'memberGroup'.
content.SetValue("memberGroup", "1067","1068");
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@using Umbraco.Cms.Core;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'memberGroup'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MemberGroup).Alias, 1067);
}
@if (Model.HasValue("colorTheme"))
{
var value = Model.Value("colorTheme");
<p>@value</p>
}
@if (Model.ColorTheme != null)
{
var value = Model.ColorTheme;
<p>@value</p>
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'colorTheme'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.ColorTheme).Alias, "water");
}
@if (Model.HasValue("email"))
{
var emailAddress = Model.Value<string>("email");
<p>@emailAddress</p>
}
@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);
}
@{
if (!Model.Value<bool>("myCheckBox"))
{
<p>The Checkbox is not checked!</p>
}
}
@{
if (!Model.MyCheckbox)
{
<p>The Checkbox is not checked!</p>
}
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'myCheckBox'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor,x => x.MyCheckBox).Alias, true);
}
Database Cache - Rebuilds the database cache that is the content of the cmsContentNu table. Use it when reloading the Memory Cache is not enough and you think that the database cache has not been properly generated.
Internals - Lets you trigger a NuCache snapshots collection.
Details on how Models Builder is configured, that is: InMemoryAuto, Nothing, SourceCodeAuto, and SourceCodeManual.
Provides a button to generate models (if the models mode is SourceCodeManual mode only).
Reports the last error (if any) that would have prevented models from being properly generated.
For more information about Models Builder, see the Models Builder article.
For more information about MiniProfiler, see the MiniProfiler section in the Debugging article.
Number of: Root nodes, Content nodes, Macros, Media, Document Types, Templates, Languages, Domains, User Group, Users, Members, and Property Editors in use.
System information: Webserver, server OS, server framework, server OS language, and database provider.
Configuration settings: Modelsbuilder mode, if custom Umbraco path exists, ASP environment, and if you are in debug mode.
Basic contains:
Anonymized site ID, Umbraco version, and packages installed.
Minimal contains:
Anonymized site ID only
You can see the specific data being sent on each of the levels directly in the Telemetry Data Dashboard.
Additionally, Telemetry Data also sends anonymized, analytical data on package usage in Umbraco. Having solid data on package usage is important for both package developers and the Umbraco ecosystem. For more information about Package Telemetry, see the Package Telemetry section in the Umbraco 9.2 Release Blog Post.
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.
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 Directory Factory.
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 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.
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 Azure Web Apps 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 advanced techniques.
If you wish to use something entirely different you can give the editor a separate render value which follow the same conventions.
Grid editor controller
If you are building something slightly more complex then a text area, you will need to add a controller to the grid editor view. So first add a ng-controller attribute to the grid editor html - this works like building a property editor:
To wire up a controller to this view, create the file /App_Plugins/yourpackage/editor.controller.js and add a standard angular controller declaration:
Finally, we need to tell Umbraco to load this JavaScript controller when the Umbraco application boots. This is like building a property editor. Add your JavaScript (and css dependencies) in the package.manifest file in the /yourpackage folder, and configure it to load your controller file.
So to summarize, to create a custom grid editor from scratch, you will need to:
Create a grid editor view .html file
Create a grid render .cshtml file
Create a grid editor controller .js file
Create a package.manifest to register the editor and make Umbraco load needed files
This process tries to be as close to building property editors as currently possible.
Rendering grid editor content
Next add this c# to the .cshtml file:
When rendering the .cshtml file will receive a dynamic model with the raw data of the editor:
So you can now use these value to build your razor output like so:
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>();
}
@using Newtonsoft.Json
@using Umbraco.Cms.Core.Services;
@using Umbraco.Cms.Core.Models;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Create a variable for the grid value with the 1 one column layout and add a headline
var gridValue = new GridValue
{
Name = "1 column layout",
Sections = new List<GridValue.GridSection>
{
new GridValue.GridSection
{
Rows = new List<GridValue.GridRow>
{
new GridValue.GridRow
{
Name = "Headline",
Id = new Guid(),
Areas = new List<GridValue.GridArea>
{
new GridValue.GridArea
{
Controls = new List<GridValue.GridControl>
{
new GridValue.GridControl
{
Editor = new GridValue.GridEditor
{
Alias = "headline"
},
Value = "Our Umbraco"
}
}
}
}
}
}
}
}
};
// Serialize the grid value
var serializedGridValue = JsonConvert.SerializeObject(gridValue);
// Set the value of the property with alias 'body'
content.SetValue("body", serializedGridValue);
// Save the change
contentService.Save(content);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'body'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Body).Alias, serializedGridValue);
}
en-us.user.xml
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<language>
<area alias="contentTypes">
<key alias="article">Article page</key>
<key alias="article-desc">A textual, article-like page on the site. Use this as the main type of content.</key>
<key alias="landing">Landing page</key>
<key alias="landing-desc">An inviting, very graphical page. Use this as an entry point for a campaign, and supplement with Articles.</key>
</area>
<area alias="tabs">
<key alias="content">Page content</key>
<key alias="seo">SEO configuration</key>
</area>
<area alias="groups">
<key alias="titles">Page titles</key>
</area>
<area alias="properties">
<key alias="title">Main title</key>
<key alias="title-desc">This is the main title of the page.</key>
<key alias="title-message">The main title is required for this page.</key>
<key alias="subTitle">Sub title</key>
<key alias="subTitle-desc">This is the sub title of the page.</key>
</area>
</language>
@{
// 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 Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = new Guid("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Set the value of the property with alias 'pageTitle'
content.SetValue("pageTitle", "Umbraco Demo");
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'pageTitle'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.PageTitle).Alias, "Umbraco Demo");
}
@{
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>
}
@{
int students = Model.Students;
int teachers = Model.Teachers;
int totalTravellers = students + teachers;
<p>@totalTravellers</p>
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'students'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Students).Alias, 20);
}
@{
if (Model.HasValue("pageLabel")){
<p>@(Model.Value("pageLabel"))</p>
}
}
@{
if (!string.IsNullOrEmpty(Model.PageLabel))
{
<p>@Model.PageLabel</p>
}
}
@{
@inject IContentService Services;
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Set the value of the property with alias 'pageLabel'.
content.SetValue("pageLabel", "A pre-set string value");
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@{
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor
// Set the value of the property with alias 'pageLabel'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MyLabel).Alias, "A Preset string");
}
The samples in this section have not been verified against the latest version of Umbraco.
Instead, we recommend using the Media Picker for uploading files to your Umbraco website.
See the example below to see how a value can be added or changed programmatically. To update a value of this property editor you need the Content Service and the Media Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
A section in Umbraco is where you do specific tasks related to that section. For example Content, Settings and Users. You can navigate between the different sections of the backoffice by clicking the corresponding icon in the section menu.
The Section menu is the horizontal menu located on the top of the backoffice.
A node is an item in a tree. Media section items appear as nodes in the Media tree, while pages and content are displayed in the Content tree, and so on.
A dashboard is the main view you are presented with when entering a section within the backoffice. It can be used to show valuable information to the users of the system.
An editor is what you use to edit different items within the backoffice. There are editors specific to editing stylesheets, there are editors for editing Macros, and so forth.
Content is what you find in the Content section. Each item in the tree is called a content node. Each content node in the content tree consists of different fields, and each of them is defined by a Document Type.
Document Types define the types of content nodes that backoffice users can create in the content tree. Each Document Type contains different properties. Each property has a specific Data Type for example text or number.
Properties
Every Document Type has properties. These are the fields that the content editor is allowed to edit for the content node.
Each Document Type property has a Data Type that defines the type of input of that property. Data Types reference a Property Editor and are configured in the Umbraco backoffice in the Settings section. A Data Type can be something basic (text string, number, true/false) or more complex (multi-node tree picker, image cropper, etc).
A property editor is a view used by Data Types to insert content into Umbraco. An example of a property editor is the Textarea. It's possible to have many Textarea Data Types with different settings that all use the Textarea property editor.
A package is the Umbraco term for an add-on or plugin used to extend the core functionalities in Umbraco. The packages can be found on the Umbraco Marketplace, and the can also be browsed directly in the backoffice of the Umbraco CMS.
A macro is a reusable piece of functionality that you can reuse throughout your site. Macros can be configured with parameters and used on content nodes that have a Rich Text Editor, a Grid editor, or a Macro Picker property. You can define what macros are available for your editors to use. When an editor inserts a macro it will prompt them to fill out any of the defined parameters for the macro.
A user is someone who has access to the Umbraco backoffice and is not to be confused with Members. When Umbraco has been installed a user will automatically be generated with the login (email) and password entered during installation. Users can be created, edited, and managed in the User section.
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.
Create a backup of the database from your Umbraco 8 project (after you have upgraded to the latest version of v8). For this, you can use the database backup guide.
Import the database backup into SQL Server Management Studio.
Update the connection string in the new projects appsettings.json file so that it connects to the Umbraco 8 database:
You can also add the connection details if you spin up a clean installation.
Run the new project and login to authorize the upgrade.
Select "Upgrade" when the upgrade wizard appears.
Once the upgrade has been completed, it's recommended to login to the backoffice to verify if your project is upgraded to new version.
This is only content migration and the database will be migrated.
You need to manually update the view files and custom code implementation. For more information, see Step 3 of this guide.
Step 2: File Migration
The following files/folders need to be copied from the Umbraco 8 project into the new project:
~/Views - Do not overwrite the default Macro and Partial View Macro files unless changes have been made to these.
~/Media - Media folder from v8 needs to be copied over into the wwwroot - media folder
Any files/folders related to Stylesheets and JavaScript.
Migrate custom configuration from the Umbraco 8 configuration files (.config) into the appsettings.json file on the new project.
As of Umbraco version 9, the configuration no longer lives in the Web.Config file and has been replaced by the appsettings.json file. Learn more about this in the article.
, if relevant.
As of Umbraco Forms version 9, it is only possible to store Forms data in the database. If Umbraco Forms was used on the Umbraco 8 project, the files need to be migrated to the database.
Run the new project.
It will give you an error screen on the frontend as none of the Template files have been updated. Follow Step 3 to resolve the errors.
Step 3: Custom Code in the latest version
The latest version of Umbraco is different from Umbraco 8 in many ways. With all the files and data migrated it is now time to rewrite and re-implement all custom code and templates.
Examples of changes
One of the changes is how published content is rendered through Template files. Due to this, it will be necessary to update all the Template files (.cshtml) to reflect these changes.
Read more about these changes in the IPublishedContent section of the Umbraco CMS documentation.
Template files need to inherit from Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ContentModels.HomePage> instead of Umbraco.Web.Mvc.UmbracoViewPage<ContentModels.HomePage>
Template files need to use ContentModels = Umbraco.Cms.Web.Common.PublishedModels instead of ContentModels = Umbraco.Web.PublishedModels
For more information on the correct namespaces or custom code, you can find the references in the API Documentation article.
Depending on the extent of the project and the amount of custom code and implementations, this step is going to require a lot of work.
Once the new project runs without errors on a local setup it is time to deploy the website to production.
This concludes this tutorial. Find related information and further reading in the section below.
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 Requirements 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 InstallMissingDatabase 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 Microsoft Documentation.
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.
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
Data Type Definition Example
Related Links Data Type Definition
Content Example
Media Picker Content
MVC View Example - value converters enabled
Typed
If Max number of items is configured to 1
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Enable list view
If enabled, editors will be able to see multiple children from a list on a content node that has children. When not enabled, no list will be shown and all children will be shown in the Content Tree.
Enable List view example
Settings
List view settings example
List view settings example 2
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 list. If you set it to 5, then only 5 content items will be shown in the list.
Order By
Will sort your list 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 list by adding more datatypes to the columns in the "Columns Displayed" section.
Order Direction
You can select order of the content nodes displayed, "Acsending" or "Descending". The order is affected by the "Order By" selection.
Columns Displayed
It is possible to add more columns to the list, via adding the properties through the dropdown. These properties are based on the Data Types which are used by the Document Type. It will show up in the dropdown by its alias and not the name on the property.
List view property example
List view property example
Once you have selected a column that you want to display, the next thing you want to do is define what its name should be and what kind of value it should display. You can also move the headers around, re-ordering how the headers 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
The list view 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.
A minimum of one layout needs to be enabled for the list view to work.
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.
Bulk Action Permissions
Select what kind of action is available on the list view.
Allow bulk publish - content only
Allow bulk unpublish - content only
Allow bulk copy - content only
Allow bulk move
Allow bulk delete
Content app icon
Changes the icon in the backoffice of the listview. By default it will look like the image below.
List icon example
Content app name
You can change the name of the listview itself. Default if empty: 'Child Items'.
Show Content App First
Enable this to show the content app by default instead of the list view
Content Example
Generic field value
This example uses a generic field on a child item and displays it in the list.
The {{ value }} will take the value of the Email property and display it in the list, as shown on the image below.
List view content example email
Member name
First, a Member Picker property needs to be present on the content item. In this example, the child item has gotten a Member Picker Data Type with the alias of isAuthor.
List view member picker
Now that the child item has a member 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 listview setting.
List view member picker
This will take the value picked up by the member picker.
And display it in the listview. Shown in the example below:
Other examples
List view other examples
List view other examples
List view example
Data Type Definition Example
Slider Data Type Definition
Content Example
MVC View Example
Without Modelsbuilder
With Modelsbuilder
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.
With a range off
With a range on
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Data Type Definition Example
Repeatable textstrings Data Type Definition
Content Example
Repeatable textstrings Content
MVC View Example
Without Modelsbuilder
With Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
To add multiple values to the repeatable text strings property editor you have to put each value on a new line. This can be achieved using either \r\n\ or Environment.NewLine.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Data Type Definition Example
Color Picker Data Type Definition
Content Example
Color Picker Content
Example with Modelsbuilder
Example without Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Settings
Enable multiple choice
If enabled, editors will be able to select multiple values from the dropdown otherwise only a single value can be selected.
Prevalues
Prevalues are the options which are shown in the dropdown list. You can add, edit, or remove values here.
You can use dictionary items to translate the values of a Dropdown property editor in a multilingual setup. For more details, see the Creating a Multilingual Site article.
Data Type Definition Example
Dropdown Data Type Definition
Content Example
Single Value
Single dropdown content example
Multiple Values
Multiple dropdown content example
MVC View Example
Single item - without Modelsbuilder
Multiple items - without Modelsbuilder
Single item - with Modelsbuilder
Multiple items - with Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
and download Visual Studio Code for free.
Once installed, launch Visual Studio Code.
Click the extensions menu at the bottom on the left side. Then search for C# and install it.
Configure Visual Studio Code to run the Umbraco project
Open your project folder in Visual Studio Code, your project will look something like this:
Fresh Umbraco installation
Now we need to tell Visual Studio 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:
Configure task option
Select "Create task.json from template"
Create task from template
Now select ".NET Core" as your template.
Create .NET Core Template
Visual Studio Code creates a folder called .vscode that contains a file called tasks.json. The tasks.json file tells Visual Studio Code how to build your project.
Now that we've told Visual Studio Code how to build your project, we need to tell it how to launch it. Visual Studio 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.
Creating launch.json file
This will prompt a menu to appear, select .NET 5+ and .NET Core:
Prompt Menu
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.
Green Play button options
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 Visual Studio 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 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.
Web Installer - Lets Get Started
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/.
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Ensure that the Folder media type allows the new media types as children.
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)
MediaArticle
UmbracoMediaAudio
The UmbracoMediaAudio media type has the following properties:
umbracoFile Upload Audio
umbracoExtension Label (string)
umbracoBytes Label (bigint)
MediaAudio
UmbracoMediaVectorGraphics
The UmbracoMediaVectorGraphics media type has the following properties:
umbracoFile - Upload Vector Graphics
umbracoExtension Label (string)
umbracoBytes Label (bigint)
MediaVectorGraphics
UmbracoMediaVideo
The UmbracoMediaVideo media type has the following properties:
umbracoFile - Upload Video
umbracoExtension - Label (string)
umbracoBytes - Label (bigint)
MediaVideo
You can also create localization files for Media Types. You can read more about this in the Document Type Localization article.
Data Type Definition Example
True/Checkbox List Definition
You can use dictionary items to translate the values of a Checkbox List property editor in a multilingual setup. For more details, see the Creating a Multilingual Site article.
Content Example
Checkbox List Example
MVC View Example
Without Modelsbuilder
With Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
This article provides details on how to upgrade to the next minor version when using Umbraco 7.
Sometimes there are exceptions to these guidelines, which are listed in the version-specific guide.
Note
It is necessary to run the upgrade installer on each environment of your Umbraco site. If you want to update your staging and live site then you need to repeat the steps below and make sure that you click through the install screens to complete the upgrade.
Contents
In this article you will find instructions for 2 different ways of upgrading:
Upgrade using NuGet
Open up the Package Console and type: Update-Package UmbracoCms
Choose "No to All" by pressing the "L" when prompted.
Alternatively, you can use the Visual Studio NuGet Package Manager to upgrade:
Open the NuGet Package Manager and select the Updates pane to get a list of available updates.
Choose the package called UmbracoCms and select update.
The upgrade will run through all the files and make sure you have the latest changes while leaving the files you have updated.
Upgrades to versions lower than 7.2.0
If you're not upgrading to 7.2.0 or higher then you should follow these extra instructions. If you are upgrading to 7.2.0+ then you can skip this and go to .
You will be asked to overwrite your web.config file and the files in /config, make sure to answer No to those questions.
For some inexplicable reason, the installation will fail if you click "No to All" (in the GUI) or answer "L" (in the package manager console) to the question: "File 'Web.config' already exists in project 'MySite'. Do you want to overwrite it?" So make sure to only answer "No" (in the GUI) or "N" (in the package manager console).
We will overwrite the web.config file. We'll back it up so don't worry. You can find the backup in App_Data\NuGetBackup\20140320-165450\. The 20140320-165450 bit is the date and time when the backup occurred, which varies. You can then merge your config files and make sure they're up to date.
Upgrade manually from a zip file
Download the .zip file for the new version you are upgrading to from
Copy the following folders from inside the .zip file over the existing folders in your site:
/bin
/Umbraco
/Umbraco_Client
There are hosting providers (we know of one: RackSpace Cloud) that require proper casing of file and folder names. Generally, on Windows, this is not a problem. Is your hosting provider forcing proper casing? You'll then need to verify that folders and files are named in the same casing as the version you're upgrading to.
Merge configuration files
You can expect some changes to the following configuration files:
Any file in the /Config folder
The /Global.asax file
The web.config
Use a tool like to check changes between all of the config files. Depending on when you last did this there may have been updates to a few of them.
There's also the possibility that files in the /Config folder are new or have been removed(we note this in the release notes). WinMerge (and other diff tools) is able to compare folders as well so you can spot these differences.
Up until version 6.0.0 it was necessary to change the version number in ClientDependency.config. This was to clear the cached HTML/CSS/JS files in the backoffice. Change the current version number to one that's higher than that. Make sure not to skip this step as you might get strange behavior in the backoffice otherwise.
Merge UI.xml and language
Some packages (like Contour and Umbraco Forms) add dialogs to the UI.xml. Make sure to merge those changes back in from your backup during the upgrade so that the packages continue to work. This file can be found in: /Umbraco/Config/Create/UI.xml.
Packages like Contour, Umbraco Forms, and Courier also make changes to the language files located in: /Umbraco/Config/Lang/*.xml (typically en.xml).
Finalize
After copying the files and making the config changes, you can open your site. You should see the installer which will guide you through the upgrade.
The installer will do two things:
Update the version number in the web.config
Upgrade your database in case there are any changes
We are aware that, currently, the installer is asking you for the database details of a blank database while upgrading. In the near future this will be pre-filled with your existing details and the wording will be updated. So no need to be scared. Enter the details of your existing database and Umbraco will upgrade it to the latest version when necessary.
Post installation
One important recommendation is to always remove the install folder immediately after upgrading Umbraco and never to upload it to a live server.
Potential issues and gotchas
Browser cache
Google Chrome has notoriously aggressive caching. If something doesn't seem to work well in the backoffice, make sure to clear cache and cookies thoroughly (for other browsers as well). Normally the browser cache problem is automatically handled in an Umbraco upgrade by modifying the config/ClientDependency.config version number. If you wish to re-force this update you can increment this version number. This will ensure that any server-side cache of JavaScript and stylesheets gets cleared as well.
One way to nudge the cache in Chrome is to open the developer tools (F12) and go to the settings (the cog icon). There will be a checkbox that says "Disable cache (while DevTools is open)". Once this checkbox is on you can refresh the page and the cache should be invalidated. To force it even more, the "reload" button next to your address bar now has extra options when you right-click it. It should have "Normal reload", "Hard reload" and "Empty cache and hard reload" now. The last option is the most thorough and you might want to try that.
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.
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
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.
Blocks in Rich Text Editor
It is possible to insert Blocks into the markup of the Rich Text Editor (RTE). Once you've defined the Block Type as part of the RTE Data Type and enabled the Blocks Toolbar Option. Then Blocks can be created directly inside the Rich Text Editor.
Configure Blocks
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.
Blocks Live editing mode - Enabling this will make editing of a Block happen directly to the Rich Text Editor, making changes appear as you type.
Setup Block Types
Block Types are Element Types that 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. If they are set beforehand then they need to be added to the Rich Text Editor afterward.
Once you add an Element Type as a Block Type on your Rich Text Editor Data Type you will have options 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 can use AngularJS template string syntax to display values of properties.
Display Inline with text - When turned on the Block Element will be able to stay in line with text or other elements. If not the Block will stay on its own line.
Custom view - Overwrite the AngularJS view for the block presentation in the Content editor. Use this to make a more visual presentation of the block or even make your own editing experience by adding your own AngularJS controller to the view.
Data Models
It is possible to use two separate Element Types for your Block Types. It's required to have one for Content and optional to add one for Settings.
Content model - This presents the Element Type used as a 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 catalog 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.
The thumbnails for the catalog 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.
Rendering Blocks
To render Blocks in the frontend, you must create Partial Views for each Block.
The Partial Views must be:
Named by the alias of the Element Type that is being used as the Content Model for the Block.
Placed in the folder Views/Partials/RichText/Components/.
For example, if the Element Type alias of the Content Model is myBlockType, a Partial View must be created at Views/Partials/RichText/Components/MyBlockType.cshtml.
The Partial View will receive the model of Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem. This gives you the option to access properties of the Content and Settings Models of your Block, as illustrated in the following sample:
If you use ModelsBuilder, you can specify the Content Model (and optionally the Settings Model) in the Partial View model. This allows for type-safe access to the Block data.
The following example shows a Partial View of a Block with MyBlockType as Content Model and MyBlockSettingsType as Settings Model:
Build a Custom Backoffice View
Building Custom Views for Block representations in Backoffice is the same for all Block Editors.
Members
Members are used for registering and authentication external / frontend users of an Umbraco installation. This could be Forum members and Intranet members.
Members are used for registering and authenticating external users of an Umbraco installation (ie. forum members, intranet users and so forth).
This guide will explain how to define and create members in the backoffice. If you want to work with members using the service APIs, links can be found at the end of the document.
There is a default Member Type that can be used to create members. You can customize this to fit your needs or create your own Member Type from scratch.
Creating a Member
Go to the Members section, right-click Members in the member tree, click Create and choose Member.
Members have a number of mandatory properties that need to be filled in before a member can be saved. The properties are Login, Email, and the two Password fields in the Member tab.
There are also a number of default properties in the Member tab which are stored in the database in the tables Member andTwoFactorLogin:
umbracoMemberFailedPasswordAttempts
umbracoMemberApproved
umbracoMemberLockedOut
Once the Member is created and saved you can access it by expanding the Members tree and clicking All Members to get a list view. You can also view members of a specific type by selecting the member type in the Members tree.
Sensitive properties on a members data will not be displayed to backoffice users unless they have appropriate permissions. In order to see the values of the default properties in the Member tab you need to have the Sensitive data User Group. By having this group added to a user they will also have the option to mark member type properties as sensitive.
More information can be found under .
Creating a Member Type
You can create your own Member Types and add tabs, groups and properties as you would with Document Types.
Go to the Settings section, right-click Member Types and select Create. You will now be taken to the Member Type editor that is used to define and edit the Member Type. Name the new Member Type and click Save.
Once created, the Member Type will have no properties, so you have the freedom to add your own properties or compositions.
Assigning a Member Composition
When creating a Member Type you can assign compositions. Compositions allow you to inherit tabs and properties from existing member types instead of creating them from scratch.
For example on the member type that you have created, click on Composition. Then you can choose the existing Member type which then you will inherit its tabs, groups, and properties.
The default Member type has a Membership group which includes umbracoMemberComments property along with the other default properties. The other properties can be seen only in the Member tab when creating a member.
It is possible to add more groups and more properties to each of the Member Types you create, as well as the default Member Type.
Creating Member Groups
Member Groups define roles for your members that can be used for role-based protection. A member can be in multiple groups.
To create a new Member Group click the menu icon next to the Member Groups node in the Members section. Choose Create, name the group, and save the group.
Assigning a Member Group
To assign a member to a specific group find the member you wish to assign and find the Properties group. Here you can see which groups the member is already part of. You can also add the member to more groups or remove the member from already assigned groups:
Technical
As a developer you are able to leverage your website when you build on the Members section of Umbraco. The member's section is by default in the Umbraco backoffice, but you can still use it to implement some work on your front end. Members are created using ASP.NET Core Identity, so there are some provider settings that can be set in appsettings.json - here are the defaults:
You can find out more about the services methods in the reference section of the documentation by following the links below.
References
Video:
Video:
Video:
Related Services
Media Picker (Legacy)
We highly recommend that you use the Media Picker instead.
This updated property contains more customizable features, and we recommend using this over the Media Picker, which is also marked as the old version of the picker.
Alias: Umbraco.MediaPicker
Returns: IEnumerable<IPublishedContent> or IPublishedContent
This property editors returns a single item if the "Pick multiple items" Data Type setting is disabled or a collection if it is enabled.
Data Type Definition Example
Ignore user start nodes
Use Settings to overrule user permissions, to enable any user of this property to pick any Media Item of the choosen Start node.
When this setting is enabled, a user who doesn't normally have access to the media selected as "Start Node" (/Design in this case), can access the media when using this particular Media Picker. If no Start node has been defined for this property any content can be viewed and selected of this property.
Content Example
MVC View Example
Multiple enabled without Modelsbuilder
Multiple enabled with Modelsbuilder
Multiple disabled without Modelsbuilder
Multiple disabled with Modelsbuilder
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 example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
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.
Contents
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 Settings section.
Open the Permissions 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.
Each Property Editor that does not allow variants (an Invariant Property) will by default need to be unlocked in order to be edited. The lock exists to make it clear that this change will affect more languages. Since the value of the invariant properties are shared between all variants on the website.
Whether or not the lock is enabled on the invariant properties depends on the AllowEditInvariantFromNonDefault setting in the appsettings.json file.
Learn more about the AllowEditInvariantFromNonDefault setting in the article.
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:
Right-click 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.
Related Links
Content Templates
In this article you can learn about how to create and use Content Templates in Umbraco.
Content Templates allows a content editor to create a blueprint for new content nodes based on an existing node.
Create - Method 1
Before following this method you should have some created beforehand.
Select a Content node from the Content menu:
Right-click the Content node and select the Create Content Template option. Alternatively, select the Actions dropdown of the content node and select the Create Content Template option:
Give your content template a Name:
Click the Create button and if the creation was successful, you will see a success notification:
The new content template will be created in Content Templates node of the Settings tree:
Refresh your browser, if you do not see the new content template in the Content Templates folder.
Create - Method 2
Click on the Settings menu:
Right-click on the Content Templates tree and select the Create menu item:
Select the Document Type you want to create a content template for:
You can create content templates only from Document Types or Document Types with Templates
Give your content template a Name and click the Save button:
The new content template will be created in Content Templates folder of the Settings tree:
Edit
To edit an existing content template, select a content template from the Content Templates folder of the Settings tree. When you have finished editing click the Save button:
Use
Once you have created a content template, you can use the template to create new content nodes. To use a content template, right-click the Content tree and select Create:
When you click on a Document Type that has a content template you will see two options:
Create a new node based on a content template
Create a blank one
Rich Text Editor
Alias: Umbraco.TinyMCE
Returns: HTML
The Rich Text Editor (RTE) is based on tinymce and is highly configurable. Depending on the configuration, it will give your content editors more flexibility when working with content that should be more than only plain text.
Are you using custom configuration or plugins with TinyMCE?
In Umbraco 11 the TinyMCE version supported has been upgraded from version 4 to version 6. You need to migrate to the latest version if you are using TinyMCE plugins or custom configuration.
If your site is upgraded from an older version, follow the migration guides below to upgrade the TinyMCE version as well.
Customize everything from toolbar options to editor size to where pasted images are saved.
Use CSS to define specific editor styles and add them as formatting options of the Rich Text Editor.
Use Blocks to define specific parts which can be added as part of the markup of the Rich Text Editor.
Extend the functionality of the Rich Text Editor with plugins.
Data Type Definition Example
Content Example
MVC View Example
Without Modelsbuilder
With Modelsbuilder
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 example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Default Data Types
Learn about the default data types in Umbraco.
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 Property Editors.
Umbraco 9 Data Type List
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 values as a list of checkbox controls. The preset values are modified in the Settings section under Data Types in Checkbox List where new items can be added. The value saved is a comma-separated string of prevalue 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 values as a list where only a single value can be selected. The default Data Type does not contain any prevalues. The value saved is the selected value as a string.
Dropdown multiple
Displays a list of preset values as a list where multiple values can be selected. The default Data Type does not contain any prevlaues. The value saved is a comma separated string of prevalue 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.
List View - Content
This Data Type is used by Document Types that are set to display as list views.
List View - Media
This Data Type is used by Media Types that are set to display as list views.
List View - Members
This Data Type is used by Member Types that are set to display as list views.
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
The TinyMCE based WYSIWYG editor. This is the standard editor used to edit 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.
In the default settings some tags such as bullet list can be used. If you want to use other tags like h1 or h2, you need to add stylesheets.
Create Rich Text Editor stylesheets for each tag(h1 or h2) and select them when configuring the Rich Text Editor Data Type. Learn more about how to configure this Data Type in the .
The "Style select" options need to be enabled in the toolbar section.
An example of the stylesheet tree is as follows:
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
Tags
Alias: Umbraco.Tags
Returns: IEnumerable<string>
The Tags property editor allows you to add multiple tags to a node.
Data Type Definition Example
Tag group
The Tag group setting provides a way to categorize your tags in groups. So for each category you will create a new instance of the Tags property editor and setup the unique category name for each instance. Whenever a tag is added to an instance of the tags property editor it's added to the tag group, which means it will appear in the Typeahead list when you start to add another tag. Only tags that belong to the specified group will be listed. If you have a "Frontend" group and a "Backend" group the tags from the "Frontend" group will only be listed if you're adding a tag to the Tags property editor configured with the "Frontend" group name and vice versa.
Storage type
Data can be saved in either Comma-Separated Values (CSV) format or in JSON format. By default data is saved in JSON format. The difference between using CSV and JSON is that with JSON you can save a tag, which includes comma separated values.
There are built-in property value converters, which means you don't need to worry about writing them yourself or parse the JSON output when choosing "JSON" in the storage type field. Therefore on this page will work out of the box without further ado.
Content Examples
CSV tags
JSON tags
Tags typeahead
Whenever a tag has been added it will be visible in the typeahead when you start typing on other pages.
MVC View Example - displays a list of tags
Multiple items - with Modelsbuilder
Multiple items - without Modelsbuilder
Setting Tags Programmatically
You can use the ContentService to create and update Umbraco content from c# code, when setting tags there is an extension method (SetTagsValue) on IContentBase that helps you set the value for a Tags property. Remember to add the using statement for Umbraco.Core.Models to take advantage of it.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled, you can get the alias of the desired property without using a magic string:
More on working with Tags
More on working with Tags (query all of them) can be found at the
Running Umbraco On Azure Web Apps
This section describes best practices with running Umbraco on Azure Web Apps
What are Azure Web Apps
They have been called a few names in the past, many people still know Azure Web Apps as Azure Web Sites.
App Service is a fully Managed Platform for professional developers that brings a rich set of capabilities to web, mobile and integration scenarios. Quickly create and deploy mission critical web Apps that scale with your business by using Azure App Service.
Umbraco will run on Azure Web Apps but there are some configuration options and specific Azure Web Apps environment limitations to be aware of.
Recommended configuration
You need to add these configuration values. E.g in a json configuration source like appSettings.json:
You can also copy the following JSON directly into your Azure Web App configuration via the Advanced Edit feature.
Remember to add an ASPNETCORE_ENVIRONMENT variable with values Development, Staging, or Production.
The minimum recommended Azure SQL Tier is "S2", however noticeable performance improvements are seen in higher Tiers
If you are load balancing or require the scaling ("scale out") ability of Azure Web Apps then you need to consult the . This is due to the fact that a lot more needs to be configured to support scaling/auto-scaling.
Storage
It is important to know that Azure Web Apps uses a remote file share to host the files to run your website. This is due to the files running your website do not exist on the machine running your website. In many cases this isn't an issue. It can become one if you have a large amount of IO operations running over remote file-share.
Issues with read-only filesystems
Although Umbraco can be configured to use environmental storage it still requires its working-directory to be writable. If Umbraco is deployed to a read-only file system it will .
For example, Azure's is not supported by Umbraco. To check if your web app is using this feature you can check the WEBSITE_RUN_FROM_PACKAGE environment variable.
Scaling
If you require the scaling ("scale out") ability of Azure Web Apps you need to consult the . This is due to the fact that a lot more needs to be configured to support scaling/auto-scaling.
Web worker migrations
It's important to know that Azure Web Apps may move your website between their 'workers' at any given time. This is normally a transparent operation. In some cases you may be affected by it if any of your code or libraries use the following variables:
Environment.MachineName (or equivalent)
When your site is migrated to another worker, these variables will change. You cannot rely on these variables remaining static for the lifetime of your website.
How to find the Linux App Service Logs
The quickest way to get to your logs is using the following URL template and replacing {app} with your Web App name:
https://{app}.scm.azurewebsites.net/api/logstream
You can also find this in the KUDU console by clicking Advanced Tools > Log Stream on the Web App in the Azure Portal.
Web App secret management
Consult the if you would like to directly reference Azure Key Vault Secrets to your Azure Web App.
Rich Text Editor Plugins
Information on how to work with TinyMCE plugins in the rich text editor.
The global configuration of TinyMCE will be removed in Umbraco 14 in order to support more rich text editors in the future. Instead, a new extension type called “tinyMcePlugin” will be added.
Overview
Rich Text Editor Configuration
Configuration
In this article you can learn about the various ways you can configure the RTE.
Advanced Techniques With Flexible Load Balancing
This describes some more advanced techniques that you could achieve with flexible load balancing
The election process that runs during the startup of an Umbraco instance determines the server role that instance will undertake.
There are two server roles to be aware of for flexible load balancing:
SchedulingPublisher - The Umbraco instance usually used for backoffice access, responsible for running scheduled tasks.
Markdown Editor
Alias: Umbraco.MarkdownEditor
Returns: System.Web.HtmlString
This built-in editor allow the user to use the markdown formatting options, from within a tinyMCE-like interface.
Data Type Definition Example
User Picker
Alias: Umbraco.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
Installation
Instructions on installing Umbraco on various platforms using various tools.
Install Umbraco using CLI
The fastest way to get the latest version of Umbraco up and running is using the command line (CLI).
Open your command line.
@using System.IO;
@{
if (Model.HasValue("myFile"))
{
var myFile = Model.Value<string>("myFile");
<a href="@myFile">@System.IO.Path.GetFileName(myFile)</a>
}
}
@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 Services;
@inject IJsonSerializer _serializer;
@inject MediaUrlGeneratorCollection _mediaUrlGeneratorCollection;
@{
// Get access to ContentService
var contentService = Services;
// Get access to MediaService
var mediaService = MediaService;
// 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'myFile'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MyFile).Alias, publishedMedia.Url();
}
@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>
}
}
@using Umbraco.Cms.Core.Models
@{
var link = Model.Value<Link>("link");
if (link != null)
{
<a href="@link.Url" target="@link.Target">@link.Name</a>
}
}
@using Umbraco.Cms.Core;
@using Umbraco.Cms.Core.Services;
@using Newtonsoft.Json;
@using Umbraco.Cms.Core.Models;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Get the 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 externalLink = 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 = JsonConvert.SerializeObject(externalLink);
// Set the value of the property with alias 'footerLinks'.
content.SetValue("footerLinks", links);
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'footerLinks'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.FooterLinks).Alias, links);
}
@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 Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Set the value of the property with alias 'singleValueSlider'.
content.SetValue("singleValueSlider", 10);
// Save the change
contentService.Save(content);
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'singleValueSlider'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.SingleValueSlider).Alias, 10);
// Set the value of the property with alias 'multiValueSlider'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MultiValueSlider).Alias, new Range<decimal> {Minimum = 10, Maximum = 12});
}
@{
if (Model.Value<string[]>("keyFeatureList").Length > 0)
{
<ul>
@foreach (var item in Model.Value<string[]>("keyFeatureList"))
{
<li>@item</li>
}
</ul>
}
}
@{
if (Model.KeyFeatureList.Any())
{
<ul>
@foreach (var item in Model.KeyFeatureList)
{
<li>@item</li>
}
</ul>
}
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'keyFeatureList'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.KeyFeatureList).Alias, "Awesome" + Environment.NewLine + "Super");
}
@{
// 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>
}
}
@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Set the value of the property with alias 'color'.
// The value set here, needs to be one of the prevalues on the Color Picker
content.SetValue("color", "38761d");
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;
@{
// Set the value of the property with alias 'color'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Color).Alias, "38761d");
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@using Newtonsoft.Json
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Set the value of the property with alias 'categories'.
content.SetValue("categories", JsonConvert.SerializeObject(new[] { "News" }));
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'categories'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Categories).Alias, JsonConvert.SerializeObject(new[] { "News" }));
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Get the page you want to assign to the content picker
var page = Umbraco.Content("665d7368-e43e-4a83-b1d4-43853860dc45");
// Create an Udi of the page
var udi = Udi.Create(Constants.UdiEntityType.Document, page.Key);
// Set the value of the property with alias 'featurePicker'.
content.SetValue("featurePicker", udi.ToString());
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@using Umbraco.Cms.Core;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'featurePicker'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.FeaturePicker).Alias, udi.ToString());
}
@{
if (Model.HasValue("superHeros"))
{
<ul>
@foreach (var item in Model.Value<IEnumerable<string>>("superHeros"))
{
<li>@item</li>
}
</ul>
}
}
@{
if (Model.SuperHeros.Any())
{
<ul>
@foreach (var item in Model.SuperHeros)
{
<li>@item</li>
}
</ul>
}
}
@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@using Newtonsoft.Json
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Set the value of the property with alias 'superHeros'.
content.SetValue("superHeros", JsonConvert.SerializeObject(new[] { "Umbraco", "CodeGarden"}));
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;
@{
// Set the value of the property with alias 'superHeros'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor,x => x.SuperHeros).Alias, JsonConvert.SerializeObject(new[] { "Umbraco", "CodeGarden"}));
}
Templates Short Name Language Tags
------------------------------------------------------------------------------------------------------
Umbraco Project umbraco [C#] Web/CMS/Umbraco
Umbraco Package umbracopackage [C#] Web/CMS/Umbraco/Package/Plugin
Umbraco Project (C#)
Author: Umbraco HQ
Description: An empty Umbraco project ready to get started.
Options:
-v|--version The version of Umbraco.Cms to add as PackageReference.
string - Optional
Default: 10.0.0
--use-https-redirect Adds code to Program.cs to redirect HTTP to HTTPS and enables the UseHttps setting.
bool - Optional
Default: false
--no-restore If specified, skips the automatic restore of the project on create.
bool - Optional
Default: false
--exclude-gitignore Whether to exclude .gitignore from the generated template.
bool - Optional
Default: false
--minimal-gitignore Whether to only include minimal (Umbraco specific) rules in the .gitignore.
bool - Optional
Default: false
--connection-string Database connection string used by Umbraco.
string - Optional
--connection-string-provider-name Database connection string provider name used by Umbraco.
string - Optional
Default: Microsoft.Data.SqlClient
--development-database-type Database type used by Umbraco for development.
None - Do not configure a database for development.
SQLite - Use embedded SQLite database.
LocalDB - Use embedded LocalDB database (requires SQL Server Express with Advanced Services).
Default: None
--friendly-name Used to specify the name of the default admin user when using unattended install on development (stored as plain text).
string - Optional
--email Used to specify the email of the default admin user when using unattended install on development (stored as plain text).
string - Optional
--password Used to specify the password of the default admin user when using unattended install on development (stored as plain text).
string - Optional
--no-nodes-view-path Path to a custom view presented with the Umbraco installation contains no published content.
string - Optional
-p|--PackageTestSiteName The name of the package project this should be a test site for.
string - Optional
If there are any specific configuration changes required for the version you are upgrading to then they will be noted in the
.
file in the root of your site
(Important: make sure to copy back the version number, and the connection string as they were.)
In rare cases, the web.config file in the Views folder
Document Types in Umbraco: Defining Properties, Data Types and Property Editors
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
Fix the backoffice environment to be the SCHEDULINGPUBLISHER scheduling server and the scalable public-facing environment to be SUBSCRIBERs - see Setting Explicit Server Roles
Custom stylesheet - Pick your own stylesheet to be used for this block in the Content editor. By adding a stylesheet the styling of this block will become scoped. Meaning that backoffice styles are no longer present for the view of this block.
Overlay editor size - Set the size for the Content editor overlay for editing this block.
Thumbnail - Pick an image or Scalable Vector Graphics (SVG) file to replace the icon of this Block in the catalog.
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
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.
Subscriber - A scalable instance that subscribes to content updates from the SchedulingPublisher server, not recommended to be used for backoffice access.
These new terms replace 'Master and Replica', in Umbraco versions 7 and 8.
Explicit SchedulingPublisher server
It is recommended to configure an explicit SchedulingPublisher server since this reduces the amount of complexity that the election process performs.
The first thing to do is create a couple of small classes that implement IServerRoleAccessor one for each of the different server roles:
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.
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
This description pertains only to Umbraco database tables
In some cases infrastructure admins will not want their front-end servers to have write access to the database. By default front-end servers will require write full access to the following tables:
umbracoServer
umbracoNode
This is because by default each server will inform the database that they are active and more importantly it is used for task scheduling. Only a single server can execute task scheduling and these tables are used for servers to use a server role election process without the need for any configuration. So in the case that a subscriber server becomes the SchedulingPublisher task scheduler, it will require write access to all of the Umbraco tables.
In order to have read-only database access configured for your front-end servers, you need to implement the Explicit SchedulingPublisher server configuration mentioned above.
Now that your subscriber servers are using your custom SubscriberServerRoleAccessor class, they will always be deemed 'Subscriber' servers and will not attempt to run the automatic server role election process or task scheduling. Because you are no longer using the default ElectedServerRoleAccessor they will not try to ping the umbracoServer table.
If using SqlMainDomLock on Azure WebApps then write-permissions are required for the following tables for all server roles including 'Subscriber'.
umbracoLock
umbracoKeyValue
SQL Server Replica databases cannot be used as they are read-only without replacing the default MainDomLock with a custom provider.
Controlling how often the load balancing instructions from the database are processed and pruned
The configurations can be adjusted to control how often the load balancing instructions from the database are processed and pruned.
Below is shown how to do this from a JSON configuration source.
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.
Install the Umbraco templates:
Replace 13.* with the specific version you want to install.
Example:
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
Open your browser and navigate to that URL.
Follow the instructions to finish up the installation of Umbraco.
Members of the Umbraco Community have created a website that makes the installation of Umbraco a lot easier for you. You can find the website at https://psw.codeshare.co.uk. On the website, you can configure your options to generate the required script to run. Click on the Install Script tab to get the commands you need to paste into the terminal. This tab also includes the commands for adding a starter kit or unattended install which creates the database for you.
Alternative Methods for Installing Umbraco
There are numerous ways to install Umbraco. Below, you can find links to different installation methods that will help you easily install and set up Umbraco projects.
.NET CLI, 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.
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.
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem>
@* Output the 'heading' field from the Content Model using the `backgroundColor` field from the Settings Model as background color *@
<h1 style="background-color:@Model.Settings.Value("backgroundColor")">@Model.Content.Value("heading")</h1>
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem<MyBlockType, MyBlockSettingsType>>
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;
@* Output the Heading of field with alias 'heading' from the 'MyBlockType' Content Model *@
<h1 style="background-color:@Model.Settings.BackgroundColor">@Model.Content.Heading</h1>
@{
var typedMultiMediaPicker = Model.Value<IEnumerable<IPublishedContent>>("sliders");
foreach (var item in typedMultiMediaPicker)
{
<img src="@item.Url()" style="width:200px"/>
}
}
@{
var typedMultiMediaPicker = Model.Sliders;
foreach (var item in typedMultiMediaPicker)
{
<img src="@item.Url()" style="width:200px" />
}
}
@{
var typedMediaPickerSingle = Model.Value<IPublishedContent>("featuredBanner");
if (typedMediaPickerSingle != null)
{
<p>@typedMediaPickerSingle.Url()</p>
<img src="@typedMediaPickerSingle.Url()" style="width:200px" alt="@typedMediaPickerSingle.Value("alt")" />
}
}
@{
var typedMediaPickerSingle = Model.FeaturedBanner;
if (typedMediaPickerSingle is Image image)
{
<p>@image.Url()</p>
<img src="@image.Url()" style="width:200px"/>
}
}
@using Umbraco.Cms.Core;
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Get the 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'featuredBanner'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.FeaturedBanner).Alias, udi.ToString());
}
@{
if (Model.HasValue("richText")){
<p>@(Model.Value("richText"))</p>
}
}
@{
if (!string.IsNullOrEmpty(Model.RichText.ToString()))
{
<p>@Model.RichText</p>
}
}
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'richText'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.RichText).Alias, "Add some text <strong>here</strong>");
}
Stylesheets
-IE7
-IE8
-Style
-RichEdit
--h1
--h2
@if(Model.Tags.Any()){
<ul>
@foreach(var tag in Model.Tags){
<li>@tag</li>
}
</ul>
}
@if(Model.HasValue("tags"))
{
var tags = Model.Value<IEnumerable<string>>("tags");
<ul>
@foreach(var tag in tags)
{
<li>@tag</li>
}
</ul>
}
@using Umbraco.Cms.Core.Services
@inject IContentService Services;
@using Newtonsoft.Json
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("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", JsonConvert.SerializeObject(new[] { "News", "Umbraco", "Example", "Setting Tags", "Helper" }));
// Save the change
contentService.Save(content);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'tags'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Tags).Alias, JsonConvert.SerializeObject(new[] { "News", "Umbraco", "Example", "Setting Tags" }));
}
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>();
The Rich Text Editor (RTE) in Umbraco is based on the open source editor TinyMCE. TinyMCE is a highly customizable editor, and it is possible to extend the functionality of the editor by adding plugins.
TinyMCE comes with a lot of plugins out of the box, but it is also possible to create your own plugins. This article will show you how to add a custom plugin to the rich text editor.
Open-Source Plugins
TinyMCE has a lot of open-source plugins available. You can find a list of these plugins on the TinyMCE website.
To enable plugins in the rich text editor, you need to add it to the Plugins array in the configuration of the rich text editor.
The example above shows how to add the open-source Word Count Plugin to the rich text editor. The plugin is added to the Plugins array in the configuration. The plugin itself will be shown in the statusbar of the rich text editor, so the statusbar option is also added to the CustomConfig object.
Adding a premium plugin
To add a premium plugin, you need to add the plugin name to the Plugins array in the configuration of the rich text editor. You also need to add the "CloudApiKey" to the configuration.
We have enabled the powerpaste plugin, and configured it to allow local images. It will prompt when pasting Word documents, but for HTML documents it will clean the HTML without prompting.
You can go to TinyMCE Cloud and sign up for a free trial. You will get a Cloud API key that you can use to try out the premium plugins.
Creating a Custom Plugin
If you want to create your own plugin, you should in general follow the TinyMCE documentation. However, there are a few things you need to be aware of to load the plugin in Umbraco. See the example below.
Examples
Load a custom plugin that gives you the ability to interact with the global tinymce editor object.
Here we are loading a custom plugin called myrteplugin and adding a button to the editor called myrtebutton. When the button is clicked, it will insert the text Hello World! into the editor.
The text "Hello World!" shows up after clicking the button
The button must be added to the toolbar in the rich text editor configuration.
Enable the button in the rich text editor configuration
You can go to any Document Type that uses the rich text editor and click the button to insert the text Hello World! after.
You have full control over which options should be available on the RTE.
Toolbar: All options enabled
In the examble above, all 34 options have been enabled. The options include copy/paste buttons, font styles like bold and italics, bullet lists and options to embed videos and insert images.
Stylesheets
It is possible to define specific styles that can be used when editing content using the RTE. You can use as many of these styles with the RTE as you want.
The RTE styles are defined in CSS files which can be created in the Settings section. Read the RTE Styles article to learn more about this feature.
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.
Mode
The Rich Text Editor comes in two different modes: Classic and Inline.
Classic
The default mode which displays the toolbar at the top.
RTE Mode: Classic
Inline
In this mode the toolbar is hidden, and only shows up when content in the editor is highlighted.
Rich Text Editor Inline mode
Blocks
Blocks can be added as elements in the Rich Text Editor. Configuration and rendering of Blocks is described in the Blocks in Rich Text Editor article.
Overlay Size
Select the width of the link picker overlay. The overlay size comes in three sizes: Small, Medium, and Large.
Hide Label
When this option is checked the label and description for the RTE property will be hidden.
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.
Image Upload Folder
Images added through the RTE is 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.
Advanced Configuration
The global configuration of RichTextEditor will be removed in Umbraco 14 to support more rich text editors in the future. Instead, a new extension type called “tinyMcePlugin” will be added.
The RTE can also accept advanced configuration through the appSettings.json file fed into the TinyMCE configuration. This is within Umbraco:CMS:RichTextEditor and allows you to configure the following:
CustomConfig is slightly different from the rest as it extends the core config passed into TinyMCE.
Read more about the advanced configuration and how to set it up in Umbraco in the Rich Text Editor Settings article.
Allowing script tags in the RTE
Sometimes you want to allow your content editors to be able to add <script> tags into the RTE. This tag is classed as invalid by default which means the configuration needs to be updated to allow it. This is not something that can be done through the CMS and requires advanced configuration in the appSettings.json file. It uses the ValidElements property to append ,script[*] to the pre-existing list of valid elements as shown below.
Definition Example
There are three settings available for manipulating the Markdown editor property.
Preview toggles if a preview of the markdown should be displayed beneath the editor in the content view.
Default value is inserted if no content has been saved to the Document Type using this property editor.
Overlay Size is used to select the width of the link picker overlay in the content view.
Content Example
Content Example
Explanation of buttons from left to right
Function
Shortcut
Further explanation
toggle bold text
Ctrl + B
toggle italic text
Ctrl + I
insert link
Ctrl + L
This opens the Select Link interface.
toggle quote
Ctrl + Q
Other functionality
Function
Shortcut
select all
Ctrl + A
copy
Ctrl + C
paste
Ctrl + V
MVC View Example
With Modelsbuilder
Without Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Media Picker Data Type Definition
Content Example
Member Picker Content
MVC View Example
Getting the Value of the property will return the user ID - properties of the User can be accessed by referencing UserService.
Without Modelsbuilder
With Modelsbuilder
Add values programmatically
See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
This document should be used as a reference, not a step by step guide. Upgrading will largely depend on what version of Umbraco you are currently running, what packages you have installed and the many
It is critical that you back up your website and database before upgrading. There are database changes made during installation and you cannot revert an Umbraco 7 database to an Umbraco 6 database.
.Net 4.5
Umbraco 7 is built on .Net 4.5 and your development environment will require this version installed in order to operate. Visual Studio users may require 2012 or higher.
HTML 5 browser support
Umbraco 7 requires browsers with proper HTML 5 support, these include Chrome, Firefox, IE10+
Breaking changes
Before you upgrade be sure to read the list of breaking changes. This is especially recommended if you have removed or modified code in the core or if one of these breaking changes directly affects your installation.
for more details.
Examine
It is recommended to rebuild all Examine indexes after completing the upgrade.
Xml Cache rebuild
You should re-generate the XML cache. This can be done by following the prompts when visiting the following URL:
It is recommended that you use a Diff tool to compare the configuration file changes with your own current configuration files.
/web.config updates
You will need to compare the new Umbraco 7 web.config with your current web.config. Here is a quick reference of what needs to change:
Medium Trust
Umbraco 7+ will no longer support medium trust environments. There are now some assemblies used in the core that do not support medium trust but are used extensively. Plugin scanning now also allows for scanning Umbraco's internal types which requires full trust.
Events
Tree events
Content, Media, Members, and Data Type trees will no longer raise the legacy tree events (based on BaseTree). It is recommended to change all tree event handlers to use the new tree events that fire for every tree in Umbraco including legacy trees. The new tree events are static events and are found in the class Umbraco.Web.Trees.TreeControllerBase:
MenuRendering
RootNodeRendering
TreeNodesRendering
Legacy business logic events
The Content, Media, Member, and Data Type editors have been re-created and are solely using the new Umbraco Services data layer. This means that operations performed in the backoffice will no longer raise the legacy business logic events (for example, events based on umbraco.cms.businesslogic.web.Document). It is recommended to change your event handlers to subscribe to the new Services data layer events. These are static events and are found in the services. For example: Umbraco.Core.Services.ContentService.Saved.
Property Editors
Legacy property editors (pre-Umbraco 7) will not work with Umbraco 7. During the upgrade installation process, Umbraco will generate a report showing you which legacy property editors are installed. These will all be converted to a readonly Label property editor. No data loss will occur but you'll need to re-assign your existing data types to use a new compatible Umbraco 7 property editor.
Most Umbraco core property editors shipped will be mapped to their equivalent Umbraco 7 editors. The Image cropper editor has not been completed for v7.0.
The Related Links property editor and XSLT
Since the Related Links property is an advanced property editor, the data format has changed from XML to JSON. This should not have any effect when retrieving the data from razor. If you are outputting Related Links data with XSLT you will need to update your XSLT snippet. Making use of the new library method umbraco.library:JsonToXml and taking into account that the xml structure has also slightly changed.
GUID -> Alias mapping
One of the database changes made in Umbraco 7 is the change of referencing a property editor from a GUID to a string alias. In order to map a legacy property editor to a new Umbraco 7 version you can add your custom "GUID -> Alias" map during application startup. To do this you would add your map using this method: Umbraco.Core.PropertyEditors.LegacyPropertyEditorIdToAliasConverter.CreateMap
Parameter Editors
Legacy parameter editors (pre-Umbraco 7) will not work with Umbraco 7. If Umbraco detects legacy parameter editor aliases that do not map to a Umbraco 7 parameter editor it will render a textbox in its place. You will need to update your macros to use a compatible Umbraco 7 parameter editor as those that aren't supported.
Previously, parameter editors were registered in an Umbraco database table: cmsMacroPropertyType which no longer exists. Parameter editors in Umbraco 7 are plugins like property editors. During the Umbraco 7 upgrade installation process it will update the new cmsMacroProperty.editorAlias column with the previous parameter editor alias. During this process it will look into the Umbraco.Core.PropertyEditors.LegacyParameterEditorAliasConverter for a map between a legacy alias to a new Umbraco 7 alias.
Custom legacy parameters can be mapped to new Umbraco 7 parameter editor aliases during installation. This can be done by modifying the mapping during application startup using this method: Umbraco.Core.PropertyEditors.LegacyParameterEditorAliasConverter.CreateMap.
Database changes
All database changes will be taken care of during the upgrade installation process.
Tags
See above for the database updates made for better tag support.
Tags can now be assigned to a nodes property and not only a node
Multiple tag controls can exist on one page with different data
The legacy API does not support this, the legacy API will effectively, add/update/remove tags for the first property found for the document that is assigned a tag property editor.
Packages
You should check with the package creator for all installed packages to ensure they are compatible with Umbraco 7.
For package developers
We see common errors that we cannot fix for you, but we do have recommendations you can follow to fix them:
TypeFinder
The TypeFinder has been deprecated since 4.10 and is now found under Umbraco.Core.TypeFinder.
JavaScript in menu actions
While you need to have JavaScript inside menu actions to trigger a response, it is highly recommended that you use the recommended UmbClientMgr methods. You should not try to override parent.right.document and similar tricks to get to the right-hand frame.
Use the recommended Umbraco uicontrols
If you have a webforms page, it is recommended to use the built-in ASP.NET controls to render panels, properties and so on. If you use the raw HTML or try to style it to match the backoffice, you will get out of sync. Follow the guidelines set by Umbraco's internal editors and use the ASP.NET custom controls for UI.
Minor upgrades for Umbraco 8
This article provides details on how to upgrade to the next minor version when using Umbraco 8.
Sometimes there are exceptions to these guidelines, which are listed in the version-specific guide.
Note
It is necessary to run the upgrade installer on each environment of your Umbraco site. If you want to update your staging and live site you need to repeat the steps below. Make sure you click through the install screens so that your upgrade is complete.
Contents
In this article you will find instructions for 3 different ways of upgrading:
Upgrade using NuGet
Open up the Package Console and type: Update-Package UmbracoCms
Choose "No to All" by pressing the "L" when prompted.
Alternatively, you can use the Visual Studio NuGet Package Manager to upgrade:
Open the NuGet Package Manager and select the Updates pane to get a list of available updates.
Choose the package called UmbracoCms and select update.
The upgrade will run through all the files and make sure you have the latest changes while leaving files you have updated.
Upgrade manually from a zip file
Download the .zip file for the new version you are upgrading to from
Copy the following folders from inside the .zip file over the existing folders in your site:
/bin
/Umbraco
There are hosting providers (we know of one: RackSpace Cloud) that require proper casing of file and folder names. Normally on Windows this is not a problem. If your hosting provider however forces proper casing, you will need to verify that the folder and file names are in the same casing as in the newest version you're upgrading to.
Merge configuration files
You can expect some changes to the following configuration files:
Any file in the /Config folder
The /Global.asax file
The web.config
Use a tool like to check changes between all of the config files. Depending on when you last did this there may have been updates to few of them.
There's also the possibility that some files in the /Config folder are new or some have been removed (we do make a note of this in the release notes). WinMerge (and other diff tools) can compare folders as well so you can spot these differences.
Merge UI.xml and language files
Some packages like Umbraco Forms add dialogs to the UI.xml. Make sure to merge those changes back in from your backup during the upgrade so that the packages continue to work. This file can be found in: /Umbraco/Config/Create/UI.xml.
Packages like Umbraco Forms and Courier also make changes to the language files located in: /Umbraco/Config/Lang/*.xml (typically en.xml).
Finalize
After copying the files and making the config changes, you can open your site. You should see the installer which will guide you through the upgrade.
The installer will do two things:
Update the version number in the web.config
Upgrade your database in case there are any changes
We are aware that, currently, the installer is asking you for the database details of a blank database while upgrading. In the near future this will be pre-filled with your existing details and the wording will be updated. So no need to be scared. Enter the details of your existing database and Umbraco will upgrade it to the latest version when necessary.
Run an unattended upgrade
When upgrading your Umbraco project to Umbraco v8.12+ it is possible to enable the upgrade to run unattended. This means that you will not need to run through the installation wizard when upgrading.
Below you will find the steps you need to take in order to upgrade your project unattended.
Are you running a load balanced setup with multiple servers and environments?
Check out the section about .
Enable the feature
Add the Umbraco.Core.RuntimeState.UpgradeUnattended key to appSettings in your web.config file.
Set the value of the key to true.
Check the ConfigurationStatus
In order to trigger the actual upgrade, the correct version number needs to be set.
It is important to use the version number of the version that you are upgrading to. If this is not set, the upgrade will not run even if the UpgradeUnattended key has been set to true.
Locate the ConfigurationStatus key in the appSettings section in your web.config file.
Update the value to match the Umbraco version that you are upgrading to.
Run the upgrade
With the correct configuration applied, the project will be upgraded on the next boot.
While the upgrade processes are running, any requests made to the site will be "put on hold", meaning that no content will be returned before the upgrade is complete.
Boot order
The Runtime level will use Run instead of Upgrade in order to allow the website to continue to boot up directly after the migration is run, instead of initiating the otherwise required restart.
The upgrade is run after Composers but before Components. This is because the migration requires services that are registered in Composers and Components requires that Umbraco and the database is ready.
Unattended upgrades in a load balanced setup
Follow the steps outlined below to use run unattended upgrades in a load balanced setup.
Upgrade Umbraco via NuGet in Visual Studio. Make sure the Umbraco.Core.ConfigurationStatus key in appSetting in the web.config file is updated to match the target version.
Deploy to all environments, including the updated appSetting for Umbraco.Core.ConfigurationStatus.
Post installation
One important recommendation is to always remove the install folder immediately after upgrading Umbraco and never to upload it to a live server.
Potential issues and gotchas
Browser cache
Google Chrome has notoriously aggressive caching, so if something doesn't seem to work well in the backoffice, make sure to clear cache and cookies thoroughly (for other browsers as well). Normally the browser cache problem is automatically handled in an Umbraco upgrade by modifying the config/ClientDependency.config version number. If you however wish to re-force this update you can increment this version number which will ensure that any server-side cache of JavaScript and stylesheets gets cleared as well.
One way to nudge the cache in Chrome is to open the developer tools (F12) and go to the settings (the cog icon). There will be a checkbox that says "Disable cache (while DevTools is open)". Once this checkbox is on you can refresh the page and the cache should be invalidated. To force it even more, the "reload" button next to your address bar now has extra options when you right-click it. It should have "Normal reload", "Hard reload" and "Empty cache and hard reload" now. The last option is the most thorough and you might want to try that.
Settings And Styling
A grid layout can also expose custom settings - such as data-attributes or styling options - on each cell or row. This allows editors to use a friendly UI to add configuration values to grid elements. When custom settings and styles are applied, they will by default be included in the grid html as either html attributes or inline styles.
These settings and styles must be configured by developers when setting up the grid layout data type.
Configuring a custom setting or style
To add a setting, click the edit settings link. This will expand a dialog showing you the raw configuration data. This data is in the JSON format and will only save if it's valid JSON.
The settings data could look like this, with an object for each setting:
The different values are:
label : Field name displayed in the content editor UI
description : Descriptive text displayed in the content editor UI to guide the user
key
label and description are straight-forward.
key defines the alias the configuration is stored under and by default the alias of the attribute will also be the attribute on the rendered html element. In the example above any value entered in this settings editor will be rendered in the grid html as:
By changing the key of the setting you can modify the <div> element's attributes like class, title, id or custom data-* attributes.
view the view defines the editor used to enter a value. By default Umbraco comes with a collection of prevalue editors:
textstring
textarea
radiobuttonlist
Alternatively you can also pass in a path to a custom view like "/App_Plugins/grid/editors/view.html"
prevalues is for views that need predefined values, e.g. the radiobuttonlist view. Prevalues are defined as strings in an array:
and will translate in to three different options where each string will become a radiobutton. The strings represent the value of the options.
Prevalues can also be defined as an object of label/value allowing to have a displayed label instead of showing the actual underlying value. You can even mix and match these and use both label/value prevalues and string prevalues in the same configuration:
modifier is a basic way to prepend, append or wrap the value from the editor in a string. This is especially useful when working with custom styles which often requires additional values to function. For instance if you want to set a background image you can get an image path from the image picker view. But in order for it to work with css it has to be wrapped in url(). In that case you set the modifier to url({0}) which means that {0} is replaced with the editor value.
applyTo defines what this setting can be applied to. It should be either row or cell as a string.
A JSON object can also be used if you need a more specific configuration. A JSON configuration could look like this:
This would ensure the setting can only be used on rows named Article or Headline, or on cells sized: 4, 8 or 6. If it should only apply to cells you can remove the row property. If it should apply to all rows you can specify it by having the row property with null or an empty string as value.
Sample settings
There are many ways to combine these, here are some samples:
Set a background image style
Set a title setting
Set a data-custom setting
Multiple settings and styles
You can add multiple settings and styles configurations on a data type. This is done by creating a new setting or style object. Remember to separate the objects with a comma.
Adding multiple settings
Full-width settings and styles
It is possible to use settings and styles to add full-width background-images, background-colors and so forth. Make sure the surrounding section is full-width (12 columns by default) and the rows inside it will automatically become full-width.
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
Umbraco allows you to implement a customn ILogViewer to fetch logs from alternative sources, such as Azure Table Storage.
Creating a Custom Log Viewer
To fetch logs from Azure Table Storage, implement the SerilogLogViewerSourceBase class from Umbraco.Cms.Core.Logging.Viewer.
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 and stored.
Register implementation
Umbraco needs to be made aware that there is a new implementation of an ILogViewer to register. We also need to replace the default JSON LogViewer that we ship in the core of Umbraco.
Configuring Logging to Azure Table Storage
With the above two 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.
Runtime Modes
This section describes how to use the runtime mode setting to optimize Umbraco for the best development experience or optimal production environment.
Configuring the runtime mode
You can configure the runtime mode to optimize Umbraco for different development experiences and environments by setting Umbraco:CMS:Runtime:Mode to one of the available modes:
Configuring Block Editor Label Properties
When configuring a block, the label property allows you to define a label for the appearance of the Block in the editor. The label can use AngularJS template string syntax to display values of properties. Example: My Block {{myPropertyAlias}} will be shown as: My Block FooBar.
You can also use more advanced expressions using AngularJS filters. Example: {{myPropertyAlias | limitTo:100}} or for a property using the Richtext editor {{myPropertyAlias | ncRichText | truncate:true:100}}.
It is also possible to use properties from the settings model by using {{$settings.propertyAlias}}.
Media Picker
Alias: Umbraco.MediaPicker3
Returns: IEnumerable<MediaWithCrops> or MediaWithCrops
This property editors returns one of the following:
A collection (IEnumerable<MediaWithCrops>
Umbraco in Load Balanced Environments
Information on how to deploy Umbraco in a Load Balanced scenario and other details to consider when setting up Umbraco for load balancing
Information on how to deploy Umbraco in a Load Balanced scenario and other details to consider when setting up Umbraco for load balancing.
Overview
Configuring and setting up a load balanced server environment requires planning, design and testing. This document should assist you in setting up your servers, load balanced environment and Umbraco configuration.
Installing Nightly Builds
Instructions on installing nightly builds of Umbraco.
In this article, we'll explain how you can get the latest builds of Umbraco. You can do this in three steps:
Build a Custom View for a Block
You can choose to customize your editing experience by implementing a custom view for each Block Type of a Block Editor.
By picking a custom view you overwrite the backoffice UI for the given block with your own. This enables you to define how a block should be presented. It can, however, also include interactive elements and be a full custom solution to how data is manipulated. In the Block List Editor the Inline Editing Mode must be disabled for custom backoffice views to appear.
Write your own HTML view
Currently you can only pick HTML files for a custom view. These views are powered by AngularJS and you can write any AngularJS logic.
'use strict'
;(function () {
/**
* @param {import('tinymce').TinyMCE} tinymce
*/
function plugin(tinymce) {
// Register a new plugin on the PluginManager
tinymce.PluginManager.add('myrteplugin', function (editor) {
// Register a new button
editor.ui.registry.addButton('myrtebutton', {
text: 'My RTE Button',
icon: 'code-sample',
// When the button is clicked, insert 'Hello World!' into the editor
onAction: function () {
editor.insertContent('Hello World!')
}
})
})
}
// Initialize the plugin only if the global `tinymce` object exists
if (window && 'tinymce' in window) {
plugin(window.tinymce)
}
})();
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'myMarkdownEditor'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MyMarkdownEditor).Alias, markdownValue);
}
@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>
}
}
@inject IContentService Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'userPicker'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.UserPicker).Alias, "Umbraco Demo");
}
: The key the entered setting value will be stored under.
view : The editor used to enter a setting value with.
prevalues : For views that need predefined values, e.g. the radiobuttonlist view.
modifier (optional) : A string formatter to modify the output of the editor to prepend or append extra values.
applyTo (optional) : States whether the setting can be used on a cell or a row. If either not present or empty, the setting will be shown both on Rows and Cells.
mediapicker
imagepicker
boolean
treepicker
treesource
number
multivalues
Your HTML can be anything. If you use it as a representation of the content you would also want the full view to be clickable. This would then open the default editor for editing of your content.
The following example displays the property with the alias headline together with the description inside a button to edit your block.
If you would like to display properties of settings, you can access these by using block.settingsData.myPropertyAlias.
Make Block List Editor custom view draggable
A custom view of Block List Editor needs to have the 'blockelement__draggable-element' class presented to define which part of the Block is draggable.
Example:
This is not relevant for the Block Grid Editor where all Blocks are draggable by default..
Add the Areas for Block Grid Editor
Blocks of the Block Grid Editor can have Areas. These Blocks require their Custom View to define where the Areas should be inserted.
This enables you to wrap and place the Areas as you need.
The Areas is inserted through Web Component Slots. A slot is a native HTML tag.
These Area slots can be generated automatically via this AngularJS Directive:
Example of a Custom View wrapping the Areas within a green border:
You can also define where each Area should be inserted. This is relevant if you like the Areas to appear differently than the provided grid setup of Areas.
As a reference here is an example of the HTML output of the umb-block-grid-render-area-slots AngularJS Directive:
Adding custom implementation to your View
To achieve this you need to add a custom AngularJS controller to your custom view, using the ng-controller attribute:
Create a folder inside the App_Plugins folder called 'CustomBlockView'.
Create two files within the CustomBlockView file: package.manifest and customBlock.controller.js.
Add the following JSON to the package.manifest file:
Umbraco will parse all package.manifest files and load any resources they reference into the backoffice during startup.
The second file, customBlock.controller.js, will be used to register the 'customBlockController' defined using the ng-controller attribute in your custom view.
To register the controller, add the following lines of code:
Example: Displaying an image from a Media Picker
Your block may enable you to 'pick' an image to use as the background for a particular block. If you try to display this image directly in the view using block.data.image, you will see the unique ID and not the image.
There are two approaches to displaying the actual image in your custom block view. Either use a filter in your custom view or retrieve the image through the AngularJS controller.
1. Retrieve the image using a filter directly in your custom view
By using the AngularJS filter called mediaItemResolver, it is possible to retrieve the image directly from your custom view file. You will need to create a variable that then uses the mediaItemResolver filter on the Media Picker property. This variable is then used to retrieve the image URL in an <img> HTML tag.
In the following example, a mediaItem variable is defined and used to set the ng-src value on the image tag. This will retrieve the image into your custom view.
2. Retrieve the image using an AngularJS controller
It is also possible to get the ImageUrl by using the unique ID in an AngularJS controller.
Amend the customBlock.controller.js file, by injecting the mediaResource to retrieve the image from the ID:
The Custom View should then be updated to use the imageUrl property to display the image:
If you need to use a specific crop, you can inject the imageUrlGeneratorResource resource. This has a getCropUrl(mediaPath, width, height, imageCropMode, animationProcessMode) method:
{
"label": "Title",
"description": "Set a title on this element",
"key": "title",
"view": "textstring"
}
{
"label": "Custom data",
"description": "Set the custom data on this element",
"key": "data-custom",
"view": "radiobuttonlist",
"prevalues": [
"value_1",
"value_2",
"value_3"
]
}
[
{
"label": "Class",
"description": "Set a class on this element",
"key": "class",
"view": "textstring"
},
{
"label": "Title",
"description": "Set a title on this element",
"key": "title",
"view": "textstring"
},
{
"label": "Custom data",
"description": "Set the custom data on this element",
"key": "data-custom",
"view": "textstring"
}
]
angular.module("umbraco").controller("customBlockController", function ($scope) {
// you can do your custom functionality here!
});
<div ng-click="block.edit()">
<h2 ng-bind="block.data.headline"></h2>
<!-- Use the 'mediaItemResolver' on the block.data.image -->
{{mediaItem = (block.data.image[0].mediaKey | mediaItemResolver); “”}}
<!-- Use the variable defined above to retrieve the mediaLink representing the image -->
<img ng-src=“{{mediaItem.mediaLink}}“/>
<p ng-bind="block.data.description"></p>
</div>
angular.module("umbraco").controller("customBlockController", function ($scope, mediaResource) {
//your property is called image so the following will contain the udi:
var imageUdi = $scope.block.data.image[0].mediaKey;
//the mediaResource has a getById method:
mediaResource.getById(imageUdi).then(function (media) {
console.log(media);
//set a property on the 'scope' called imageUrl for the returned media object's mediaLink
$scope.imageUrl = media.mediaLink;
});
});
angular.module("umbraco").controller("customBlockController", function ($scope, mediaResource,imageUrlGeneratorResource) {
//your property is called image so the following will contain the udi:
var imageUdi = $scope.block.data.image[0].mediaKey;
//the mediaResource has a getById method:
mediaResource.getById(imageUdi).then(function (media) {
imageUrlGeneratorResource.getCropUrl(media.mediaLink, 150, 150).then(function (cropUrl) {
console.log(cropUrl);
$scope.imageUrl = cropUrl;
});
});
});
Remove the section name="BaseRestExtensions" section
Remove the section name="FileSystemProviders" section
Remove the sectionGroup name="system.web.webPages.razor" section
Remove the <FileSystemProviders> element
Remove the BaseRestExtensions element
Remove the add key="umbracoUseMediumTrust" element
Ensure that the targetFramework="4.5" is added to the httpRuntime element
Add add key="ValidationSettings:UnobtrusiveValidationMode" value="None" to the appSettings element
/config/clientdependency.config changes
remove add name="CanvasProvider" element
/views/web.config updates
New macroscripts/web.config
config/umbracoSettings.config
Umbraco is now shipped with minimal settings but the full settings are still available
umbracoSettings is now a true ASP.NET configuration section
Remove the EnableCanvasEditing element
Remove the webservices element
Removed xsltExtensions.config
/config/applications.config and /config/trees.config have some icon paths and names updated. You need to merge the new changes into your existing config files.
/config/tinyMceConfig.config
The inlinepopups is compatible and supported in Umbraco 7. You need to remove these elements: plugin loadOnFrontend="true", inlinepopups/plugin;
The plugins element that is shipped with Umbraco 7 looks like this:
You need to merge the changes from the new tinyMceConfig file into yours. The command elements that have changed are: JustifyCenter, JustifyLeft, JustifyRight, JustifyFull, umbracomacro, umbracoembed
/config/dashboard.config
You need to merge the changes from the new dashboard.config into yours. Some of the original dashboard entries that were shipped with Umbraco 6 have been replaced or removed.
There is a new ITagService that can be used to query tags
Querying for tags in a view (front-end) can be done via the new TagQuery class which is exposed from the UmbracoHelper. For example: @Umbraco.TagQuery.GetTagsForProperty
This can be done via the appsettings.json file, environment variables, or any other .NET configuration provider (like Azure Key Vault/App Configuration). Although this setting affects how Umbraco behaves at runtime, some modes have prerequisites on how the project is built/published. Make sure to read the descriptions of each mode before changing this setting from the default BackofficeDevelopment mode, as incorrect configuration can result in your application not starting (by throwing a BootFailedException).
BackofficeDevelopment mode
The BackofficeDevelopment mode is the default behavior for Umbraco: it does not optimize Umbraco for any specific environment and does not have any prerequisites. This mode allows for rapid development (without having to recompile/rebuild your project), including all development from within the backoffice.
Development mode
The Development mode can be used when you're developing from an IDE (like Visual Studio, VS Code, or Rider) or the dotnet CLI (e.g. using dotnet watch). It is a recommended prerequisite if you want to use the Production mode in your production environment.
This mode disables in-memory ModelsBuilder generation and validates the following setting:
Umbraco:CMS:ModelsBuilder:ModelsMode is not set to InMemoryAuto.
If you want to use the generated models, use SourceCodeAuto or SourceCodeManual, which requires manually recompiling the project after the models have changed (e.g. after updating Document Types, Media Types, Member Types, or Data Types). Razor views (cshtml files) will still be automatically compiled at runtime, allowing you to quickly iterate on the rendered output from templates, (macro) partial views, and view components.
The recommended approach to enable Development mode is to update the appsettings.json file with the following settings:
Ensure your models are generated by running Umbraco and navigating to Settings > Models Builder > Generate models. You can remove the following properties from your csproj project file to enable the compilation of Razor views (which also ensures your views do not contain compilation errors and is a prerequisite for enabling Production mode):
Fix any compilation errors you might get after this, e.g. if you accidentally referenced deleted models or properties. Running the application will still show the rendered content and you're now ready to optionally enable Production mode on your production environment.
Ensure you have the <CopyRazorGenerateFilesToPublishDirectory>true</CopyRazorGenerateFilesToPublishDirectory> property set in your csproj project file, so Razor views are always copied to the publish directory. This is required by the CMS to display the contents in the backoffice, for Forms to lookup custom theme views and for Deploy to be able to compare schemas (otherwise you'll get schema mismatches).
Production mode
Use Production mode to ensure your production environment is running optimally by disabling development features and validating whether specific settings are configured to their recommended production values.
This mode disables both in-memory ModelsBuilder generation (see Development mode) and Razor (cshtml) runtime compilation. Production mode requires you to compile your views at build/publish time and enforces the following settings for optimal performance/security:
The application is built/published in Release mode (with JIT optimization enabled), e.g. using dotnet publish --configuration Release;
Umbraco:CMS:WebRouting:UmbracoApplicationUrl is set to a valid URL;
Umbraco:CMS:Global:UseHttps is enabled;
Umbraco:CMS:RuntimeMinification:CacheBuster is set to a fixed cache buster like Version or AppDomain;
Umbraco:CMS:ModelsBuilder:ModelsMode is set to Nothing.
To compile your views at build/publish time, remove the <RazorCompileOnBuild> and <RazorCompileOnPublish> properties from your project file (see the Development mode section). If you don't, Umbraco can't find the templates and will return 404 (Page Not Found) errors.
The recommended approach to enable Production mode is to update the appsettings.Production.json file (or create one) with the following settings:
Although you can still edit document types and views (if not running from the published output), changes won't be picked up until you've rebuilt your project or republished the application.
Models won't be generated by ModelsBuilder (because the mode is set to Nothing), requiring you to do all your changes while in Development mode.
As Models Builder is set to Nothing, the Models Builder dashboard is disabled in the backoffice of live environment.
Also, templates cannot be edited on live environment as runtime compilation is not enabled and is set to Production.
Also ensure the UmbracoApplicationUrl is updated to the primary URL of your production environment, as this is used when sending emails (password reset, notifications, health check results, etc.) and the keep-alive task.
Static web assets are disabled when using Production mode, following Microsoft guidance. If you are running a non-Development environment using the Production runtime mode from source (non-published output), you will need to explicitly enable this. You can add the following line of code to your Program.cs file:
This should not be used in a more typical production environment where you are hosting your application from published output.
Customize/extend runtime mode validation
Validation of the above-mentioned settings is done when determining the runtime level during startup using the new IRuntimeModeValidationService and when it fails, causes a BootFailedException to be thrown. The default implementation gets all registered IRuntimeModeValidators to do the validation, making it possible to remove default checks and/or add your own (inherit from RuntimeModeProductionValidatorBase, if you only want to validate against the production runtime mode). The following validators are added by default:
JITOptimizerValidator - Ensure the application is built/published in Release mode (with JIT optimization enabled) when in production runtime mode, e.g. using dotnet publish --configuration Release;
UmbracoApplicationUrlValidator - ensure Umbraco:CMS:WebRouting:UmbracoApplicationUrl is configured when in production runtime mode;
UseHttpsValidator - ensure Umbraco:CMS:Global:UseHttps is enabled when in production runtime mode;
RuntimeMinificationValidator - ensure Umbraco:CMS:RuntimeMinification:CacheBuster is set to a fixed cache buster like Version or AppDomain when in production runtime mode;
ModelsBuilderModeValidator - ensure Umbraco:CMS:ModelsBuilder:ModelsMode is not set to InMemoryAuto when in development runtime mode and set to Nothing when in production runtime mode.
The following example removes the default UmbracoApplicationUrlValidator and adds a new custom DisableElectionForSingleServerValidator:
In some cases, you might want to create a fallback label. This can be achieved using the following format: {{myProperty || $contentTypeName}}.
This example will show the name of the ElementType when the value of myProperty is not defined.
Useful Angular filters
As well as the default AngularJS filters, Umbraco ships with additional filters which are useful for setting the Label field of Block editors.
Filter
Description
Property type
Parameters
ncNodeName
Gets the name of a node
Umbraco node
ncRichText
Strips HTML
Richtext editor
mediaItemResolver
Retrieves a Media Item object
Media Picker
Example: mediaItemResolver
This is how you could use the filter for a Media Picker of the type Umbraco.MediaPicker3 with multiple images:
The mediaKey is a Guid like c7a4526c-6b32-4665-a047-5b3e7256d973.
For the Media Name, the same could be achieved using ncNodeName like shown below:
The ncNodeName value expects a UDI like umb://media/c7a4526c6b324665a0475b3e7256d973.
Custom filters
If the filters do not suit your needs, you can create custom filters by creating a plugin in App_Plugins and adding a filter module. You can see an example below:
If you do not have an /App_Plugins folder, you can create it at the root of your project.
Create a plugin by adding a folder inside App_Plugins called MyFilters
Inside the MyFilters folder add a package.manifest file containing:
Add a myFilter.filter.js file containing:
Implement a block editor of your choice. When adding a label add {{ myFilter }} which is the property alias of the element type. The myFilter property has a textstring editor. When adding the content, the block editor will then display the data that you input.
Special variables
Variable
Description
$index
The 1-based index of this block item in the current block list
$contentTypeName
The name of the Element Type used for the Block
$settings
Provides access to the settings model for the block (if configured)
$layout
Provides access to the layout model for the block (columnSpan and rowSpan)
) if the
Pick multiple items
setting is enabled.
A single MediaWithCrops item if the Pick multiple items setting is disabled.
Data Type Definition Example
Media Picker Data Type Definition
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.
Ignorer 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
Multiple enabled without Modelsbuilder 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 Modelsbuilder
Multiple disabled without Modelsbuilder
Multiple disabled with Modelsbuilder
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 Content Service.
The following sample will update a single image in a Media Picker.
The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
This document assumes that you have a fair amount of knowledge about:
Umbraco
IIS 10+
Networking & DNS
Windows Server
.NET5+
It is highly recommended that you setup your staging environment to also be load balanced so that you can run all of your testing on a similar environment to your live environment.
Design
These instructions make the following assumptions:
All web servers can communicate with the database where Umbraco data is stored
You are running Umbraco 9.0.0 or above
You will designate a single server to be the backoffice server for which your editors will log into for editing content. Umbraco will not work correctly if the backoffice is behind the load balancer.
There are three design alternatives you can use to effectively load balance servers:
Each server hosts copies of the load balanced website files and a file replication service is running to ensure that all files on all servers are up to date
The load balanced website files are located on a centralized file share (SAN/NAS/Clustered File Server/Network Share)
You will need a load balancer to do your load balancing.
How Umbraco load balancing works
In order to understand how to host your site it is best to understand how Umbraco's flexible load balancing works.
The following diagram shows the data flow/communication between each item in the environment:
Umbraco flexible load balancing diagram
The process is as follows:
Administrators and editors create, update, delete data/content on the backoffice server
These events are converted into data structures called "instructions" and are stored in the database in a queue
Each front-end server checks to see if there are any outstanding instructions it hasn't processed yet
When a front-end server detects that there are pending instructions, it downloads them and processes them and in turn updates it's cache, cache files and indexes on its own file system
There can be a delay between content updates and a front-end server's refreshing, this is expected and normal behaviour.
Scheduling and server role election
Although there is a backoffice server designated for administration, by default this is not explicitly set as the "Scheduling server". In Umbraco there can only be a single scheduling server which performs the following 3 things:
Keep alive service - to ensure scheduled publishing occurs
Scheduled tasks - to initiate any configured scheduled tasks
Scheduled publishing - to initiate any scheduled publishing for documents
Automatic Server Role Election
Umbraco will automatically elect a "Scheduling server" to perform the above services. This means that all of the servers will need to be able to resolve the URL of either: itself, the Backoffice server, the internal load balancer, or the public address.
There are two server roles:
SchedulingPublisher - Usually this is the backoffice instance.
Subscriber - These are the scalable front-end instances - not recommended to be used for backoffice access.
These new terms replace 'Master and Replica', in Umbraco versions 7 and 8.
Each instance will be allocated a role by the automatic server role election process, but they can also be set explicitly (recommended)
For example, In the following diagram the node f02.mysite.local is the elected "Scheduling server". In order for scheduling to work it needs to be able to send requests to itself, the Backoffice server, the internal load balancer or the public address. The address used by the "Scheduling server" is called the "umbracoApplicationUrl".
Umbraco flexible load balancing diagram
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:
File Replication - 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
Centralized file share - The load balanced website files are located on a centralized file share (SAN/NAS/Clustered File Server/Network Share)
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 official docs 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 https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed 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.
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 General Upgrades 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.
Now the feed is added as a source named Umbraco Nightly.
Option 2: Using Visual Studio
To add the nightly feed using Visual Studio:
Open Visual Studio.
Go to Tools > NuGet Package Manager > Package Manager Settings.
Package Manager Settings
The Options window open.
Select the Package Sources option in the NuGet Package Manager section.
Click the + icon.
A new Package source will be added automatically and highlighted.
Enter the desired name for the feed in the Name field.
Enter the link https://www.myget.org/F/umbraconightly/api/v3/index.json into the Source field.
Click OK.
Register the nightly feed
Now the feed is added as a source named Umbraco Nightly.
Option 3: Using Rider
To add the nightly feed using Rider:
Open Rider.
Go to View > Tool Windows > NuGet.
Go to Sources tab.
Choose the C:\Users\Úmbraco\AppData\Roaming\NuGet\NuGet.Config to add the feed globally.
Click the green + button in the New Feed field.
Open the new feed menu
The New feed dialog opens.
Enter the desired name in the Name field.
Enter https://www.myget.org/F/umbraconightly/api/v3/index.json in the URL field.
Leave the User, Password fields empty, and the Enabled checkbox ticked.
Adding the feed
Click OK.
Now the feed is added as a source named Umbraco Nightly.
Finding the latest nightly version
In the previous steps, we've added the feed and are now ready to install the nightly build.
However, which version should we install? This is, in particular, an issue if we want to create a new site using the dotnet template. The dotnet command does not allow us to use wildcard characters to install the newest version.
Using IDE, we can see a list of available versions in both Visual Studio and Rider. We can then use that version to install the template.
Here we're going to assume that you want to create a brand new site with the dotnet template. The approach is the same if you're updating an existing site. You'll click the Update button for the Umbraco.Cms package instead of installing the template through the terminal.
Let's look at how we can find the latest version of the nightly build:
A grid editor is the component responsible for getting data into the grid - that could be a text field or a media picker. They're built in the same way as a property editor thus consists of 3 parts:
.html view file
.js controller
.cshtml server side renderer
The view is what the editor sees, the controller handles how it acts and the cshtml determines how the entered data is rendered in the template.
Default configuration
Grid editors are specified in /config/grid.editors.config.js. By default this file doesn't exist, so before you attempt to extend the configuration, make sure to create it first.
The default items in the config file are as follows below. It is recommended that you copy all of editors below before you add more, in case some of them are already in use.
If you don't add the editors below to this config file then they won't be available in your grid editors, even if there are existing grid datatypes already using these editors.
You will need to restart your site before any new customizations become available to use.
Default Grid editors
Grid editor are created in the JSON format and each editor is an object like so:
Custom Grid editors
You can customize the built-in editors to tailor the grid to your need.
package.manifest
It is recommended that you define custom editors in a package.manifest file (not in the config file described above) like so:
While the root JSON element of /config/grid.editors.config.js is an array of grid editors, package.manifest files start with a JSON object with a number of different properties - one of them being gridEditors.
The package manifest should be placed in a folder inside the /App_Plugins/ folder - for instance /App_Plugins/{YourPackageName}/package.manifest. You can define as many grid editors you want and it can be done over multiple manifests so you can use grid editors from packages etc. With the package.manifest file in place, Umbraco will automatically pick it up during startup.
You can read more about package.manifest files in general at the page.
Grid editor configuration
For a grid editor, the required values are:
name: The name of the editor
alias: Unique alias of the editor
icon
You can also add a name template for generating grid item labels using the syntax {{ value.propertyAlias }}.
If you would like to include the index position in the label, you can use {{$index}}.
The built-in views you can use are:
textstring
rte
embed
In most cases you will either use the textstring or media view, or built your own from scratch. The textstring and media editors come with some additional configuration to make it quick to customise these.
Sample textstring config
In this sample, the config.style value is applied to the editor so users can see an accurate preview in the backoffice. This will be applied as as inline styling to the textarea in the backoffice.
The config.markup is the string rendered server side in your template. #value#will be replaced with the actual value
Sample media config
In this sample config.size will resize the image according to height and width. The above example will result in a rendered image that is 200x200 pixels no matter the size of the uploaded image. If the ratio of the size differs from the uploaded image it is possible to set a focal point that determines how the image should be cropped.
Sample macro config
In this sample a new option will appear in the Choose type of content with direct access to the macro.
Upgrade your project
This is the guide for upgrading existing installations in general.
In this article, you will find everything you need to upgrade your Umbraco CMS project.
You will find instructions on how to upgrade to a new minor or major version as well as how to run upgrades unattended.
The following lists a few things to be aware of before initiating an upgrade of your Umbraco CMS project.
Sometimes there are exceptions to general upgrade guidelines. These are listed in the . Be sure to read this article before moving on.
Check if your setup meets the for the new versions you will be upgrading your project to.
Things may go wrong for different reasons. Be sure to ALWAYS keep a backup of both your site's files and the database. This way you can always return to a version that you know works.
It is necessary to run the upgrade installer on each environment of your Umbraco site. This means that you need to repeat the steps below on each of your environments in order to complete the upgrade.
Legacy Umbraco
The steps outlined in this article apply to modern Umbraco from version 10 and later versions.
Are you upgrading to a minor for Umbraco 6, 7, or 8 you can find the appropriate guide below:
Upgrade to a new Major
You can upgrade to a new major of Umbraco CMS directly by using NuGet.
Switching to a new major of Umbraco CMS also means switching to a new .NET version. You need to make sure that any packages used on your site are compatible with this version before upgrading.
The package compatibility can be checked on the package's download page. Locate the Project compatibility area and select View details to check version-specific compatibility.
Choose the correct .NET version
Use the table below to determine which .NET version to upgrade to when going through the steps below.
CMS version
.NET version
Upgrade your project using Visual Studio
It's recommended that you upgrade the site offline and test the upgrade fully before deploying it to the production environment.
Stop your site in IIS to prevent any changes from being made while you are upgrading.
Open your Umbraco project in Visual Studio.
Right-click on the project name in the Solution Explorer and select Properties.
If you have other packages installed such as Umbraco Forms, then before upgrading Umbraco.CMS you will need to upgrade the packages first. Consult the if relevant.
Make sure that your connection string has TrustServerCertificate=True in order to complete the upgrade successfully:
Restart your site in IIS, then build and run your project to finish the installation.
In Umbraco 13, we have moved to using the .
If you have added custom code to the startup.cs file, we recommend moving the code into a Composer after upgrading.
If your database experiences timeout issues after an upgrade, it might be due to 'startupTimeLimit' configuration.
To fix the issue, try increasing the in the web.config file. Additionally, you can set the value in the in the appsettings.json file.
Upgrade to a new Minor
NuGet installs the latest version of the package when you use the dotnet add package command unless you specify a package version:
Add a package reference to your project by executing the dotnet add package Umbraco.Cms command in the directory that contains your project file.
Run dotnet restore to install the package.
For v9: If you are using SQL CE in your project you will need to run dotnet add package Umbraco.Cms.SqlCe --version <VERSION> before running the dotnet restore command.
From v10, SQL CE has been replaced with SQLite so a dotnet restore should be sufficient. If this is not working then you will need to run dotnet add package Umbraco.Cms.Persistence.Sqlite --version <VERSION> and then dotnet restore.
When the command completes, open the .csproj file to make sure the package reference was updated:
Run an unattended upgrade
When upgrading your Umbraco project, it is possible to enable the upgrade to run unattended. This means that you will not need to run through the installation wizard when upgrading.
Below you will find the steps you need to take in order to upgrade your project unattended.
Are you running a load balanced setup with multiple servers and environments?
Check out the section about .
Enable the unattended upgrade feature
Add the Umbraco:Cms:Unattended:UpgradeUnattended configuration key.
Set the value of the key to true.
Run the upgrade
With the correct configuration applied, the project will be upgraded on the next boot.
Boot order
The Runtime level will use Run instead of Upgrade to allow the website to continue to boot up directly after the migration is run. This happens instead of initiating the otherwise required restart.
The upgrade is run after Composers but before Components and the UmbracoApplicationStartingNotification. This is because the migration requires services that are registered in Composers and Components require that Umbraco and the database are ready.
Unattended upgrades in a load balanced setup
Follow the steps outlined below to use unattended upgrades in a load balanced setup.
Upgrade Umbraco via NuGet ()
Deploy to all environments.
Set the Umbraco:CMS:Unattended:UpgradeUnattended configuration key to true for the Main server only
Image Cropper
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 .
Login
In this article you can learn the various ways of customizing the Umbraco backoffice login screen and form.
To access the backoffice, you will need to login. You can do this by adding /umbraco at the end of your website URL, for example http://mywebsite.com/umbraco.
You will be presented with a login form similar to this:
The login screen contains a Greeting, Email, Password field and optionally a Forgotten password link
Below, you will find instructions on how to customize the login screen.
Could not load type umbraco.BusinessLogic.Utils.TypeFinder from assembly businesslogic, Version=1.0.5031.21336, Culture=neutral, PublicKeyToken=null.
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;
}
}
angular.module("umbraco.filters").filter("myFilter", function () {
return function (input, parameter1, parameter2, etc) {
// Apply any custom logic to modify the output value and return a string
return `My filter says: "${input}"`;
}
});
@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" />
}
}
@{
var typedMultiMediaPicker = Model.Medias;
foreach (var entry in typedMultiMediaPicker)
{
<img src="@entry.MediaUrl()" style="width:200px" />
}
}
@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 Services;
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Get the 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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
// Set the value of the property with alias 'featuredBanner'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.FeaturedBanner).Alias, udi.ToString());
}
using Azure;
using Azure.Data.Tables;
using Serilog.Events;
using Serilog.Formatting.Compact.Reader;
using Serilog.Sinks.AzureTableStorage;
using Umbraco.Cms.Core.Logging.Viewer;
using ITableEntity = Azure.Data.Tables.ITableEntity;
namespace My.Website;
public class AzureTableLogViewer : SerilogLogViewerSourceBase
{
public AzureTableLogViewer(ILogViewerConfig logViewerConfig, Serilog.ILogger serilogLog, ILogLevelLoader logLevelLoader)
: base(logViewerConfig, logLevelLoader, serilogLog)
{
}
public override bool CanHandleLargeLogs => true;
// This method will not be called - as we have indicated that this 'CanHandleLargeLogs'
public override bool CheckCanOpenLogs(LogTimePeriod logTimePeriod) => throw new NotImplementedException();
protected override IReadOnlyList<LogEvent> GetLogs(LogTimePeriod logTimePeriod, ILogFilter filter, int skip, int take)
{
//Replace ACCOUNT_NAME and KEY with your actual Azure Storage Account details. The "Logs" parameter refers to the table name where logs will be stored and retrieved from.
var client =
new TableClient(
"DefaultEndpointsProtocol=https;AccountName=ACCOUNT_NAME;AccountKey=KEY;EndpointSuffix=core.windows.net",
"Logs");
// Table storage does not support skip, only take, so the best we can do is to not fetch more entities than we need in total.
// See: https://learn.microsoft.com/en-us/rest/api/storageservices/writing-linq-queries-against-the-table-service#returning-the-top-n-entities for more info.
var requiredEntities = skip + take;
IEnumerable<AzureTableLogEntity> results = client.Query<AzureTableLogEntity>().Take(requiredEntities);
return results
.Skip(skip)
.Take(take)
.Select(x => LogEventReader.ReadFromString(x.Data))
// Filter by timestamp to avoid retrieving all logs from the table, preventing memory and performance issues
.Where(evt => evt.Timestamp >= logTimePeriod.StartTime.Date &&
evt.Timestamp <= logTimePeriod.EndTime.Date.AddDays(1).AddSeconds(-1))
.Where(filter.TakeLogEvent)
.ToList();
}
public override IReadOnlyList<SavedLogSearch>? GetSavedSearches()
{
//This method is optional. If you store saved searches in Azure Table Storage, implement fetching logic here.
return base.GetSavedSearches();
}
public override IReadOnlyList<SavedLogSearch>? AddSavedSearch(string? name, string? query)
{
//This method is optional. If you store saved searches in Azure Table Storage, implement adding logic here.
return base.AddSavedSearch(name, query);
}
public override IReadOnlyList<SavedLogSearch>? DeleteSavedSearch(string? name, string? query)
{
//This method is optional. If you store saved searches in Azure Table Storage, implement deleting logic here.
return base.DeleteSavedSearch(name, query);
}
}
public class AzureTableLogEntity : LogEventEntity, ITableEntity
{
public DateTimeOffset? Timestamp { get; set; }
public ETag ETag { get; set; }
}
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Infrastructure.DependencyInjection;
namespace My.Website;
public class LogViewerSavedSearches : IComposer
{
public void Compose(IUmbracoBuilder builder) => builder.SetLogViewer<AzureTableLogViewer>();
}
wordwise: boolean to indicate whether to truncate a string mid-word or not
max: maximum length of the string
tail (optional): string to indicate a truncated string, "…" by default
separator: string used to join values together, e.g. ", "
prop (optional): string key indicating which property to join when used on an array of objects
How to use Language Variants in Umbraco
Learn how to use the Log Viewer to read and understand logs for your Umbraco CMS website.
,
mceImage
,
subscript
,
superscript
,
styleselect
Remove the command: mceSpellCheck
: Icon shown to the editor, uses same icon classes as the rest of
view the view defines the editor used to enter a value. By default Umbraco will look in /umbraco/views/propertyeditors/grid/editors for a html view to use - but you can pass in your own path
If your editor links to a content, media or member node, you can use the Angular filter {{ value.udi | ncNodeName }} to show the node name rather than the node ID.
If your editor is a rich text editor, you can use the Angular filter {{ value | ncRichText }} to show the unformatted text.
Before upgrading to a new major version, check if the packages you're using are compatible with the version you're upgrading to. On the package's download page, in the Project compatibility area, click View details to check version-specific compatibility.
Select the .NET version from the Target Framework drop-down.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
Go to the Installed tab in the NuGet Package manager.
Upgrade Umbraco.Cms.
a. Select the correct version from the Version drop-down.
b. Click Install to upgrade your project.
.
Boot the Main server and the upgrade will run automatically.
Wait for the upgrade to complete.
Boot the Read-Only servers and make sure they do not show the “upgrade required” screen.
You can add, edit & delete crop presets the cropper UI can use.
Data Type Definition Example
Image Cropper Data Type Definition
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.
Image Cropper Upload
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.
Image Cropper Focal point
Crop and resize
The editor can fit the crop to the image to ensure that the image is presented as intended.
Image Cropper Crop
Powered by ImageSharp.Web
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 the official ImageSharp documentation.
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 Content Service.
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 format command.
The login screen features a greeting which you can personalize by overriding the existing language translation keys. To do this, create a 'user' translation file for the default language of your Umbraco site, (usually en-US) to override the greetings. For en-US, you'd create a file called: en_us.user.xml in the directory ~/config/lang/. Then take the relevant keys (listed below) and add them to your ~/config/lang/en_us.user.xml file, and update the greetings as necessary.
Note: the config directory needs to be in the root of your project (not the wwwroot).
Before the changes takes place you will need to restart the site.
You can customize other text on the login screen as well. First, grab the default values and keys from the en_us.xml in the Umbraco CMS GitHub repository. Thereafter, copy the ones you want to translate into the ~/config/lang/en_us.user.xml file.
Password reset
The Forgotten password? link allows your backoffice users to reset their password. To use this feature, you will need to add the following key to the Umbraco.Cms.Security section in the appsettings.json file:
Set it to true to enable the password reset feature, and false to disable the feature.
You will also need to configure a Simple Mail Transfer Protocol (SMTP) server in your appsettings.json file. When you get a successful result on the SMTP configuration when running a health check in the backoffice, you are good to go!
An example:
Custom background image and logo
It is possible to customize the background image and the logo for the backoffice login screen by adding the "Content" section in the appsettings.json file:
The LoginBackgroundImage, LoginLogoImage, and LoginLogoImageAlternative are referenced from the /wwwroot/umbraco/ folder.
The LoginLogoImage is displayed on top of the LoginBackgroundImage and the LoginLogoImageAlternative is displayed when the LoginLogoImage is not available, for example on small resolutions.
Custom CSS
You can also customize the login screen by adding a custom CSS file. To do this, you will need to add a new file inside the ~/App_Plugins folder, for example ~/App_Plugins/MyCustomLoginScreen/my-custom-login-screen.css.
You can then add your custom CSS to the file:
This will change the color of the SVG graphics (curves) shown on the login screen. You can also hide the curves by adding the following CSS:
Load the custom CSS file
To tell Umbraco about your custom CSS file, you will need to add a package.manifest file. The package.manifest file should look like this:
Custom CSS properties reference
The following CSS properties are available for customization:
CSS Property
Description
Default Value
--umb-login-background
The background of the layout
#f4f4f4
--umb-login-primary-color
The color of the headline
#283a97
--umb-login-text-color
The color of the text
#000
--umb-login-header-font-size
The font-size of the headline
The CSS custom properties may change in future versions of Umbraco. You can always find the latest values in the login layout element in the Umbraco CMS GitHub repository.
Login screen
Multinode Treepicker
Alias: Umbraco.MultiNodeTreePicker
Returns: IEnumerable<IPublishedContent>
Settings
The Multinode Treepicker allows you to configure the type of tree to render and what part of the tree that should be rendered. For content it allows you to select a dynamic root node based on the current document using the multinode tree picker.
Node type
Set the type of node, the root node of the tree, or query for the root node.
For querying content you can specify a dynamic root:
When you specify the dynamic root, you are able to navigate the tree relative to a node.
First you have to specify a origin, from where the query will start.
You have the following options:
Root
The root is the first level item of the current nodes subtree.
Parent
Often an origin is a good dynamic root. It is also possible to execute multiple steps from the origin to navigate the tree to find another root.
You have the following options:
Nearest Ancestor or Self
Finds the nearest ancestor or the item itself, that fits with one of the configured document types.
Furthest Ancestor or Self
Each query step takes the output from the last step (or the origin) as input.
Adding a custom query step
Custom query steps can be used to solve some specific use cases.
To add a custom query step you need to append it to the existing query steps. This can be done from a composer:
The implementation of a query step takes in 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.
The code required to create a custom query step is like in the below example.
You can inject dependencies into the constructor. Some interesting dependencies could be custom repositories, or the IVariationContextAccessor, if you wanna use the current culture.
The ExecuteAsync method gets a collection of content keys from the last executed query step or the origin. It has to return a new collection of content keys.
Filter out items with type
Allow or disallow tree nodes with a certain content type alias.
Enter typeAlias,altTypeAlias to only allow selecting nodes with those alias'. Enter !typeAlias,altTypeAlias to only allow selecting nodes not with those alias'.
Minimum/maximum number of items
Set a limit on the number of items allowed to be selected.
Data Type Definition Example
Content Example
Consider the following tree structure where Document Type alias is presented in square brackets.
Codegarden
2023 [year]
Talks [talks]
Consider configuring a picker on the talk Document Type to choose a stage of the talk. Here you only want to present the stages for the actual year. To do this, you need to choose the parent as origin.
Imagine being on the Umbraco anno MMXXIII node. This means the collection of content keys passed into the first query step will only contain the Talks content node.
First you can then query for the nearest ancestors of type year. This means the 2023 will be returned.
Next, you can query for the nearest descendants of type stages.
When opening the picker on the Umbraco anno MMXXIII node, it will now show the children of the node on path Codegarden => 2023 => Stages.
MVC View Example
Without Modelsbuilder
With Modelsbuilder
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 example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.
Although the use of a GUID is preferable, you can also use the numeric ID to get the page:
If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:
Block List
Alias: Umbraco.BlockList
Returns: IEnumerable<BlockListItem>
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<>
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 can use AngularJS template string syntax to display values of properties.
Custom view - Overwrite the AngularJS view for the block presentation in the Content editor. Use this to make a more visual presentation of the block or even make your own editing experience by adding your own AngularJS controller to the view.
Custom stylesheet - Pick your own stylesheet to be used for this block in the Content editor. By adding a stylesheet the styling of this block will become scoped. Meaning that backoffice styles are no longer present for the view of 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.
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.
Migrate content to Umbraco 8
This guide will show you how to migrate the content from your Umbraco 7 site to a site running Umbraco 8.
Umbraco 8 contains a lot of breaking changes and a lot of code has been cleaned up compared to Umbraco 7. Due to this, it will not be possible to do a direct upgrade from Umbraco 7 to Umbraco 8. You need to migrate your content from your Umbraco 7 site into your Umbraco 8 site and then recreate the rest in the new version.
A content migration tool has been implemented in Umbraco 8.1.0, to help you with the transition.
In this guide you can read more about the tool, its limitations, and how to use it in practice.
@if (Model.Photo is not null)
{
<img src="@Url.GetCropUrl(Model.Photo, height: 300, width: 400)" alt="@Model.Photo.Name" />
}
@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 Newtonsoft.Json;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.PropertyEditors.ValueConverters;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Web.Common.Controllers;
using Umbraco.Extensions;
namespace Umbraco.Docs.Samples.Web.Property_Editors_Add_Values;
public class CreateImageCropperValuesController : UmbracoApiController
{
private readonly IContentService _contentService;
private readonly IMediaService _mediaService;
private readonly MediaUrlGeneratorCollection _mediaUrlGeneratorCollection;
public CreateImageCropperValuesController(
IContentService contentService,
IMediaService mediaService,
MediaUrlGeneratorCollection mediaUrlGeneratorCollection)
{
_contentService = contentService;
_mediaService = mediaService;
_mediaUrlGeneratorCollection = mediaUrlGeneratorCollection;
}
// /Umbraco/Api/CreateImageCropperValues/CreateImageCropperValues
[HttpPost]
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 = JsonConvert.SerializeObject(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 = (ContentModels.MyElementTypeAliasOfSettings)Model.Settings;
}
// Output the value of field with alias 'heading' from the Element Type selected as Content section
<h1>@content.Value("heading")</h1>
// Output the value of field with alias 'heading' from the Element Type selected as Content section
<h1>@content.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>
}
}
The parent is the nearest ancestor of the current node.
Current
The current node. Be aware a picker that uses the current node, cannot pick anything when the current node is created, because it do not have any children.
Site
The nearest ancestor of the current node that has a domain assigned.
Specific node
A specific node that you have to choose in the tree
Finds the furthest ancestor or the item itself, that fits with one of the configured document types.
Nearest Descendant or Self
Finds the nearest descendant or the item itself, that fits with one of the configured document types.
Furthest Descendant or Self
Finds the furthest descendant or the item itself, that fits with one of the configured document types.
Custom
Execute a custom query step by specifying the name. This requires custom code to add the new query step.
In the following section, you can learn more about the limitations of migrating content from Umbraco 7 to Umbraco 8.
Versions supported
The content migration tool is a database migration, which is made for the database schema of Umbraco 7.14+. This means that in order to do the migration you need to ensure your Umbraco 7 site is running at least Umbraco 7.14.
Database types supported
Umbraco 8 does not support MySQL databases. This means that the migration will not work when moving from an Umbraco 7 site using MySQL to Umbraco 8 on SQL Server
The database types that are supported are SQL Server and SQL CE.
Known issues
Feedback from user testing has shown that some databases are harder to migrate than others.
A migration was introduced in Umbraco 8.6 which can break the migration process. See Issue #7914 for more details.
There are two ways to work around this issue:
Migrate to version 8.5 as a first step and then post-migration, carry out a normal Umbraco upgrade to the latest version of Umbraco 8, or
Install the following community Nuget Package: into your Umbraco 8 project before running the migration (no configuration required). This package was created by Umbraco Gold Partner and patches the migration process so you can migrate directly from the latest Umbraco 7 to Umbraco 8.6+ without encountering the above issue. .
Third party property editors
The migration will transform the data stored in third party editors as well. However, it will be stored as it was in Umbraco 7. If the structure has changed or the property editor doesn't exist, you will still be able to find the data in the database. It will, however, not be available in the backoffice.
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.
What will happen
When the migrations are running, Umbraco will go through your entire Umbraco 7 database and update it to the format required for Umbraco 8. The schema will be remodeled and transformed into the correct format and your existing compatible data will be transformed to fit with Umbraco 8.
These migrations will be running directly on your database. They are transforming schema and data - not transferring. Therefore always ensure that you have a backup before attempting to do this. In case something goes wrong, you will be able to rollback and try again.
It is highly recommended to clean up your site before running this as it will be quicker.
Empty Content recycle bin
Empty Media recycle bin
Clean up the database version history (can be done with a script or a package like Unversion)
How it works
In the following guide we will migrate the content of an Umbraco 7.13.1 site to Umbraco 8.1.0.
Step 1: Upgrading to 7.14+
Before the content migration can start the site has to run Umbraco 7.14+. Make sure to always take a backup of the database before doing an upgrade, and then check the version specific upgrade instructions.
The site in this example is an Umbraco 7.13.1 site, and we will use Nuget to update it.
When upgrading an old website, check if you are using obsolete properties in your Data Types. These should be changed to their updated counterparts. The migration will fail if you are still using obsolete properties.
The updated properties are:
Content Picker
Media Picker
Member Picker
Multinode Treepicker
Folder Browser
Related Links
You can see if your site is using the obsolete properties from the (Obsolete) prefix in their name.
Install the Pre-migration health checks plugin, and run it health check from the Developer section of the backoffice. This is done to identify and resolve some common database schema issues before migration.
Once it is upgraded and you have verified everything is working, move on to the next step.
Step 2: Migrating content to Umbraco 8
The first thing to do is to spin up a fresh new Umbraco 8.1+ site. Make sure everything works and that no content is there.
Fresh 8.1 site
If you have customized the UsersMembershipProvider on your Umbraco 7 site you need to copy that over to the 8.1 web.config as well. Additionally you need to update the type attribute to be type="Umbraco.Web.Security.Providers.UsersMembershipProvider, Umbraco.Web".
This also includes the attribute useLegacyEncoding value. Make sure that this setting is copied into your new Umbraco 8 site, as it is needed in order to log in.
Take a backup of your database from the Umbraco 7.14 site. Take the information for the backup database and add that to the connectionstring for the Umbraco 8.1 site. If you are running SQL CE, you will have to copy the database over to the new site as well.
Once the connectionstring is set, the final step is to change the Umbraco version number in the web.config on the Umbraco 8.1 site. Chang it to 7.14.0. This will indicate that there is an upgrade pending and it needs to run the migration.
Set Umbraco version in the web.config
The version will be set to 8.1.0, and you need to change it to the version you are currently migrating from.
When you start the site it will ask you to login and then show you this screen:
Upgrade database to 8.1
From here, the automatic migration will take over, and after a little bit you can log in and see your content:
Content is on 8.1
Please be aware that this is a content migration. If you go to the frontend after following these steps, it will throw errors.
At this point you will have the content but nothing else.
Step 3: Files migration
Before moving on to this step, make sure that the Umbraco 8 project is no longer running.
The following files/folders need to be copied into the Umbraco 8 project:
~/Views - do not overwrite the default Macro and Partial View Macro files, unless changes have been made to these.
~/Media
Any files/folders related to Stylesheets and JavaScripts.
Any custom files/folders the Umbraco 7 project uses, that aren't in the ~/Config or ~/bin.
~/App_Data/UmbracoForms - in the case Umbraco Forms was used on the Umbraco 7 site.
Merge the configuration files carefully to ensure any custom settings are migrated while none of the default configurations for Umbraco 8 is overwritten.
You'll have to revisit all templates and custom implementations to get the site up and running, as all markup is still Umbraco 7-specific.
Are you planning on continuing the migration to the latest version on Umbraco CMS?
Then you can skip the step to revisit the template files and custom implementation. We highly recommend waiting with this step until you've reached the latest version.
As you are updating your template files and custom implementation, you should also verify your configuration files and settings.
Umbraco 8 contains a few changes regarding the Sections in the Umbraco Backoffice. Because of this, you should also check your User Groups and make sure they have access to the appropriate sections.
Learn how to work with different types of Media content on your Umbraco website.
Media in Umbraco CMS is handled the same way as content. You define Media Types that act as a base for media items. The following default Media Types are available:
Article - used for uploading and storing documents.
Audio - used for uploading and storing digital audio files.
public class CustomQueryStepComposer : IComposer
{
public void Compose(IUmbracoBuilder builder)
{
builder.DynamicRootSteps().Append<MyCustomDynamicRootQueryStep>();
}
}
public class CustomQueryStepComposer : IComposer
{
public void Compose(IUmbracoBuilder builder)
{
builder.DynamicRootSteps().Append<MyCustomDynamicRootQueryStep>();
}
}
public class MyCustomDynamicRootQueryStep : IDynamicRootQueryStep
{
private readonly IMyCustomRepository _myCustomRepository;
public MyCustomDynamicRootQueryStep(IMyCustomRepository myCustomRepository)
{
_myCustomRepository = myCustomRepository;
}
public async Task<Attempt<ICollection<Guid>>> ExecuteAsync(ICollection<Guid> origins, DynamicRootQueryStep filter)
{
if (filter.Alias != "MyCustom") // This is the string you will have to write in the UI
{
return Attempt<ICollection<Guid>>.Fail();
}
if (origins.Any() is false)
{
return Attempt<ICollection<Guid>>.Succeed(Array.Empty<Guid>());
}
// TODO replace with your own logic
var result = await _myCustomRepository.GetWhateverIWantAsync(origins);
return Attempt<ICollection<Guid>>.Succeed(result);
}
}
@{
var typedMultiNodeTreePicker = Model.Value<IEnumerable<IPublishedContent>>("featuredArticles");
if (typedMultiNodeTreePicker != null) {
foreach (var item in typedMultiNodeTreePicker)
{
<p>@item.Name</p>
}
}
@{
var typedMultiNodeTreePicker = Model.FeaturedArticles;
foreach (var item in typedMultiNodeTreePicker)
{
<p>@item.Name</p>
}
}
@inject IContentService Services;
@using Umbraco.Cms.Core;
@using Umbraco.Cms.Core.Services
@{
// Get access to ContentService
var contentService = Services;
// Create a variable for the GUID of the page you want to update
var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");
// Get the page using the GUID you've defined
var content = contentService.GetById(guid); // ID of your page
// Get the pages you want to assign to the Multinode Treepicker
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);
}
@{
// Get the page using it's id
var content = contentService.GetById(1234);
}
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;
@{
// Set the value of the property with alias 'featuredArticles'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor ,x => x.FeaturedArticles).Alias, string.Join(",", udis));
}
[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>();
}
}
File - used for uploading and storing different types of files in the Media section.
Folder - a container for organizing media items in the Media section tree.
Image - used for uploading and storing images.
Vector Graphics (SVG) - used for uploading and storing Scalable Vector Graphics (SVG) files which are text files containing source code to draw the desired image.
Video - used for uploading and storing video files.
The default Media Types aim to cover most needs for media on a website. You do not need to define your Media Types to start using the Media section. The tools for organizing and uploading the media are already in place.
If you have upgraded from an older version than 8.14 the Media Types listed above are not added automatically. You can add those types manually yourselves by following the steps below 'Creating a new Media Type'. On the default media types page, you will find a detailed overview of all Media Types.
From the Media section in the Umbraco backoffice, you can add new media items by following either of the approaches defined below:
Use the Create dialog to create a new Media item in the Media section
The Media item will be created based on the type you choose.
Upload the image or file, give the Media item a name, and click Save.
Upload Media - Create Button
Use the Drag and drop feature to add your files to the Media section.
Umbraco will automatically detect the Media Type and create the Media item.
You can drop entire folder structures to recreate that same structure in the Media section.
Upload Media - Media section
Add media through the Content section
New media items can be added to your site without interrupting the content creation flow. This can be done following either of the two approaches outlined below.
Drag and drop the image(s) from your file explorer directly into the Media Picker property on the Content page.
Images added this way is automatically added to the user's start node in the Media section of the Umbraco backoffice.
Drag and drop images directly into the content
Select the "+" icon to open the "Select media" dialog where you can add images from your file explorer directly or using drag and drop.
Add images from the "Select media" dialog
Creating a folder
It is always a good idea to start by creating a folder for your media items. It can be a good idea to align these folders with the content on your website. This will give the editors a better overview of the files and enable them to upload media items in the correct place.
Follow these steps to create a folder in the Media section:
Go to the Media section.
Select ... next to Media.
Alternatively, you can right-click the Media node and select Create.
Select Folder.
Enter a name for the folder and select Save in the bottom-right corner.
Media Type properties
The Image Media Type has 5 properties: Upload Image, Width, Height, Size, and Type. These are populated once the image is uploaded. The properties can be viewed in the Media section and accessed in your Templates.
Except for the Folder Media Type, the other Media Types have 3 properties: Upload Image, Type, and Size.
The default view for the Media section is a card view that lets you preview the different files that have been uploaded.
Media Section - Cardview
By selecting multiple media items it is possible to perform bulk operations like moving or deleting the items.
To edit properties on a single media item, click the name of the item, which you will see once you hover over the item.
Edit media item
From the top-right corner of the Media section, you can toggle between list and grid view. There is also an option to search for the items in the Media section.
You can switch to a list view by selecting the view toggle next to the search field and selecting the list view.
Media Section - List view
Using media items in the Content section
By adding a Media Picker property to a Document Type the editor will have the ability to select media items when creating content.
Creating a Media Type
You can create custom Media Types and control the structure of the Media tree as you would with Document Types. This means you can store information that is specific to the media on the item itself.
Video tutorial
A Media Type is created in the Settings section using the Media Type editor.
Go to the Settings section.
Click ... next to Media Types (or right-click the Media Types node).
Choose New Media Type.
Name the new Media Type Employee Image.
Choose an icon by selecting the icon left of the name field.
You will now see the Media Type editor. It is similar to the editor used for creating Document Types.
Creating a Media Type
Having different folders for different Media Types makes it possible to restrict where media items can be created and added. Only allowing PDF uploads in a certain folder and employee images in another make it easier to keep the Media section organized.
Adding groups
Before we start adding properties to the Media Type we need to add a group to put these in.
Click on Add group.
Call the group Image.
Adding properties
We need to add the same properties as on the default Image Media Type. These are:
umbracoFile
umbracoWidth
umbracoHeight
umbracoBytes
umbracoExtension
Follow the steps outlined below to add the properties to the Media Type:
Click Add property.
Name it Upload image.
Change the alias to umbracoFile.
Click Add editor.
Search for cropper and choose Image cropper under Create new.
Rename the editor Employee Image Cropper.
Add two new crops called Thumbnail (200px x 350px) and wideThumbnail (350px x 200px).
Defining crops
Name the remaining four properties Width, Height, Size, and Type, and give them the aliases as mentioned above. They should all use the Label editor.
As mentioned before these properties will automatically be populated once an image has been uploaded.
Adding properties
Defining a Media Type folder
Next up, we will create a folder to hold the employee images. We could use the existing Folder Media Type but that would mean editors can upload employee images to any folder of that type. If we create a folder specifically for employee images there is only one place to put them.
Go back to the Settings section and create a new Media Type.
Name it Employee Images.
Select the folder icon by clicking the icon to the left of the name.
Navigate to the List view tab.
Toggle the Enable list view option.
Enable List View
The new folder should be allowed to be created in the root of the Media tree. We also need to allow only the Employee Image Media Type in our new folder. Both of these configurations can be set on the Permissions tab.
Go to the Permissions tab.
Toggle the Allow as root.
Click Add child under Employee Images.
Select Employee Image.
Permissions
Creating the folder and media items
Go to the Media section.
Select ... next to Media and select the Employee images folder.
Name it Employee Images and select Save.
There are four options to add new media items to the folder, as you can see here:
Uploading Media
Uncheck the Allow at root option on the Employee Images Media Type to prevent the creation of multiple folders of this type. This will only disable the creation of new ones and not affect existing folders.
Cropping the images
If you select an image that has been uploaded to the folder you will see the full image and the two defined crops.
Moving the focal point circle on the image will update the crops to focus accordingly. You can also edit the individual crops by selecting them and moving the image or adjusting the slider to zoom.
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 Permissions 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 available 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 "
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.
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
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 adding -- on its own line:
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".
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 Permissions group.
Click Add child
Go to the Content section
Click the menu icon (•••) next to the "Home" node
Select the "Text page
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
Right-click 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
Right-click the Document type
Select Import Document Type
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
Related Services
Tutorials
"
Then click the Save and Publish button.
Body Text
".
Select the Rich Text editor under Create new. This will let you configure the editor settings - the Rich Text editor for this property.
italic
alignLeft
alignCenter
link
umbMediaPicker
When you are happy with the settings click Submit.
Add a group called "Content"
This time we'll add two properties:
First, make a property called "Summary" using the Textarea editor
Secondly, create a property called "Body Text" and reuse the Rich Text Editor Data Type.
Select "Text Page".
" Document Type. We'll name the page "
About us
".
We now have a basic content structure.
Click on the Import button and browse to the Document Type you exported. The Name and Alias of the Document Type are displayed.
[This is an absolute link](https://google.com)
[This is a relative link](/umbraco#/media)
This is initially shown
--
This is initially hidden
This is **bold**
This is *italic*
[This is an absolute link](https://google.com)
[This is a relative link](/umbraco#/media)
--
Block Grid
Alias: Umbraco.BlockGrid
Returns: BlockGridModel
The Block Grid property editor enables editors to layout their content in the Umbraco backoffice. The content is made of Blocks that can contain different types of data.
Sample configuration
When testing out the property editor, you can use a set of predefined Blocks. The option will only be possible when there are no other Data Types using the Block Grid property editor.
Create a new Data Type.
Select the Block Grid as the Property editor.
Install the "Sample Configuration".
4 Blocks will be added to the property, ready for testing.
Configuring the Block Grid
The Block Grid property editor is configured via the Data Types backoffice interface.
To set up the Block Grid property editor, follow these steps:
Navigate to the Settings section in the Umbraco backoffice.
Right-click the Data Types folder.
Select Create -> New Data Type.
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.
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.
Label example: "My Block {{myPropertyAlias}}" will be shown as: "My Block FooBar".
You can also use more advanced expression using AngularJS filters, like {{myPropertyAlias | limitTo:100}} or for a property using Richtext editor {{myPropertyAlias | ncRichText | truncate:true:100}}. It is also possible to use properties from the Settings model by using {{$settings.propertyAlias}}.
Get more tips on how to use AngularJS filters in Umbraco CMS from this community-made
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.
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
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.
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.
If you like to use the Default Layout Stylesheet, you must copy the stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the css folder, example: wwwroot/css/umbraco-blockgridlayout.css.
A set of built-in Partial Views are responsible for rendering the Blocks and Areas in a grid layout. If you want to tweak or change the way the grid layout is rendered, you can use the built-in Partial Views as a template:
Clone the views from <a href="https://github.com/umbraco/Umbraco-CMS/">GitHub</a>. They can be found in /src/Umbraco.Cms.StaticAssets/Views/Partials/blockgrid/
2. Build your own rendering
The built-in value converter for the Block Grid property editor lets you use the block data as you like. Call the Value<T> method with a type of BlockGridModel to have the stored value returned as a BlockGridModel instance.
BlockGridModel contains the Block Grid configuration (like the number of columns as GridColumns) whilst also being an implementation of IEnumerable<BlockGridItem> (see details for BlockGridItem above).
The following example mimics the built-in rendering mechanism for rendering Blocks using Partial Views:
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.
On a document type add a property called blockGrid.
Then add as editor Block Grid.
In the Block Grid add a new block and click to Create new Element Type
a property called title with the editor of Textstring
a property called text with the editor of Textstring
Then on the Settings model click to add a new Setting.
Then click to Create new Element Type.
Name this element type spotSettings with the following properties:
a property called featured with the editor of True/false.
The raw input data for the spots looks like this:
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).
All contentData and layoutData entries need their own unique Udi as well as the ID (key) of their corresponding Element Types. In this sample, we only have one Element Type for content (spotElement) and one for settings (spotSettings). In a real life scenario, there could be any number of Element Type combinations.
First and foremost, we need models to transform the raw data into Block Grid compatible JSON. Create a class called Model.cs containing the following:
By injecting and into an API controller, we can transform the raw data into Block Grid JSON. It can then be saved to the target content item. Create a class called BlockGridTestController.cs containing the following:
For the above code IContent? content = _contentService.GetById(1203); change the id with your content node that is using the Block Grid.
In order to test this implementation, run the project and add /umbraco/api/blockgridtest/create after your domain name. If the result shows as Saved then check your content node and you will see the 2 spotElement contents.
This can also be tested via Postman as well if preffered.
Select Block Grid from the list of available property editors.
Editor width - Overwrites the width of the property editor. This field takes any valid CSS value for "max-width". For example: 100% or 800px.
Grid Columns - Define the number of columns in your grid layout. The default is 12 columns.
Layout Stylesheet - Replaces the built-in Layout Stylesheet. Additionally, you can retrieve the default layout stylesheet to use as a base for your own inspiration or for writing your own stylesheet.
Create Button Label - Overwrites the label on the Create button.
.
Thumbnail - Pick an image or Scalable Vector Graphics (SVG) file to replace the icon of the Block in the catalogue.
- Determines the total number of Blocks in an Area.
Allowed block types - When this is empty, all Blocks with Permissions for creation in Areas, will be available. This can be overwritten by specifying the allowed Blocks. Define the types of Blocks or Groups of Blocks that are allowed. Additionally, you can also set how many Blocks of each type/group should be present.
Copy the cloned views to the local folder Views/Partials/blockgrid/
Make changes to your copied views. The entry point for GetBlockGridHtmlAsync() is the view default.cshtml
Name this element type spotElement with the following properties:
One layout entry with the desired column and row spans.
@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)
@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>
}
}
@import 'css/umbblockgridlayout.css';
<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 }
}
using Newtonsoft.Json;
using Umbraco.Cms.Core;
namespace My.Site.Models;
// this is the "root" of the block grid data
public class BlockGridData
{
public BlockGridData(BlockGridLayout layout, BlockGridElementData[] contentData, BlockGridElementData[] settingsData)
{
Layout = layout;
ContentData = contentData;
SettingsData = settingsData;
}
[JsonProperty("layout")]
public BlockGridLayout Layout { get; }
[JsonProperty("contentData")]
public BlockGridElementData[] ContentData { get; }
[JsonProperty("settingsData")]
public BlockGridElementData[] SettingsData { get; }
}
// this is a wrapper for the block grid layout, purely required for correct serialization
public class BlockGridLayout
{
public BlockGridLayout(BlockGridLayoutItem[] layoutItems) => LayoutItems = layoutItems;
[JsonProperty("Umbraco.BlockGrid")]
public BlockGridLayoutItem[] LayoutItems { get; }
}
// this represents an item in the block grid layout collection
public class BlockGridLayoutItem
{
public BlockGridLayoutItem(Udi contentUdi, Udi settingsUdi, int columnSpan, int rowSpan)
{
ContentUdi = contentUdi;
SettingsUdi = settingsUdi;
ColumnSpan = columnSpan;
RowSpan = rowSpan;
}
[JsonProperty("contentUdi")]
public Udi ContentUdi { get; }
[JsonProperty("settingsUdi")]
public Udi SettingsUdi { get; }
[JsonProperty("areas")]
// areas are omitted from this sample for abbreviation
public object[] Areas { get; } = { };
[JsonProperty("columnSpan")]
public int ColumnSpan { get; }
[JsonProperty("rowSpan")]
public int RowSpan { get; }
}
// this represents an item in the block grid content or settings data collection
public class BlockGridElementData
{
public BlockGridElementData(Guid contentTypeKey, Udi udi, Dictionary<string, object> data)
{
ContentTypeKey = contentTypeKey;
Udi = udi;
Data = data;
}
[JsonProperty("contentTypeKey")]
public Guid ContentTypeKey { get; }
[JsonProperty("udi")]
public Udi Udi { get; }
[JsonExtensionData]
public Dictionary<string, object> Data { get; }
}
BlockGridTestController.cs
using Microsoft.AspNetCore.Mvc;
using My.Site.Models;
using Newtonsoft.Json;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Web.Common.Controllers;
namespace My.Site.Controllers;
public class BlockGridTestController : UmbracoApiController
{
private readonly IContentService _contentService;
private readonly IContentTypeService _contentTypeService;
public BlockGridTestController(IContentService contentService, IContentTypeService contentTypeService)
{
_contentService = contentService;
_contentTypeService = contentTypeService;
}
// POST: /umbraco/api/blockgridtest/create
[HttpPost]
public ActionResult Create()
{
// get the item content to modify
IContent? content = _contentService.GetById(1203);
if (content == null)
{
return NotFound("Could not find the content item to modify");
}
// get the element types for spot blocks (content and settings)
IContentType? spotContentType = _contentTypeService.Get("spotElement");
IContentType? spotSettingsType = _contentTypeService.Get("spotSettings");
if (spotContentType == null || spotSettingsType == null)
{
return NotFound("Could not find one or more content types for block data");
}
// this is the raw data to insert into the block grid
var rawData = new[]
{
new { Title = "Item one", Text = "This is item one", Featured = false, ColumnSpan = 12, RowSpan = 1 },
new { Title = "Item two", Text = "This is item two", Featured = true, ColumnSpan = 6, RowSpan = 2 }
};
// build the individual parts of the block grid data from the raw data
var layoutItems = new List<BlockGridLayoutItem>();
var spotContentData = new List<BlockGridElementData>();
var spotSettingsData = new List<BlockGridElementData>();
foreach (var data in rawData)
{
// generate new UDIs for block content and settings
var contentUdi = Udi.Create(Constants.UdiEntityType.Element, Guid.NewGuid());
var settingsUdi = Udi.Create(Constants.UdiEntityType.Element, Guid.NewGuid());
// create a new layout item
layoutItems.Add(new BlockGridLayoutItem(contentUdi, settingsUdi, data.ColumnSpan, data.RowSpan));
// create new content data
spotContentData.Add(new BlockGridElementData(spotContentType.Key, contentUdi, new Dictionary<string, object>
{
{ "title", data.Title },
{ "text", data.Text },
}));
// create new settings data
spotSettingsData.Add(new BlockGridElementData(spotSettingsType.Key, settingsUdi, new Dictionary<string, object>
{
{ "featured", data.Featured ? "1" : "0" },
}));
}
// construct the block grid data from layout, content and settings
var blockGridData = new BlockGridData(
new BlockGridLayout(layoutItems.ToArray()),
spotContentData.ToArray(),
spotSettingsData.ToArray());
// serialize the block grid data as JSON and save it to the "blockGrid" property on the content item
var propertyValue = JsonConvert.SerializeObject(blockGridData);
content.SetValue("blockGrid", propertyValue);
_contentService.Save(content);
return Ok("Saved");
}
}
This document covers specific upgrade steps if a version requires them. Most versions do not require specific upgrade steps and you will be able to upgrade directly from your current version.
Use the information below to learn about any potential breaking changes and common pitfalls when upgrading your Umbraco CMS project.
If any specific steps are involved with upgrading to a specific version they will be listed below.
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.
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 .
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
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.
10.latest to the latest Umbraco version
It might be necessary to delete all of the bin and obj directories in each of the projects of your solution. It has been observed that Visual Studio's "Clean Solution" option is sometimes not enough.
You can upgrade from Umbraco 10 to the latest version directly. If you choose to skip upgrading to versions 11 and 12, you will no longer receive warning messages for obsolete features. However, if you do skip these versions, any breaking changes will no longer compile.
It is recommended to upgrade to the closest 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
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.
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.
Version 7.7.2 no longer ships with the CookComputing.XmlRpcV2
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
7.4.0 to 7.6.0
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
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:
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
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
Watch this tutorial and learn how to create your own Media Types in Umbraco CMS.
You can find more information about all breaking changes for v13.0.0 on Our Umbraco website.
Note: You need to be aware of some things if you are using EF Core, and have installed the Microsoft.EntityFrameworkCore.Design 8.0.0 package:
This package has a transient dependency to Microsoft.CodeAnalysis.Common which clashes with the same transient dependency from Umbraco.Cms 13.0.0. This happens because Microsoft.EntityFrameworkCore.Design 8.0.0 requires Microsoft.CodeAnalysis.CSharp.Workspaces in v4.5.0 or higher.
If there are no other dependencies that need that package then it installs it in the lowest allowed version (4.5.0). That package then has a strict dependency on Microsoft.CodeAnalysis.Common version 4.5.0. The problem is Umbraco.Cms through its own transient dependencies that require the version of Microsoft.CodeAnalysis.Common to be >= 4.8.0.
This can be fixed by installing Microsoft.CodeAnalysis.CSharp.Workspaces version 4.8.0 as a specific package instead of leaving it as a transient dependency. This is because it will then have a strict transient dependency on Microsoft.CodeAnalysis.Common version 4.8.0, which is the same that Umbraco has.
PagedModel has moved namespace from Umbraco.New.Cms.Core.Models to Umbraco.Cms.Core.Models
Umbraco.Cms.Infrastructure.Migrations.PostMigrations.ClearCsrfCookies is removed. The functionality can be archived by implementing a notification handler for the new UmbracoPlanExecutedNotification.
Umbraco.Cms.Core.Cache.DistributedCacheBinder is now divided into separate files for each notification handler
Umbraco.Cms.Infrastructure.Migrations.PostMigrations.DeleteLogViewerQueryFile was a no-op method removed.
Umbraco.Cms.Infrastructure.Migrations.PostMigrations.RebuildPublishedSnapshot replaced with a RebuildCache flag on the MigrationBase
A member that is visible outside of the assembly is missing in the compared assembly when required to be present.
Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor.Execute(Umbraco.Cms.Infrastructure.Migrations.MigrationPlan,System.String) replaced with Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor.ExecutePlan(Umbraco.Cms.Infrastructure.* * Migrations.MigrationPlan,System.String) that returns an rich object instead of a string
Umbraco.Cms.Infrastructure.Migrations.IMigrationContext.AddPostMigration``1 Removed and replaced with notification
Umbraco.Cms.Infrastructure.Migrations.Upgrade.Upgrader.Execute(Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor,Umbraco.Cms.Core.Scoping.IScopeProvider,Umbraco.Cms.Core.Services.IKeyValueService) was obsolete and is replaced by method taking a ICoreScopeProvider instead of a IScopeProvider
An abstract member was added to the right side of the comparison to an unsealed type.
PublishedPropertyBase now requires inheritors to implement GetDeliveryApiValue(System.Boolean,System.String,System.String)
A member was added to an interface without a default implementation.
The breaking changes in Umbraco 11 are mainly the removal of classes, methods, and so on, marked as obsolete in Umbraco 9.
A few methods and classes have also been moved and changed namespace. Decoupled dependencies are documented on the Umbraco Announcements repository.
The full list of API-breaking changes can be found below.
Obsolete code removed
The following have been removed after having been obsoleted since Umbraco 9.
Umbraco.Extensions
Umbraco.Cms.Core
Umbraco.Cms.Infrastructure
Umbraco.Cms.Web
Umbraco.Cms.Tests
Code moved to new assemblies and namespaces
The following have been moved to new assemblies and their namespaces have been updated accordingly.
Umbraco.Extensions
Umbraco.Cms.Web
Umbraco.Cms.Infrastructure
New interface methods
A few interfaces have been merged, adding new members to the original interfaces.
Umbraco.Cms.Core
No-Operation methods removed
A method not doing anything for the last couple of major releases have been removed.
Umbraco.Cms.Core
Changes due to models made immutable
A single model have been made immutable, so the default constructor and the setters are not available anymore.
Umbraco.Cms.Infrastructure
Classes that does not inherit from base type anymore
The following classes now directly inherit from OEmbedProviderBase instead of EmbedProviderBase.
Umbraco.Cms.Core
IContent/Content
to
read/write
content schedules.
Use IContentService.GetContentScheduleByContentId && IContentService.PersistContentSchedule or the optional contentSchedule parameter on IContentService.Save instead.
Removed public methods: PublishedSnapshotServiceEventHandler.Dispose, PublishedSnapshotServiceEventHandler.Dispose(bool), and .PublishedSnapshotServiceEventHandler.Initialize.
Removed support for Microsoft SQL Server Compact (SQL CE).
Removed ReadLock and WriteLock methods from ISqlSyntaxProvider interface. Use IDistributedLockingMechanism (or IScope which delegates to IDistributedLockingMechanism) instead.
Constants for SQL Server provider name moved+consolidated from Core.Constants.DatabaseProviders and Core.Constants.-DbProviderNames to Umbraco.Cms.Persistence.SqlServer.Constants
Some SQL Server related services moved from the Umbraco.Infrastructure project to the new Umbraco.Cms.Persistence.
SqlServer project with altered namespaces e.g. SqlServerSyntaxProvider, SqlServerBulkSqlInsertProvider, SqlServerDatabaseCreator.
Added the following methods/properties to ISqlSyntaxProvider. These must be implemented in any downstream implementation e.g:
Renamed the CachedNameLength property to CacheHashLength on ImagingCacheSettings.
Moved ImageSharpImageUrlGenerator from project Umbraco.Infrastructure to Umbraco.Web.Common and updated the corresponding namespace and DI registration (from AddCoreInitialServices() to AddUmbracoImageSharp());
Moved ImageSharp configuration from the AddUmbracoImageSharp() extension method into separate IConfigureOptions<> implementations:
The middleware is configured in ConfigureImageSharpMiddlewareOptions (which also replaces ImageSharpConfigurationOptions that previously only set the default ImageSharp configuration);
The default physical cache is configured in ConfigurePhysicalFileSystemCacheOptions.
This is breaking because it is no longer possible to access the properties listed below through the IMember.Properties collection. You must now access them through their specific properties that is IMember.IsLockedOut.
umbracoMemberFailedPasswordAttempts
umbracoMemberApproved
umbracoMemberLockedOut
umbracoMemberLastLockoutDate
umbracoMemberLastLogin
umbracoMemberLastPasswordChangeDate
Additionally, when previously you resolved a Member as published content, all the default properties would be there twice. For instance, IsLockedOut would be there both as a property with the alias umbracoMemberLockedOut and with the alias IsLockedOut. Now it'll only be there once, with the alias being the name of the property, so IsLockedOut in this instance.
Lastly the nullable dates on a user, i.e. LastLoginLate will now be null instead of DateTime.MinValue when getting a user with the UserService.
Added a new method on IPublishedModelFactory: Type GetModelType(string? alias);
The generic types of a BlockListItem<TContent, TSettings>instance in theBlockListModelreturned byBlockListPropertyValueConverteris now determined by calling this new method, which can be different and cause aModelBindingException` in your views.
StackQueue has been moved from Umbraco.Core.Collections to the Umbraco.Cms.Core.Collections namespace.
Globalsetting SqlWriteLockTimeOut has been removed
This setting has been superseded by DistributedLockingWriteLockDefaultTimeout.
GlobalSetting UmbracoPath cannot be configured
It is no longer possible to rename the /Umbraco folder path using configuration. The property still exists but is hardcoded to /Umbraco and will be removed in Umbraco 12, planned for release in June 2023.
There is no official migration path from SQL CE to another database engine.
The following options may suit your needs:
Follow a community guide to migrate from a SQL CE database to SQL Server, like the article by Jan Reilink
Setup a new database for v10 and use uSync to transfer document types and content across.
Setup a new database for v10 and use a premium tool such as redgate SQL Data Compare to copy database contents across.
Setup a new database for v10 and use a premium tool such as to transfer document types and content across.
Steps to upgrade using Visual Studio
It's recommended that you upgrade the site offline, and test the upgrade fully before deploying it to the production environment.
Stop your site in IIS to prevent any changes being made to the database or filesystem while you are upgrading.
Open your Umbraco 9 project in Visual Studio.
Right-click on the project name in the Solution Explorer and select Properties.
Select .NET 6.0 from the Target Framework drop-down.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
Go to the Installed tab in the NuGet Package manager.
Choose Umbraco.Cms.
Select 10.0.0 from the Version drop-down and click Install to upgrade your project to version 10.
Update Program.cs to the following:
Remove the following files and folders:
/wwwroot/umbraco
/umbraco/PartialViewMacros
/umbraco/UmbracoBackOffice
/umbraco/UmbracoInstall
/umbraco/UmbracoWebsite
/umbraco/config/lang
/umbraco/config/appsettings-schema.json
If using Umbraco Forms, update your files and folders according to the for version 10 article.
Restart your site in IIS, build and run your project to finish the installation of Umbraco 10.
To re-enable the appsettings IntelliSense, you must update your schema reference in the appsettings.json file and any other appsettings.{Environment}.json files from:
To:
To upgrade to Umbraco 10, your database needs to be at least on Umbraco 8.18.
Upgrade of any publicly hosted environment
When the upgrade is completed and tested, and prior to deploying to any publicly accessible environment, you should consider the following:
Ensure you have backups for both the database and the file system.
Stop the site so it is not accessible during the upgrade process.
Delete the relevant folders from the filesystem prior to deploying:
/wwwroot/umbraco
/umbraco/PartialViewMacros
/umbraco/UmbracoBackOffice
/umbraco/UmbracoInstall
/umbraco/UmbracoWebsite
/umbraco/config/lang
/umbraco/config/appsettings-schema.json
If you are using Umbraco Forms, update your files and folders according to the for version 10 article.
Deploy the site how you normally would to your public facing environment.
Start the site. At this point it will launch and upgrade the database, after which the site should become accessible and your upgrade is complete.
Check the logs for any errors which may have occurred during the upgrade process.
The introduction of multilingual support in version 8 required changes to the interface. For instance, a property value could be obtained with GetPropertyValue(alias) in version 7. Version 8 requires a new parameter for culture, and the call thus became Value(alias, culture).
In the excitement of the version 8 release, we assumed that IPublishedContent was "done". By our tests, everything was looking good. However, feedback from early testers showed that the interface was in some places odd or inconsistent or had issues.
Fixing the bugs is a requirement. Some of the required bug fixes could not be achieved without introducing some breaking changes.
At that point, we decided to give IPublishedContent some love. We fixed the bugs and made it clean, friendly, discoverable, and predictable for the entire life of version 8.
Breaking changes to such a central interface is not something we take lightly. Even though they do not impact the "concepts" nor require heavy refactoring, they may demand an amount of small fixes here and there.
The general idea underlying these changes is that:
The proper way to retrieve "something" from an IPublishedContent instance is always through a method, for example: Children(). And, when that method can be multilingual, the method accepts a culture parameter, which can be left null to get the "current" culture value.
To reduce the amount of breaking changes, and to simplify things for non-multilingual sites, existing properties such as document.Name and document.Children (and others) still exist, and return the value for the current culture. In other words, these properties are now implemented as document.Name => document.Name() or document.Children => document.Children().
The rest of this document presents each change in details.
More interfaces
It was possible to mock and test the IPublishedContent interface in version 7. It has been improved in version 8, but it still relies on concrete PublishedContentType and PublishedPropertyType classes to represent the content types, which complicates things.
In version 8.1, these two classes are abstracted as IPublishedContentType and IPublishedPropertyType, thus making IPublishedContent easier to mock and test.
CHANGE: This impacts every method accepting or returning a content type. For instance, the signature of most IPropertyValueConverter methods changes. References to PublishedContentType must be replaced with references to IPublishedContentType.
The following IPublishedContent members change:
Name
The document.Name property is complemented by the document.Name(string culture = null) extension method. The property returns the name for the current culture. The document.GetCulture(...).Name syntax is removed.
CHANGE: Calls to document.GetCulture(culture).Name must be replaced with document.Name(culture).
UrlSegment
The document.UrlSegment property is complemented by the document.UrlSegment(string culture = null) extension method. The property returns the Url segment for the current culture. The document.GetCulture(...).UrlSegment syntax is removed.
CHANGE: Calls to document.GetCulture(culture).UrlSegment must be replaced with document.UrlSegment(culture).
Culture
The document.GetCulture() method is removed. The proper way to get a culture date is document.CultureDate(string culture = null). The document.Cultures property now returns the invariant culture, for invariant documents.
CHANGE: Calls to document.GetCulture(culture).Date must be replaced with document.CultureDate(culture). Calls to document.Cultures must take into account the invariant culture.
Children
The document.Children property is complemented by the document.Children(string culture = null) extension method which, when a culture is specified always return children available for the specified culture. The property returns the children available for the current culture.
A new document.ChildrenForAllCultures property is introduced, which returns all children, regardless of whether they are available for a culture or not.
CHANGE: Calls to document.Children may have to be replaced by document.ChildrenForAllCultures depending on if the 8.0.x usage of this was relying on it returning unfiltered/all children regardless of the current routed culture.
Url
The document.Url property is complemented by the document.Url(string culture = null, UrlMode mode = UrlMode.Auto) extension method. The document.GetUrl(...) and document.UrlAbsolute() methods are removed. The UrlProviderMode enumeration is renamed UrlMode.
CHANGE: Calls to document.GetUrl(...) must be replaced with document.Url(...). Calls to document.UrlAbsolute() must be replaced with document.Url(mode: UrlMode.Absolute).
UmbracoContext
Due to the UrlProviderMode enumeration being renamed UrlMode, the signature of some overloads of the Url(...) method has changed. Methods that do not have a mode parameter remain unchanged.
CHANGE: Code such as context.Url(1234, UrlProviderMode.Absolute) must become context.Url(1234, UrlMode.Absolute).
The UmbracoContext class gives access to the rendering layer, which is more than a "cache". To reflect this, its ContentCache and MediaCache properties are renamed Content and Media. However, the old properties remain as obsolete properties.
CHANGE: None required in 8.1, but code such as context.ContentCache.GetById(1234) should eventually be converted to context.Content.GetById(1234) as the obsolete properties may be removed in a further release.
GetCulture
Version 7 had a document.GetCulture() method that was deriving a culture from domains configured in the tree. Somehow, that method was lost during version 8 development (issue #5269).
Because that method is useful, especially when building traditional, non-multilingual sites, it has been re-introduced in version 8.1 as document.GetCultureFromDomains().
CHANGE: None.
DomainHelper
DomainHelper has been replaced with a static DomainUtilities class.
CHANGE: It is rare that DomainHelper is used in code since it only contains one public method but if developers are using this, it can no longer be injected since it's now a static class called DomainUtilities.
Models Builder
If you're using ModelsBuilder in dll mode you need to delete the dlls before upgrading. Otherwise, they're going to be wrong and cause your whole site to throw errors.
If you're using ModelsBuilder in AppData mode and you have your generated models in your solution you need to update them after upgrading. PublishedContentType will need to be replaced with IPublishedContentType. If you have an implementation of the PropertyValueConverter class, you need to replace all references to PublishedPropertyType with IPublishedPropertyType within that class. Only after you do that will your solution build again.
AutoMapper
Umbraco 8.1 replaces AutoMapper with UmbracoMapper. This in itself will not break anything on your site. If you have used AutoMapper in your own code you will have to either include the package yourself or switch your implementation to use UmbracoMapper.
assembly. If you reference this assembly or have a package that requires this assembly, you need to copy it back into your website.
This version also ships with far fewer client files that were only relevant for older versions of Umbraco (i.e. < 7.0.0). There might be some packages that were referencing these old client files. If you see missing image references you may need to contact the vendor of the package in question to update their references.
Depending on whether you tried to fix the problem with those, you will need to fix them after you upgrade to 7.6.3.
Property Value Converters (PVC)
Umbraco stores data for Data Types in different ways. For a lot of pickers it will store 1072 or 1083,1283. These numbers refer to the identifier of the item in Umbraco. In the past, when building your templates, you would manually have to take that value and find the content item it belongs to. Then you would be able to get the data you wanted from there. An example of that is shown below:
In Umbraco 7.6.0, this is what you would do instead:
This is possible using Models Builder and through the inclusion of core property value converters, a package by community member Jeavon Leopold.
To not break everybody's sites (the results of queries are different when PVCs are enabled), we disabled these PVCs by default.
Umbraco 7.6.0 also came with new pickers that store their data as a UDI (Umbraco Identifier). We wanted to simplify the use of these new pickers and by default we wanted PVC's to always be enabled for those pickers.
We noticed that some new pickers also got their PVC's disabled when the configuration setting was set to false (<EnablePropertyValueConverters>false</EnablePropertyValueConverters>).
To make everything consistent, we made sure that the UDI pickers would always use PVC's in 7.6.2, this however reversed the behavior. So when PVC's were enabled, the property would not be converted and when PVC's were disabled, the property would be converted after all. This is the exact opposite behavior of 7.6.2.
So we have fixed this now in 7.6.3.
This issue only affects:
Multi Node Tree Picker
Related Links
Member Picker
Have you already upgraded to 7.6.2 and fixed queries for those three Data Types? Then you have to do that again in version 7.6.3.
In umbracoSettings.config leave EnablePropertyValueConverters set to false - this will help your existing content queries to still work.
In tinyMceConfig.config make sure to remove <plugin loadOnFrontend="true">umbracolink</plugin> so that the rich text editor works as it should.
Breaking Changes
Dependencies
UrlRewriting.Net
UrlRewriting was old, leaking memory, and slowing down website startup when dealing with more than a few rules. It's entirely replaced by the IIS Url Rewrite extension.
Json.Net
Json.Net has been updated to version 10.0.0 to benefit from improvements in features, fixes, and performances (see release notes). This might be a breaking change for people relying on one of the changed functionality.
Log4net
Umbraco has used a custom build of an old (1.2.11) version of log4net that supported Medium Trust. However, Umbraco itself does not support Medium Trust anymore, and therefore log4net has been upgraded to the standard, latest build of log4net 2.0.8.
ImageProcessor
An optional parameter has been added to the GetCropUrl method in order to support the background color parameter. This breaks the method signature and therefore might require a recompile of user's code.
HtmlAgilityPack
The HtmlAgilityPack has been upgraded to version 1.4.9.5. The Umbraco upgrade process should take care of setting up the binding redirects appropriately.
Core
Membership Provider Encoding
The Membership Provider useLegacyEncoding setting is now false by default, as the legacy password encoding has weaknesses.
This change only impacts new installs (no change for upgrades).
Property Value Converters
A large amount of property value converters contributed by the community have been merged in and are now the default value converters. These converters change the object types returned by GetPropertyValue for more convenient types.
Instead of returning comma-separated string values like it did before, the SliderValueConverter now returns a decimal or a Range<decimal> value that can be used directly in views.
This change only impacts new installs (no change for upgrades).
The new property value converters are controlled by an umbracoSettings.config setting. In the section settings/content, setting EnablePropertyValueConverters needs to be present and true to activate them.
Database
Umbraco has been using a PetaPoco-managed UmbracoDatabase instance since version 7 came out. We realized that some of our legacy code still bypassed that mechanism and used parallel, out-of-band database connections, causing issues with transactions.
The legacy code has been refactored to rely on the UmbracoDatabase instance. However, because that database is disposed of during EndRequest, the code that ran after it has been disposed may not work anymore. This should then be updated to use either an HttpModule event that occurs before EndRequest or the new UmbracoModule.EndRequest event.
More details are available on issue 146 on the 301 Redirect Tracker GitHub issue tracker.
Scopes
Version 7.6 introduces the notion of scopes, which allow for wrapping multiple service-level operations in one single transaction. The scopes API is partially public. Scopes are not meant for public use at this stage and we need a few more releases to ensure that the APIs are stable.
Scopes should not change how Umbraco functions.
Introducing scopes means that some public APIs signatures are changing. Most of these changes target internal and/or non-breaking APIs (as per our guidelines). This should therefore have no impact on sites but may break unit tests.
Property Editors storing UDI instead of ID
The property editors for pickers for content, media, members, and related links have been updated to store UDI instead of the node ID. Pickers in sites being upgraded have been marked as obsolete but will continue to work as they always did.
New sites will have the obsolete pickers filtered out from the list of available property editors, but they can be enabled by a configuration flag.
Rich Text Editor (RTE) Images attributes
For a long time, we had a rel attribute on an <img> tag when inserted into the RTE. This is invalid HTML markup. We worked around this by stripping this attribute using a Property Editor Value converter. Some developers relied on this attribute so we didn't change it to a "data-id" attribute which would have been valid. In 7.6 we are not storing integer IDs in these attributes. Instead of storing UDI values so with this change we no longer use rel or data-id and instead there will be a "data-udi" attribute. This change should affect only a small amount of people that were previously relying on the values from the "rel" attribute.
Others
We are shipping with SignalR in the core at version 2.2.1. If you already have SignalR installed into your app and are using an older version there may be conflicts.
The creation and editing of WebForms templates will no longer be supported as for version 7.6.0.
Upgrading via NuGet
This is an important one and there was no perfect solution to this. We have removed the UrlRewriting dependency and no longer ship with it. However, if you are using it we didn't want to have NuGet delete all of your rewrites. The good news is that if you are using it, the NuGet upgrade will not delete your rewrite file and everything should continue to work.
However, if you are not using it, you will get an error after upgrading. Here's how to fix it:
Since you aren't using UrlRewriting you will have probably never edited the UrlRewriting file. In this case, NuGet will detect that and remove it. However you will need to manually remove these UrlRewriting references from your web.config:
and
Remove the following httpModules from your web.config:
and
Forms
Umbraco Forms 6.0.0 has been released to be compatible with Umbraco 7.6. It is a new major version release of Forms primarily due to the strict dependency on 7.6+. If you are using Forms, you will need to update it to version 6.0.0
Do not forget to merge ~/Config/trees.config and ~/Config/Dashboard.config - they contain new and updated entries that are required to be there
If you forget trees.config you will either not be able to browse the Developer section or you will be logged out immediately when trying to go to the developer section
You may experience an error saying Invalid object name 'umbracoUser' - this can be fixed by clearing your cookies on localhost
You need to update your web.config file to have the correct WebApi version references - this should be done by doing a compare/merge of your ~/web.config file with the ~/web.config file in the release
MVC has been updated to MVC5
You need to update your web.config file to have the correct MVC version references - this should be done by doing a compare/merge of your ~/web.config file with the ~/web.config file in the release
It is not required that you merge the changes for the Examine index paths in the ExamineIndex.config file. However, if you do, your indexes will be rebuilt on startup because Examine will detect that they don’t exist at the new location.
It's highly recommended to clear the browser cache - the ClientDependency version is automatically bumped during installation which should force the browser cache to refresh, however in some edge cases this might not be enough.
Move appSettings/connectionStrings back to web.config
If you are on 7.0.0 you should migrate these settings into the web.config instead of having them in separate files in /config/
The keys in config/AppSettings.config need to be moved back to the web.config <appSettings> section and similarly, the config/ConnectionStrings.config holds the Umbraco database connections in v7.0.0 and they should be moved back to the web.config <connectionStrings> section.
/config/AppSettings.config and /config/ConnectionString.config can be removed after the contents have been moved back to web.config.
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>();
});
}
The upgrader will take care of updating all other web.config’s (in all other folders, for example, the Views and App_Plugins folders) to have the correct settings
