What is involved in an upgrade

When upgrading to a new version of Umbraco, there are four key aspects of the migration to be aware of.

Database schema and content

Firstly there's the update of your Umbraco database's schema and how the content is stored. On occasion changes are necessary to support a new feature. This might be adding new tables or columns, or updating the stored data. This is something Umbraco takes care of for you. When Umbraco starts up and is running a newer version, the necessary changes will be detected and applied.

As a developer responsible for the Umbraco website, there's nothing specific you need to do here. We will communicate key migrations that will happen on major version upgrades. As if you have a large site and significant amounts of data need to be updated, the migration could take some time to complete.

Minor or patch versions may contain schema and content updates too, but they won't be extensive.

Supported features

Secondly you should review your use of property editors to ensure that they are available on the new version. It's rare for these to be removed, but it can happen when better alternatives are available. These are only removed in major versions and with plenty of notice on the announcements repository. Property editors for retirement will also have been indicated as legacy on earlier versions.

Project customizations

The third aspect is determining and verifying that your own code customizations are compatible with the new version. This includes C# server-side functionality, Razor templates and JavaScript backoffice extensions.

Extensive efforts are made to avoid breaking changes that would cause issues for these types of customization other than in a major version update.

Finally you should consider the packages you are using on your project. You will need to verify that the package will work with the new version of Umbraco. Or that a compatible upgrade of the package is available or planned.

As above, breaking changes that would prevent packages from working other than in a major version update are avoided.

For the reasons described, projects always need to be considered case by case when upgrading to new versions.

Umbraco communicates about the breaking changes in release blog posts and on the documented . There will be extended release candidate periods to ensure upgrades can be tested and to help package developers support new major versions.

Breaking changes are minimized but there will be cases when such updates are needed. How straightforward the upgrade will be depends on the breaking changes included in the major and whether your project(s) are impacted by them.

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.

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

• - how to upgrade Umbraco across major, minor, and patch versions.

• - configure Umbraco to upgrade in an unattended mode, avoiding the need to click through the installation wizard.

• - details of changes to be aware of when upgrading to specific versions.

• - covers the possibility of downgrading to a previous version and re-running migrations from an upgrade.

Prerequisites

• Check the article to ensure you have everything you need to start your Umbraco project.

Install the template

1. Install the latest .NET SDK.

2. Run dotnet new install Umbraco.Templates to install the project templates.

Create the Visual Studio project

1. Go to File > New > Project/Solution.

2. Search for Umbraco in the Search for templates field.

3. Select Umbraco Project (Umbraco HQ).

4. Click Next.

5. Enter a Project name.

1. Select .Net 10.0 Long-Term Support (LTS) from the Framework dropdown. The rest of the fields are optional.

2. Click Create.

The Umbraco Project is ready for you.

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.

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

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.

1. Create a backup of the database from your Umbraco 8 project (after you have upgraded to the latest version of v8). For this, you can use the .

2. Import the database backup into SQL Server Management Studio.

3. Update the connection string in the new projects appsettings.json file so that it connects to the Umbraco 8 database:

1. Run the new project and login to authorize the upgrade.

2. Select "Upgrade" when the upgrade wizard appears.

3. Once the upgrade has been completed, it's recommended to login to the backoffice to verify if your project is upgraded to new version.

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

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.

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

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

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

• Template files need to use ContentModels = Umbraco.Cms.Web.Common.PublishedModels instead of ContentModels = Umbraco.Web.PublishedModels

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.

• , for the configuration of Umbraco 7 and 8

Whether you are an editor managing daily content or a developer configuring the system for the first time, understanding the Backoffice is essential. This section covers the fundamental operations of the Umbraco interface from initial login and content creation to advanced node management.

Once you are familiar with the basics, the Tips and Tricks section covers audit trails, notifications, session timeout, and other useful backoffice features.

What this section covers

• Content lifecycle: Create, save, preview, publish, and unpublish content

• Node management: Find, edit, sort, move, copy, delete, and restore pages

Related Resources

Umbraco HQ offers training on backoffice workflows, content management, and editorial best practices.

The course is useful for content editors, project managers, and other team members who want a stronger foundation in working with Umbraco.

.

If you have pages that are no longer required for your website, you can delete them. Upon deletion, the page is moved to the Recycle Bin and is not deleted permanently.

In case you wish to restore the page, you can restore them from the Recycle Bin. You also have the option to empty the Recycle Bin which permanently deletes all the items.

Deleting a Page

To delete a page:

1. Go to Content.

2. Click ... next to the page you wish to delete.

3. Select Trash.

Alternatively, click on the ... next to the title field and select Trash.

1. A window appears confirming if you want to delete the page.

1. Click OK.

2. A confirmation message appears. Click OK to dismiss the confirmation message.

The Recycle Bin is a separate tree list which can be found at the bottom of the section tree view. Selecting the Recycle Bin page, opens a list view with all deleted content. Clicking the arrow to the left of the Recycle Bin icon in the tree will also list any pages that have been deleted.

To restore deleted pages from the Recycle Bin:

1. Click ••• next to the page in the list and select Restore.

You can also click on the ... next to the page in tree and select Restore.

1. A window appears confirming if you want to restore the page.

2. Click Restore.

3. A confirmation message appears. Click OK to dismiss the confirmation message.

If you are confident you no longer require any pages in the Recycle Bin, you can permanently delete it. You can delete pages one by one or empty the Recycle Bin in one go.

To empty the Recycle Bin:

1. Select the Recycle Bin and click on Empty recycle bin above the list.

1. A message appears confirming if you want to empty the recycle bin.

1. Click OK.

Alternatively, click on the ... when hovering the Recycle Bin, and select Empty recycle bin... from the menu.

To delete individual pages from the Recycle Bin:

1. Select the Recycle Bin to open the list of deleted items.

2. Click on the trash bin icon next to the content you want to permanently delete.

You can also open the page and click the ... next to the title field and select Delete.

1. A message appears confirming if you want to delete the page.

1. Click OK.

2. A confirmation message appears. Click OK to dismiss the confirmation message.

In this article, you get an overview of how to create and save pages. You will also learn more about how to publish and unpublish your content.

If you are a Cloud user, you will also learn how to compare and transfer content between environments. In Umbraco Cloud, an environment is a separate workspace such as Development, Staging, or Live/Production. It lets you preview and test changes before moving them to your live site. For more information about environments, see the Environments article in the Umbraco Cloud documentation.

Creating a New Page

Select the parent page to create your new page. The parent page can be the home page or any of the sub-pages of the site.

If the parent page allows sub-pages underneath it, follow these steps:

1. Hover over the name of the parent page in the Content section and click ••• to view the types of pages you can create.

2. Select the page type you wish to create. The new page is loaded in the editor on the right-hand side.

3. Enter a Name for the page and click Save.

There are three different options for saving and publishing pages. The options vary depending on whether you’re still in the process of editing the page or you’re ready to publish your changes.

The Save and preview button allows you to save your changes and preview it before publishing the changes to the live site. The Preview feature shows you how the page will look once it is published. This Save and preview feature only saves your page and does not publish your contents to the live site.

The Save button is used for saving the page without publishing the changes to the live site. The Save feature prevents data loss during long-term projects. Use it frequently to protect your ongoing changes.

The Save and publish button is used to publish a previously saved page to the live website or to publish a page without previewing it. The Save and publish feature will save and publish the page to your live website.

The Save and publish button has three options:

The Schedule button allows you to set a time and a date for when your page should be published. The Schedule option lets you keep editing your page. The site will automatically publish at your scheduled date and time.

To set up scheduled publishing, follow these steps:

1. Navigate to the page you want to publish.

2. Select the arrow next to the Save and Publish button.

3. Select Schedule publish.

4. In the Scheduled Publishing window, set the date and time in the Publish at field.

1. Select Schedule.

The Publish with descendants button allows you to publish the current page and all the content linked to this page to the live site. Using this option, you can publish the current parent page and its child nodes, previously published, and unpublished content items.

To publish the node with descendants, follow these steps:

1. Navigate to the page you want to publish.

2. Select the arrow next to the Save and Publish button.

3. Select Publish with descendants.

4. Toggle the option to Include unpublished content items if you wish to. This option includes all unpublished content items for the selected page and the descendant pages.

The Unpublish button allows you to unpublish a page if you do not want a page to be publicly visible.

To unpublish a page, follow these steps:

1. Navigate to the page you want to unpublish.

2. Select the arrow next to the Save and Publish button.

3. Select Unpublish.

Take note of any listed items with dependencies on the content your are unpublishing. This will typically be child items published under the content you have selected.

You can also unpublish your page by setting the date and time using the Schedule feature.

To set up scheduled unpublishing, follow these steps:

1. Navigate to the page you want to unpublish.

2. Select the arrow next to the Save and Publish button.

3. Select Schedule.

4. In the Scheduled Publishing window, set the date and time in the Unpublish at field.

1. Select Schedule.

Umbraco 15 changes the internal data format of all Block Editors.

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

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

It is advised to clean up old content versions before upgrading. This will make the migration run faster.

Parallelizing the content migration

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

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

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

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

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

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

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

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

• for Block List properties.

• for Block Grid properties.

• for Rich Text Editor properties.

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

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

• .NET SDK with Umbraco Templates v16 or higher

• Docker Desktop

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

The Umbraco content tree view allows you to navigate web pages through a logical site hierarchy. You can find a page by navigating through the tree itself if you know where the page is stored.

To search across all the content, files, or folders in Umbraco, click the Magnifier icon in the top-right of the screen. Alternatively, you can use the keyboard shortcut CTRL + SPACE to access the Search bar.

Using the search bar, you can enter a search term to search across most content and settings data in the backoffice. This includes:

• Document Types

• Data Types

This documentation covers the currently supported versions of Umbraco CMS. For legacy or End-of-Life (EOL) versions, use the resources below.

When a major version of Umbraco CMS reaches EOL, its documentation is unpublished one to three months later.

Documentation for all EOL versions remains available on the .

The documentation for Umbraco versions 7 and 8 is available on .

Re-use a page or a tree structure you have previously created by copying the parent page and its child pages to a different section within the site structure.

When you copy a parent page all of its child pages are also copied, by default. You can choose if you want to copy the child pages or not. You can also choose whether the links should be automatically updated or continue to link to the original pages.

You can copy a page in two ways:

Option 1

1. Go to Content.

2. Click ... next to the page you wish to copy.

3. Select Duplicate to.

A window appears on the right side of the screen. Here, you can choose where you want to copy the page in the tree structure.

1. Toggle Relate to original button if you want to keep the links linked to the original page.

2. Toggle Include descendants if you want to copy the child pages alongside the parent page.

3. Click Copy.

1. Go to Content.

2. Select the page you wish to copy.

3. Click ... next to the title of the page.

4. Select Duplicate to.

A window appears on the right side of the screen. Here, you can choose where you want to copy the page in the tree structure.

1. Toggle Relate to original button if you want to keep the links linked to the original page.

2. Toggle Include descendants if you want to copy the child pages alongside the parent page.

3. Click Copy.

The pre-release can be used to test your website and projects against the next major version of Umbraco CMS.

The first phase is a beta version, which is then followed by a Release Candidate.

This article contains all the resources needed for you to start testing.

• How to Test the Pre-Release version

• New and Updated Documentation

Test the Pre-Release version

Ensure you meet the prerequisites and move on to the installation steps outlined below.

Prerequisites

• The latest .

The .

1. Install the Umbraco dotnet template for the beta.

1. Create a new Umbraco project.

1. Navigate to the newly created folder.

1. Build and run the project.

This will boot the project and write the log to the console. The website is now running on your local machine and will be available on the ports written in the console.

Here is a list of all the new or updated articles in this version.

• ILocalizationServices

• Coming soon

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

Enable the unattended upgrade feature

1. Add the Umbraco:Cms:Unattended:UpgradeUnattended configuration key.

2. Set the value of the key to true.

{
    "Umbraco": {
        "CMS": {
            "Unattended": {
                "UpgradeUnattended": true
            }
        }
    }
}

Run the upgrade

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

Boot order

When the application starts, migrations run in a background service after the web server begins listening. During the migration the RuntimeLevel is Upgrading. The web server is reachable during this time, serving health probe responses and maintenance pages.

Once all migrations complete, the RuntimeLevel transitions to Run and the site operates normally.

While the RuntimeLevel is Upgrading, Umbraco responds differently depending on the request surface:

The returns HTTP 200 during the upgrade, confirming the process is alive. The returns HTTP 503, indicating the site is not yet ready to serve normal traffic.

You can customize the maintenance page shown to frontend visitors by setting the Umbraco:CMS:Global:UpgradingViewPath configuration key. See for details.

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

1. .

2. Deploy to all environments.

3. Set the Umbraco:CMS:Unattended:UpgradeUnattended configuration key to true for the Main server only.

You can use the to let your load balancer detect when each server has completed its upgrade and is ready to receive traffic.

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

Data Types

UploadArticle

The UploadArticle Data Type has the following configuration:

• Property editor: FileUpload

• Accepted file extensions: pdf, docx, doc

The UploadAudio Data Type has the following configuration:

• Property editor: FileUpload

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

The UploadVectorGraphics Data Type has the following configuration:

• Property editor: FileUpload

• Accepted file extensions: svg

The UploadVideo Data Type has the following configuration:

• Property editor: FileUpload

• Accepted file extensions: mp4, webm, ogv

The UmbracoMediaArticle media type has the following properties:

• umbracoFile - Upload File

• umbracoExtension - Label (string)

• umbracoBytes - Label (bigint)

The UmbracoMediaAudio media type has the following properties:

• umbracoFile Upload Audio

• umbracoExtension Label (string)

• umbracoBytes Label (bigint)

The UmbracoMediaVectorGraphics media type has the following properties:

• umbracoFile - Upload Vector Graphics

• umbracoExtension Label (string)

• umbracoBytes Label (bigint)

The UmbracoMediaVideo media type has the following properties:

• umbracoFile - Upload Video

• umbracoExtension - Label (string)

• umbracoBytes - Label (bigint)

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 .

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.

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

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

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

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

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

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

1. Go to and download Visual Studio Code for free.

2. Launch Visual Studio Code once the installation is complete.

3. Click the extensions menu on the left side.

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

1. It allows server-side implementations to be reused for multiple client-side Property Editor UIs.

2. It helps to ensure a better division between client-side and server-side responsibility.

Migration impact for Property Editors

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

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

If the Property Editor is built with a :

1. Assign the package manifest alias to the Data Type EditorUiAlias, and

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

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

If the Property Editor is built with a , we:

1. Assign the Data Editor Alias to the Data Type EditorUiAlias, and

2. Retain the Data Type EditorAlias as-is (which is the Data Editor Alias).

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

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

1. The migrated value of EditorUiAlias as its alias, and

2. The migrated value of EditorAlias as its propertyEditorSchemaAlias (found in the extension meta collection).

For example:

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

1. Manually change the EditorAlias and/or EditorUiAlias directly in the umbracoDataType table, or

2. Create a custom migration to update the properties. See the article for inspiration.

Document Blueprints Overview

A Document Blueprint allows editors to preconfigure a content node. It serves as a reusable starting point when creating new content.

Method 1 – Create a Document Blueprint from the Content Section

1. Go to the Content section and select an existing content node.

2. Click the ... menu next to the node and choose Create Document Blueprint.

1. Enter a Name for the new blueprint.

1. Click Save.

The new blueprint will appear under the Document Blueprints folder in the Settings section.

1. Go to the Settings section.

2. Click the ... menu next to the Document Blueprints tree.

3. Select Create....

1. Choose the Document Type you want to base the blueprint on.

1. Enter a Name for the blueprint.

2. Click Save.

The new blueprint will appear under the Document Blueprints folder in the Settings section.

To edit an existing document blueprint, follow these steps:

1. Go to the Settings section.

2. Open the Document Blueprints folder.

3. Select the blueprint you want to edit.

4. Make your changes.

Once you have created a document blueprint, you can use it to create new content nodes.

To use a document blueprint, follow these steps:

1. Go to the Content section.

2. Click + on the root node and select Create.

1. Select the Document Type that has an associated blueprint.

2. Choose how to create the new content:

   • Use the Document Blueprint

   • Start with a blank node

1. Open your command line.

2. Install the Umbraco templates:

1. Create a new project:

Use this section to follow Umbraco releases and plan your next step.

Find the latest release information, test upcoming versions, or browse older documentation.

• Current release information and release history.

• Guidance for testing the latest release candidate.

Move pages within the website through the tree view. Not all pages can be moved depending on your set-up or page permissions. If you need clarification, contact your system administrator.

You can move a page in two ways:

Option 1

1. Go to Content.

2. Click ... next to the page you wish to move.

3. Select Move to.

A window appears on the right side of the screen. Here, you can choose where you want to move the page in the tree structure.

1. Click Move.

2. A confirmation message appears. Click OK to dismiss the confirmation message.

1. Go to Content.

2. Select the page you wish to move.

3. Click Actions in the top-right corner of the screen.

4. Select Move to from the Actions drop-down menu.

1. A window appears on the right side of the screen. Here, you can choose where you want to move the page in the tree structure.

2. Click Move.

3. A confirmation message appears. Click OK to dismiss the confirmation message.

The pages in Umbraco are placed in the tree structure according to a predefined sort order. The most recently created page is placed at the bottom of the tree structure. You can change the order of the pages by using the Sort function.

You can sort pages in two ways:

Option 1

1. Go to Content.

2. Navigate to the parent node whose child nodes you wish to sort.

3. Click ... next to the page you wish to sort.

4. Select Sort children of.

1. A window appears on the right-side of the screen. Here, you can arrange the child nodes in the order you want by dragging them up or down.

1. Click Save and then Close.

1. Go to Content.

2. Select the parent node whose child nodes you wish to sort.

3. Click Actions in the top-right corner of the screen.

4. Select Sort children of from the Actions drop-down menu.

A window appears on the right-side of the screen. Here, you can arrange the child nodes in the order you want by dragging them up or down.

1. Click Save and then Close.

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.

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

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

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

Follow these steps to create a new Dropdown Data Type:

1. Go to the Settings section within the backoffice.

The standard upgrade instructions still apply to this process as well.

Backup

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

.Net 4.5

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

HTML 5 browser support

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

Breaking changes

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

See the list of breaking changes for more details.

Examine

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

Xml Cache rebuild

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

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

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

• /web.config updates

  • Details are listed here:

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

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.

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

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.

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

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

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

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

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.

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

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

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.

• There is a new ITagService that can be used to query tags

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

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

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

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

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.

When viewing page content in preview mode you have the option to scale the preview window to various device sizes:

1. Once you have finished editing the page content, click Save and preview.

2. Select Fit browser to view the different preview modes.
3. Select the device you would like to scale the preview pane to.

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

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

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

Customize

The Sidebar can be customized to improve the workflow for editors. For more information, see the Extending Overview article.

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

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

How to get started running Umbraco CMS on Linux or macOS

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

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

To do this follow the guide.

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

To create a project, there are two options:

• Continue creating projects using the .NET CLI.

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

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

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

If you prefer using SQL Server as your database, you can either install it locally or run it via .

Logging in

To access the Umbraco Backoffice:

1. Open your web browser and enter your website domain name followed by /umbraco (for example: http://www.company.com/umbraco/). A login screen appears.

2. Enter your Email and Password provided by your system administrator.

3. Click Login.

To log out of the Umbraco Backoffice:

1. Select the profile picture in the top-right of the screen.

2. Click Logout.

After logging in to an Umbraco project you will be presented with a dashboard containing a wide array of buttons and features. Let's quickly go through what each feature does.

By default, there are two dashboards available:

1. The Welcome to Umbraco dashboard provides helpful information about Umbraco.

2. The Redirect URL Management dashboard displays the original and redirected links of the published pages which are moved to a new location in your project.

Schema Alias: Umbraco.EmailAddress

UI Alias: Umb.PropertyEditorUi.EmailAddress

Returns: String

Displays an email address.

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.

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 .

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

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

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

To add a tab, follow these steps:

1. Go to Settings.

2. Create or select a Document Type/Media Type/Member Type

There are four kinds of content in Umbraco:

• The website content that make our the pages on your site exists in the Content section.

• Elements are reusable content items that are managed from the Library section.

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

Within the Info content app for pages you can find the Audit Trail in the History section. Here, you can get a quick overview of the actions performed on that node, by whom, when and any additional comments.

The Audit Trail is useful to find out who made changes on a certain date.

To view the audit trail:

1. Go to the Content section.

Umbraco is set up to automatically log a user out if they have been inactive for over 20 minutes. Don't worry if you are logged out of Umbraco. Log back in using your credentials and continue editing.

Session Timeout Configuration for Developers

The session timeout can be configured in Umbraco's appsettings.json file. You can modify the Timeout setting to extend or reduce the timeout duration based on your site's needs.

Schema Alias: Umbraco.ColorPicker

UI Alias: Umb.PropertyEditorUi.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 is possible to add a label to use with the color.

Data Type Definition Example

Content Example

Example with Models Builder

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

Example without Models Builder

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

Add values programmatically

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

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

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

Content Within the Tree View

When you are looking to edit content, locate the page you want to edit in the Content tree on the left-side of the screen.

To edit existing content, follow these steps:

1. Go to the Content section.

2. Select the page in the section tree you wish to edit. The content of the page is loaded in the right-side editor.

3. Edit the contents of the page.

4. Click Save to save the edits without publishing it.

5. Click Save and preview to preview the changes.

6. Click Save and publish to publish the changes. For more information, see the article.

By default, you can view Page layouts in two ways: in a List or in a Grid (default).

When you enable Collection on a page, its child pages are no longer shown as nested items in the content tree. Instead, the parent page appears as a single node in the tree. Selecting it displays all of its child pages in a grid view within the main workspace area. For more information, see the article.

You can switch to a list view by clicking the layout icon in the top-right of the screen:

Schema Alias: Umbraco.Decimal

UI Alias: Umb.PropertyEditorUi.Decimal

Returns: decimal

Data Type Definition Example

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

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

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

Content Example

MVC View Example

With Models Builder

@Model.MyDecimal

Without Models Builder

@Model.Value("MyDecimal")

Add values programmatically

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

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

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

Schema Alias: Umbraco.Label

UI Alias: Umb.PropertyEditorUi.Label

Returns: String

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

Data Type Definition Example

Value type

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

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

Content Example

MVC View Example

Without Models Builder

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

With Models Builder

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

Add values programmatically

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

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

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

A Property Editor is what content editors use to input data on a Document Type. When you create a Data Type in the backoffice, you choose a Property Editor and configure it. Umbraco ships with a wide range of built-in Property Editors, and you can create custom ones.

In this section

• Built-in Property Editors - the full list of Property Editors that ship with Umbraco.

• Umbraco Flavored Markdown - a Markdown dialect with Umbraco-specific extensions for rich content editing.

Related Resources

This section provides a few handy tips to work with your Content using Umbraco:

• Audit Trail

• Notifications

Use this section to get involved with the Umbraco ecosystem.

Find contribution guidelines and practical resources for responsible delivery.

In this section

• Ways to contribute to Umbraco documentation and community work.

• Guidance for building and maintaining more sustainable solutions.

Schema Alias: Umbraco.TimeOnly

UI Alias: Umb.PropertyEditorUi.TimeOnlyPicker

Returns: TimeOnly?

The Time Only property editor provides an interface for selecting times. It excludes date and time zone information, and returns strongly-typed TimeOnly values.

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

To set up a property using this editor, create a new Data Type and select Time Only from the list of available property editors.

Downgrades are not a supported feature of the Umbraco product.

The primary reason for this is that the Umbraco migration scheme only supports upward migrations.

When updating to a new version, often there are migrations to run that will make changes to the Umbraco schema and data. This is being done to bring the database to a state that will support the functionality of the version being upgraded to.

There isn't an equivalent downward migration that will undo these changes.

Given that, it can't be guaranteed that a database from a later version will work with an earlier one.

If you wish to downgrade to an earlier version of Umbraco, it's best to also revert to a compatible database backup. You will need one from the version you are downgrading to.

Other factors that may preclude downgrading include packages you may be using. They may not be compatible with the lower version or support downgrades themselves.

That said, between some versions, a downgrade may be possible and perfectly safe. There may be no migrations that run between them. Or, as is often the case, migrations are backward compatible (for example, adding a new, nullable field to a database table).

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

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

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

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

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

Schema Alias: Umbraco.MemberGroupPicker

UI Alias: Umb.PropertyEditorUi.MemberGroupPicker

Returns: string

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

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 .

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

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

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

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

This is known as Block Level Variance:

Block Level Variance is achieved when:

• The

Schema Alias: Umbraco.ElementPicker

UI Alias: Umb.PropertyEditorUi.ElementPicker

Returns: IEnumerable<IPublishedElement>

The Element Picker enables you to choose one or more elements to display as part of your content. Elements are based on defined in the Settings section. They are created and managed in the Library section.

Define how many elements should be allowed to pick via the Element Picker.

Choose a start node for the Element Picker. Use this option when your Library section is organized into folders.

In Umbraco, all content is defined by a type. Document Types define the fields on a page, Media Types define the properties of media items, and Member Types define user profiles. This section covers how to create and configure these content types and how to build structure through compositions and relations.

• - key backoffice concepts: sections, trees, Document Types, Media Types, Data Types, and Property Editors.

• - define Document Types, create Media Types, configure Data Types, and manage content in the backoffice.