Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Information on the requirements to setup, install & upgrade Umbraco
How to install and configure your Umbraco installation.
Defines the system requirements to run Umbraco.
Umbraco installation steps and guidelines.
Covers the steps to upgrade your copy of Umbraco to a newer version.
Information about server setup for Umbraco including information about permissions and load balancing.
How to configure your Umbraco installation. Includes information about all of Umbraco's configuration files and options.
How to install the latest nightly builds.
Instructions on installing Umbraco on various platforms using various tools.
The fastest way to get the latest version of Umbraco up and running is using the command line (CLI).
Open your command line.
Install the Umbraco templates:
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.
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.
Learn how to run an already installed local installation of Umbraco.
Visual Studio Code is an editor with an embedded webserver (through the IIS Express extension). A fast way to get you up and running with Umbraco.
From Umbraco v9 and above you can use the Nightly Builds to get the latest version to use and test before it is released. Learn how to install the Nightly builds to get started.
Since Umbraco 9 it has been possible to run Umbraco CMS natively on Linux or macOS High Sierra. To get Umbraco running you will need to follow some steps.
Use the Unattended installs when spinning up Umbraco instances on something like Azure Web Apps to avoid having to run through the installation wizard.
The Umbraco UI should work in all modern browsers:
Chrome (Latest)
Edge (Chromium)
Firefox (Latest)
Safari (Latest)
Below you can find the minimum requirements to run Umbraco 10 on your machine:
One of the .NET 6 - Supported OS versions
One of the following .NET Tools or Editors:
Visual Studio Code with the IISExpress extension
Microsoft Visual Studio 2022 version 17.0 or higher.
Optional: JetBrains Rider version 2022.3 and higher
When using Visual Studio as your primary Integrated Development Environment (IDE) we recommend finding and downloading the Software Development Kits (SDKs) for Visual Studio.
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 latest and supported Microsoft versions to run and host Umbraco CMS:
Ubuntu Supported distributions and other Linux Packages
For the above, as Umbraco version 10 is based on .NET 6 you will need to follow the .NET 6 supported versions.
As Umbraco version 10 is based on .NET 6 follow the requirements for .NET 6.
For more information, see the Host and deploy ASP.NET Core applications article in the Microsoft documentation.
You can use Umbraco Cloud to manage the hosting infrastructure. All Umbraco Cloud plans are hosted on Microsoft Azure, which gives your site a proven and solid foundation.
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.
The database account used in the connection string will need permissions to read and write from tables. It will also require permission to create schema during installs and upgrades:
The db_owner
role has full permissions on the database.
To use an account with more restricted permissions, the db_datareader
and db_datawriter
roles will be needed for normal use to read from and write to the database. The db_ddladmin
role, which can modify the database schema, is required for installs and upgrades of the CMS and/or any packages that create database tables.
For more information on the Database-level roles, see the Microsoft documentation.
For more information on how to create a database user via SQL, you can check the Microsoft documentation.
A guide to install Umbraco CMS using Visual Studio.
Install the newest Umbraco dotnet templates.
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 .NET CLI Templates in Visual Studio article.
Check the Requirements to ensure you have everything you need to start your Umbraco project.
This is an abbreviated version of the installation steps. Jump to the Create a new project section for a more thorough guide.
Open Visual Studio.
Go to File
> New
> Project
, search for Umbraco.
Choose Umbraco Project (Umbraco HQ) then click Next.
Choose or specify the parameters, leave the default or leave them all empty.
Click Create.
Use CTRL+F5 to run the project and start the Umbraco installer.
To install Umbraco we first need to install Umbraco's dotnet new templates.
For more information check the first 2 steps of the Install Umbraco with .NET CLI article.
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 selecting Next.
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.
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.
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.
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.
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 a new empty Umbraco solution using MS SQL Azure/Server:
dotnet new umbraco -n MyCustomUmbracoProject
You will now have a new project with the name MyCustomUmbracoProject, or the name you chose to use. The new project can be opened and run using your favorite IDE or you can continue using the CLI commands.
If you want to create a solution file as well you can run the commands below.
dotnet new sln
dotnet sln add MyCustomUmbracoProject
Navigate to the newly created project folder:
cd MyCustomUmbracoProject
Build and run the new Umbraco .Net Core project:
dotnet build
dotnet run
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.
Since Umbraco 9 it has been possible to run Umbraco CMS natively on Linux/macOS.
With Umbraco CMS on .NET Core, Linux/macOS is natively supported with SQLite as the database.
In the below section, we describe how to get started with running Umbraco CMS.
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.
To create new projects using Visual Studio, you can use the guide.
Once you create a new project it will use SQLite by default.
If you want to use an SQL server database, you will need to .
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.
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.
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.
At this point you can go to your Visual Studio solution of the site and in the Properties
folder there is a launchSettings.json
file, that looks like this:
You can add a new profile called IIS, and point it at your local domain. Here it is with my example domain:
At this point IIS will be added to the launch profiles, and you can run the site from Visual Studio by choosing IIS in the dropdown:
And finally the site is running from your local IIS:
Follow these steps to set up an Umbraco project with VS Code. The benefit of using VS Code is that it is super quick to get up and running.
Go to and download VS Code for free.
Once installed, launch VS Code.
Click the extensions menu at the bottom on the left side. Then search for C#, install it then press reload.
Open your project folder in VS Code, your project will look something like this:
Now we need to tell VS Code how to run your project.
Open the command palette, you can use the shortcut Ctrl+Shift+P
, and type in Tasks: Configure
and select the Tasks: Configure Task
option:
Select "Create task.json from template"
Now select ".NET Core" as your template.
After this VS Code will have created a folder called .vscode
that contains a file called tasks.json
, it's this file that tells VS Code how to build your project.
Now that we've told VS Code how to build your project, we need to tell it how to launch it. VS Code can do this for you. First, select the little play button in the left side menu, and then select the "create a launch.json file" link.
This will prompt a menu to appear, select .NET 5+ and .NET Core:
If .NET 5+ and .NET Core is missing in the drop-down menu:
Press Ctrl + Shift + P (on Windows/Linux) or Cmd + Shift + P (on macOS) to open the Command Palette.
Search for the command .NET: Generate Assets for Build and Debug
. This command will generate the necessary assets for building and debugging your .NET application.
Now you'll see a green play button appear with a dropdown where ".NET Core Launch" is selected.
If you navigate to the Files section, a new launch.json
file is created in the .vscode
folder. When you press F5, the launch.json
file tells VS Code to build your project, run it, and then open a browser .
With that, you're ready to run the project! Press F5, or click the little green play button in the Run and Debug section to run your brand new Umbraco site locally.
This section continues from where we left off but covers the installation and configuration of Umbraco inside your web browser when you run Umbraco for the first time.
You will see the install screen where you will need to fill in some data before Umbraco can be installed.
When the installer is done you will automatically 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/.
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.
In order to get a clean instance of Umbraco, follow our installation guide for how to .
As you will not be running through the installation wizard when using this feature, you need to manually tell Umbraco which database to use.
Set up and configure a new database - see for details.
Add the connection string using configuration.
Umbraco can create an SQL Server database for you during the unattended install process. The user specified by the credentials in your connection string needs to have the CREATE DATABASE
permission granted and the global setting is set to true
.
If your connection string is for SQLite or SQL Server Express LocalDB it is assumed that a database should be created when missing. This is regardless of the value of the InstallMissingDatabase
setting.
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.
The unattended installs feature is disabled by default. In order to enable it, you need to add the following JSON object to a JSON configuration source.
Remember to set the value of InstallUnattended
to true
.
The keys for this would then be as follows:
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.
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.
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:
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:
The NuGet feed containing the nightly builds is https://www.myget.org/F/umbraconightly/api/v3/index.json
.
You can either add this feed through the command line or use an IDE of your choice. In this article, we'll provide steps for:
To add the nightly feed using the command line:
Open a command prompt of your choice.
Run the following command:
Now the feed is added as a source named Umbraco Nightly
.
To add the nightly feed using Visual Studio:
Open Visual Studio.
Go to Tools > NuGet Package Manager > Package Manager Settings.
The Options window open.
Select the Package Sources option in the NuGet Package Manager section.
Click the +
icon.
A new Package source will be added automatically and highlighted.
Enter the desired name for the feed in the Name field.
Enter the link https://www.myget.org/F/umbraconightly/api/v3/index.json
into the Source field.
Click OK.
Now the feed is added as a source named Umbraco Nightly
.
To add the nightly feed using Rider:
Open Rider.
Go to View > Tool Windows > NuGet.
Go to Sources tab.
Choose the C:\Users\Úmbraco\AppData\Roaming\NuGet\NuGet.Config
to add the feed globally.
Cick the green +
button in the New Feed field.
The New feed dialog opens.
Enter the desired name in the Name field.
Enter https://www.myget.org/F/umbraconightly/api/v3/index.json
in the URL field.
Leave the User, Password fields empty, and the Enabled checkbox ticked.
Click OK.
Now the feed is added as a source named Umbraco Nightly
.
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:
You can use the package manager in Visual Studio to browse the available template versions.
Open Visual Studio.
Go to Tools > NuGet Package Manager > Manage NuGet Packages For Solution...
Select Umbraco Nightly from the Package source dropdown in the NuGet - Solution window.
Check the Include prerelease checkbox.
Search for Umbraco.Templates in the Browse field.
Choose that package.
Click on the Version dropdown and see the available nightly builds.
Choose the applicable version and note down the version number.
You can use the NuGet window in Rider to browse the available template versions.
Open Rider.
Go to the Packages tab in the NuGet window..
Select Umbraco Nightly from the All Feeds dropdown.
Check the Prerelase checkbox.
Search for Umbraco.Templates in the Search field.
Choose that package.
Click on the Version drop down and see the available nightly builds.
Choose the applicable version and note down the version number
Now that our feed is added and we know the exact version we're ready to install our template.
To install the latest nightly version template:
Open your command prompt.
Run the following command using the latest version:
With that, we've successfully installed the latest nightly build of Umbraco.
All we have to do now is to create a site using the dotnet new umbraco -n MyAwesomeNightlySite
command.
Install the latest .
Run dotnet new install Umbraco.Templates
to install the project templates.
The solution is packaged up into the NuGet package and can be installed into the dotnet CLI.
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.
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.
Follow the to create your project folder.
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 .
Alternatively you may set your configuration with Environment Variables or other means. Learn more about this in the .
For more information about installing Umbraco, see the article.
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.
It is necessary to run the upgrade installer on each environment of your Umbraco site. If you want to update your staging and live site you need to repeat the steps below. Make sure you click through the install screens so that your upgrade is complete.
In this article you will find instructions for 3 different ways of upgrading:
Open up the Package Console and type: Update-Package UmbracoCms
Choose "No to All" by pressing the "L" when prompted.
If there are any specific configuration changes required for the version you are upgrading to then they will be noted in the version-specific guide.
Alternatively, you can use the Visual Studio NuGet Package Manager to upgrade:
Open the NuGet Package Manager and select the Updates pane to get a list of available updates.
Choose the package called UmbracoCms and select update.
The upgrade will run through all the files and make sure you have the latest changes while leaving files you have updated.
Download the .zip
file for the new version you are upgrading to from https://our.umbraco.com/download
Copy the following folders from inside the .zip
file over the existing folders in your site:
/bin
/Umbraco
There are hosting providers (we know of one: RackSpace Cloud) that require proper casing of file and folder names. Normally on Windows this is not a problem. If your hosting provider however forces proper casing, you will need to verify that the folder and file names are in the same casing as in the newest version you're upgrading to.
You can expect some changes to the following configuration files:
Any file in the /Config
folder
The /Global.asax
file
The web.config
file in the root of your site (Important: make sure to copy back the version number, and the connection string as they were.)
In rare cases, the web.config
file in the /Views
folder
Use a tool like WinMerge to check changes between all of the config files. Depending on when you last did this there may have been updates to few of them.
There's also the possibility that some files in the /Config
folder are new or some have been removed (we do make a note of this in the release notes). WinMerge (and other diff tools) can compare folders as well so you can spot these differences.
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
).
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.
When upgrading your Umbraco project to Umbraco v8.12+ it is possible to enable the upgrade to run unattended. This means that you will not need to run through the installation wizard when upgrading.
Below you will find the steps you need to take in order to upgrade your project unattended.
Are you running a load balanced setup with multiple servers and environments?
Check out the section about Unattended upgrades in a load balanced setup.
Add the Umbraco.Core.RuntimeState.UpgradeUnattended
key to appSettings
in your web.config file.
Set the value of the key to true
.
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.
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.
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.
Follow the steps outlined below to use run unattended upgrades in a load balanced setup.
Upgrade Umbraco via NuGet in Visual Studio. Make sure the Umbraco.Core.ConfigurationStatus
key in appSetting
in the web.config
file is updated to match the target version.
Deploy to all environments, including the updated appSetting
for Umbraco.Core.ConfigurationStatus
.
Set the Umbraco.Core.RuntimeState.UpgradeUnattended
key in appSetting
in the web.config
to true
for the Main server only.
Request a page on the Main server and the upgrade will run automatically.
Wait for the upgrade to complete.
Browse the Read-Only servers and make sure they do not show the “upgrade required” screen.
One important recommendation is to always remove the install
folder immediately after upgrading Umbraco and never to upload it to a live server.
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.
This document should be used as a reference, not a step by step guide. Upgrading will largely depend on what version of Umbraco you are currently running, what packages you have installed and the many
The standard upgrade instructions still apply to this process as well.
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.
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.
Umbraco 7 requires browsers with proper HTML 5 support, these include Chrome, Firefox, IE10+
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.
It is recommended to rebuild all Examine indexes after completing the upgrade.
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: https://issues.umbraco.org/issue/U4-2900
You will need to compare the new Umbraco 7 web.config
with your current web.config
. Here is a quick reference of what needs to change:
Remove the section name="BaseRestExtensions"
section
Remove the section name="FileSystemProviders"
section
Remove the sectionGroup name="system.web.webPages.razor"
section
Remove the <FileSystemProviders>
element
Remove the BaseRestExtensions
element
Remove the add key="umbracoUseMediumTrust"
element
Remove the system.web.extensions
element
Removes the xhtmlConformance
element
Remove the system.codedom
element
Remove the compilation
assemblies, /compilation
Remove the system.web.webPages.razor
element
New: sectionGroup name="umbracoConfiguration"
section
New: umbracoConfiguration
element
Ensure that the targetFramework="4.5"
is added to the httpRuntime
element
Add add key="ValidationSettings:UnobtrusiveValidationMode" value="None"
to the appSettings
element
/config/clientdependency.config
changes
remove add name="CanvasProvider"
element
/views/web.config
updates
New macroscripts/web.config
config/umbracoSettings.config
Umbraco is now shipped with minimal settings but the full settings are still available
umbracoSettings
is now a true ASP.NET configuration section https://issues.umbraco.org/issue/U4-58
Remove the EnableCanvasEditing
element
Remove the webservices
element
Removed xsltExtensions.config
/config/applications.config
and /config/trees.config
have some icon paths and names updated. You need to merge the new changes into your existing config files.
/config/tinyMceConfig.config
The inlinepopups
is compatible and supported in Umbraco 7. You need to remove these elements: plugin loadOnFrontend="true"
, inlinepopups/plugin
;
The plugins element that is shipped with Umbraco 7 looks like this:
You need to merge the changes from the new tinyMceConfig
file into yours. The command
elements that have changed are: JustifyCenter
, JustifyLeft
, JustifyRight
, JustifyFull
, umbracomacro
, umbracoembed
, mceImage
, subscript
, superscript
, styleselect
Remove the command: mceSpellCheck
/config/dashboard.config
You need to merge the changes from the new dashboard.config
into yours. Some of the original dashboard entries that were shipped with Umbraco 6 have been replaced or removed.
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
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
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.
This document covers specific upgrade steps if a version requires them. Most versions do not require specific upgrade steps and you will be able to upgrade directly from your current version.
Use the information below to learn about any potential breaking changes and common pitfalls when upgrading your Umbraco CMS project.
If any specific steps are involved with upgrading to a specific version, they will be listed below.
Use the general upgrade guide to complete the upgrade of your project.
You can find a list of all the released Umbraco versions on Our Umbraco website. When you visit Our Umbraco website, click on the version number to view the changes made in that specific version.
Are you looking to upgrade an Umbraco Cloud project from 9 to 10? Follow the guide made for Upgrading your project from Umbraco 9 to 10 instead, as it requires a few steps specific to Umbraco Cloud.
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 version-specific guide. Be sure to read this article before moving on.
Check if your setup meets the requirements for the new versions you will be upgrading your project to.
Things may go wrong for different reasons. Be sure to ALWAYS keep a backup of both your site's files and the database. This way you can always return to a version that you know works.
Before upgrading to a new major version, check if the packages you're using are compatible with the version you're upgrading to. On the package's download page, in the Project compatibility area, click View details to check version-specific compatibility.
It is necessary to run the upgrade installer on each environment of your Umbraco site. This means that you need to repeat the steps below on each of your environments in order to complete the upgrade.
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:
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.
Use the table below to determine which .NET version to upgrade to when going through the steps below.
It's recommended that you upgrade the site offline and test the upgrade fully before deploying it to the production environment.
Stop your site in IIS to prevent any changes from being made while you are upgrading.
Open your Umbraco project in Visual Studio.
Right-click on the project name in the Solution Explorer and select Properties.
Select the .NET version from the Target Framework drop-down.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
Go to the Installed tab in the NuGet Package manager.
Upgrade Umbraco.Cms.
a. Select the correct version from the Version drop-down.
b. Click Install to upgrade your project.
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 version specific upgrade notes for Umbraco Forms if relevant.
Make sure that your connection string has TrustServerCertificate=True
in order to complete successfully the upgrade:
Restart your site in IIS, build, and run your project to finish the installation.
If your database experiences timeout issues after an upgrade, it might be due to ASP.NET Core Module's 'startupTimeLimit' configuration.
To fix the issue, try increasing the startupTimeLimit
in the web.config
file. Additionally, you can set the Connection Timeout
value in the ConnectionString
in the appsettings.json
file.
NuGet installs the latest version of the package when you use the dotnet add package
command unless you specify a package version:
dotnet add package Umbraco.Cms --version <VERSION>
Add a package reference to your project by executing the dotnet add package Umbraco.Cms
command in the directory that contains your project file.
Run dotnet restore
to install the package.
For v9: If you are using SQL CE in your project you will need to run dotnet add package Umbraco.Cms.SqlCe --version <VERSION>
before running the dotnet restore
command. From v10, SQL CE has been replaced with SQLite so a dotnet restore
should be sufficient. If this is not working then you will need to run dotnet add package Umbraco.Cms.Persistence.Sqlite --version <VERSION>
and then dotnet restore
.
When the command completes, open the .csproj file to make sure the package reference was updated:
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 Unattended upgrades in a load balanced setup.
Add the Umbraco:Cms:Unattended:UpgradeUnattended
configuration key.
Set the value of the key to true
.
With the correct configuration applied, the project will be upgraded on the next boot.
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.
Follow the steps outlined below to use unattended upgrades in a load balanced setup.
Upgrade Umbraco via NuGet (see instructions above)
Deploy to all environments.
Set the Umbraco:CMS:Unattended:UpgradeUnattended
configuration key to true
for the Main server only.
Boot the Main server and the upgrade will run automatically.
Wait for the upgrade to complete.
Boot the Read-Only servers and make sure they do not show the “upgrade required” screen.
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.
Migrating Umbraco Cloud sites
Follow the steps outlined in the Umbraco Cloud documentation to upgrade your Umbraco 7 site on Cloud.
In the following section, you can learn more about the limitations of migrating content from Umbraco 7 to Umbraco 8.
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.
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.
Feedback from user testing has shown that some databases are harder to migrate than others.
We are collecting a list of these known issues on our GitHub Issue Tracker. There is a community package: Pre-migration health checks that you can install on your Umbraco 7 site before migration. This will help identify and resolve some of these common issues before triggering the migration steps detailed below.
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: ProWorks Umbraco 8 Migrations into your Umbraco 8 project before running the migration (no configuration required). This package was created by Umbraco Gold Partner ProWorks and patches the migration process so you can migrate directly from the latest Umbraco 7 to Umbraco 8.6+ without encountering the above issue. Learn more about the package and the migration process on Prowork's blog.
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.
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)
In the following guide we will migrate the content of an Umbraco 7.13.1 site to Umbraco 8.1.0.
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.
Following the general upgrade instructions we will now upgrade via Nuget until we get to this point:
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.
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.
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.
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:
From here, the automatic migration will take over, and after a little bit you can log in and see your content:
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.
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.
If you're stopping at Umbraco 8, you can learn more about rendering content on the Legacy Docs site.
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 more about the Section in the Sections article
This section describes how to use the runtime mode setting to optimize Umbraco for the best development experience or optimal production environment.
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:
BackofficeDevelopment
(default)
Development
Production
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
).
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.
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).
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.
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
.
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 are set to Nothing
, the Models Builder dashboard is disabled in the backoffice of live environment.
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.
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
:
Learn how to upgrade your Umbraco 8 project to Umbraco 10.
It is currently not possible to upgrade directly from Umbraco 8 to the latest version.
The recommended approach for upgrading from version 8 to the latest version is to use this guide to upgrade from Umbraco 8 to Umbraco 10. Umbraco 10 contains the database migrations that must be upgraded from Umbraco 8. You can then use the Upgrading to Major steps to upgrade from Umbraco 10 to the latest version.
Since the underlying framework going from Umbraco 8 to the latest version has changed, there is no direct upgrade path. That said, it is possible to re-use the database from your Umbraco 8 project on your new project in order to maintain the content.
It is not possible to migrate the custom code as the underlying web framework has been updated from ASP.NET to ASP.NET Core. All templates and custom code will need to be reimplemented.
You also need to make sure that the packages you are using are available on the latest version.
A Umbraco 8 project running the latest version of Umbraco 8.
A clean installation of the latest version of Umbraco.
A backup of your Umbraco 8 project database.
If you use Umbraco Forms, then on the clean installation of Umbraco, you will need to install Umbraco.Forms
package as well.
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.
If you use Umbraco Forms, make sure to have StoreUmbracoFormsInDbset
to True
before step 1.
Create a backup of the database from your Umbraco 8 project (after you have upgraded to the latest version of v8). For this, you can use the 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.
The following files/folders need to be copied from the Umbraco 8 project into the new project:
~/Views
- Do not overwrite the default Macro and Partial View Macro files unless changes have been made to these.
~/Media
- Media folder from v8 needs to be copied over into the wwwroot - media
folder
Any files/folders related to Stylesheets and JavaScript.
Migrate custom configuration from the Umbraco 8 configuration files (.config
) into the appsettings.json
file on the new project.
As of Umbraco version 9, the configuration no longer lives in the Web.Config
file and has been replaced by the appsettings.json
file. Learn more about this in the Configuration article.
Migrate Umbraco Forms data to the database, if relevant.
As of Umbraco Forms version 9, it is only possible to store Forms data in the database. If Umbraco Forms was used on the Umbraco 8 project, the files need to be migrated to the database.
Run the new project.
It will give you an error screen on the frontend as none of the Template files have been updated.
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 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.
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
We strongly encourage the use of HTTPS with Umbraco installations especially in production environments. Using HTTPS will greatly enhance the security of your website, see the for more information.
To ensure a stable and smoothly running Umbraco installation, these permissions need to be set correctly.
Information about hosting a v9 application using IIS.
Information on how to deploy Umbraco in a Load Balanced scenario and other details to consider when setting up Umbraco for load balancing.
Best practices for running Umbraco on Azure Web Apps.
The runtime mode setting optimizes Umbraco for the best development experience or optimal production environment.
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 |
---|
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 .
It is necessary to run the upgrade installer on each environment of your Umbraco site. If you want to update your staging and live site then you need to repeat the steps below and make sure that you click through the install screens to complete the upgrade.
In this article you will find instructions for 2 different ways of upgrading:
Open up the Package Console and type: Update-Package UmbracoCms
Choose "No to All" by pressing the "L" when prompted.
If there are any specific configuration changes required for the version you are upgrading to then they will be noted in the .
Alternatively, you can use the Visual Studio NuGet Package Manager to upgrade:
Open the NuGet Package Manager and select the Updates pane to get a list of available updates.
Choose the package called UmbracoCms and select update.
The upgrade will run through all the files and make sure you have the latest changes while leaving the files you have updated.
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.
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.
You can expect some changes to the following configuration files:
Any file in the /Config
folder
The /Global.asax
file
The web.config
file in the root of your site (Important: make sure to copy back the version number, and the connection string as they were.)
In rare cases, the web.config
file in the Views folder
There's also the possibility that files in the /Config
folder are new or have been removed(we note this in the release notes). WinMerge (and other diff tools) is able to compare folders as well so you can spot these differences.
Up until version 6.0.0 it was necessary to change the version number in ClientDependency.config
. This was to clear the cached HTML/CSS/JS files in the backoffice. Change the current version number to one that's higher than that. Make sure not to skip this step as you might get strange behavior in the backoffice otherwise.
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
).
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.
One important recommendation is to always remove the install
folder immediately after upgrading Umbraco and never to upload it to a live server.
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.
Information on hosting Umbraco v9+ on IIS
Install the and download the Hosting Bundle. Ensure you download the correct .NET version as per the .
Once you have the hosting bundle installed and have restarted IIS (net stop was /y
followed by net start w3svc
), create a site in IIS as you would for a v8 site, however you need to ensure that ".NET CLR version" is set to "No Managed Code" for the Application Pool.
You can use the dotnet CLI to compile and collate all files required for hosting
Alternatively you can use folder or ftp publishing in Visual Studio to compile and collate all required files to for the application to run.
In Visual Studio right click on Umbraco web project in the Solution Explorer and choose Publish... command.
Deploy a website for automated deployment with Azure DevOps to IIS
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 and not the website's web.config. The web.config might end in a public repository and should not contain sensitive data like Connection Strings or SMTP configuration with username and password. Additionally by default the web.config 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. E.g. 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 can host .NET 5 applications using 2 different hosting models
In-process hosting runs an .NET 5 app in the same process as its IIS worker process
Out-of-process .NET 5 apps run in a separate from the IIS worker process. The module controls the management of the Kestrel server and requests are proxied between them.
This section describes best practices with running Umbraco on 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.
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.
The minimum recommended Azure SQL Tier is "S2", however noticeable performance improvements are seen in higher Tiers
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.
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.
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.
CMS version | .NET version |
---|---|
This mode disables both in-memory ModelsBuilder generation (see ) 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:
To compile your views at build/publish time, remove the <RazorCompileOnBuild>
and <RazorCompileOnPublish>
properties from your project file (see the section). If you don't, Umbraco can't find the templates and will return 404 (Page Not Found) errors.
Also, templates cannot be edited on live environment as runtime compilation is not enabled and is set to Production.
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 .
Download the .zip file for the new version you are upgrading to from
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.
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.
- to enable this model you need to edit your .csproj file and add:
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.
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.
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.
Consult the if you would like to directly reference Azure Key Vault Secrets to your Azure Web App.
12
7.0
11
7.0
10
6.0.5
| Modify / Full control | Only needed for setting database and a global identifier during installation. So can be set to read-only afterwards for enhanced security. |
| Modify / Full control | Should always have modify rights as the folder and its files are used by packages. Not part of your project by default. |
| Modify / Full control | Should always have modify rights as the folder and its files are used for cache and storage. |
| Modify / Full control | Should always have modify rights as the folder and its files are used for Templates, Partial views, and Macro files. |
| Modify / Full control | Should always have modify rights as the folder and its files are used for CSS files. |
| Modify / Full control | Should always have modify rights as the folder and its files are used for Media files uploaded via the Umbraco CMS backoffice. |
| Modify / Full control | Should always have modify rights as the folder and its files are used for script files. |
Umbraco v8+ uses Serilog for logging. When load balancing Umbraco consideration should be given as to how the log files from each server will be accessed.
There are many Serilog Sinks available. One of these may be appropriate to store logs for all servers in a central repository such as Azure Application Insights or Elmah.io.
For more information, see SeriLog Provided Sinks.
No file replication is configured, deployment handles updating files on the different servers.
If the file system on your servers isn't performing any file replication then no Umbraco configuration file changes are necessary. However Media will need to be configured to use a shared location such as Blob storage or S3.
Depending on the configuration and performance of the environment's local storage you might need to consider Examine Directory Factory Options and the Umbraco temporary storage location.
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.
A common way to replicate files on Windows Server is to use [DFS](https://msdn.microsoft.com/en-us/library/windows/desktop/bb540031(v=vs.85), which is included with Windows Server.
Additional DFS resources:
There are other alternatives for file replication out there, some free and some licensed. You'll need to decide which solution is best for your environment.
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 configuration is pretty straightforward with file replication. IIS is only reading files from its own file system like a normal IIS website.
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
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.
Once you are familiar with how flexible load balancing works, you might be interested in some advanced techniques.
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.
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.
The single instance Backoffice Administrative Web App should be set to use SyncedTempFileSystemDirectoryFactory.
The multi-instance Scalable Public Web App should be set to use TempFileSystemDirectoryFactory.
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 .NET Host.
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.
AppDomain synchronization
Each application runs inside an AppDomain which is like a subprocess within the web app process. When an ASP.Net application restarts, the current AppDomain 'winds down' while another AppDomain is started; meaning there can be more than 1 live AppDomain 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 AppDomain at once. Umbraco manages this synchronization by an object called IMainDom
. By default, this uses a system-wide locking mechanism but this default mechanism doesn't work in Azure Web Apps so we need to swap it out for an alternative database locking mechanism by using the following appSetting:
Apply this setting to both the SCHEDULINGPUBLISHER Administrative server and the SUBSCRIBER scalable public-facing servers.
Create an Azure SQL database
Install Umbraco on your backoffice administrative environment and ensure to use your Azure SQL Database
Install Umbraco on your scalable public-facing environment and ensure to use your Azure SQL Database
Test: Perform some content updates on the administrative environment, ensure they work successfully in that environment, then verify that those changes appear on the scalable public-facing environment
Fix the backoffice environment to be the SCHEDULINGPUBLISHER scheduling server and the scalable public-facing environment to be SUBSCRIBERs - see Setting Explicit Server Roles
Ensure all Azure resources are in the same region to avoid connection lag.
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.
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.
This describes some more advanced techniques that you could achieve with flexible load balancing
The election process that runs during the startup of an Umbraco instance determines the server role that instance will undertake.
There are two server roles to be aware of for flexible load balancing:
SchedulingPublisher
- The Umbraco instance usually used for backoffice access, responsible for running scheduled tasks.
Subscriber
- A scalable instance that subscribes to content updates from the SchedulingPublisher server, not recommended to be used for backoffice access.
These new terms replace 'Master and Replica', in Umbraco versions 7 and 8.
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.
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.
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.
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.
Configuring and setting up a load balanced server environment requires planning, design and testing. This document should assist you in setting up your servers, load balanced environment and Umbraco configuration.
This document assumes that you have a fair amount of knowledge about:
Umbraco
IIS 10+
Networking & DNS
Windows Server
.NET5+
It is highly recommended that you setup your staging environment to also be load balanced so that you can run all of your testing on a similar environment to your live environment.
These instructions make the following assumptions:
All web servers can communicate with the database where Umbraco data is stored
You are running Umbraco 9.0.0 or above
You will designate a single server to be the backoffice server for which your editors will log into for editing content. Umbraco will not work correctly if the backoffice is behind the load balancer.
There are three design alternatives you can use to effectively load balance servers:
You use cloud based auto-scaling appliances like Microsoft's Azure Web Apps
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.
In order to understand how to host your site it is best to understand how Umbraco's flexible load balancing works.
The following diagram shows the data flow/communication between each item in the environment:
The process is as follows:
Administrators and editors create, update, delete data/content on the backoffice server
These events are converted into data structures called "instructions" and are stored in the database in a queue
Each front-end server checks to see if there are any outstanding instructions it hasn't processed yet
When a front-end server detects that there are pending instructions, it downloads them and processes them and in turn updates it's cache, cache files and indexes on its own file system
There can be a delay between content updates and a front-end server's refreshing, this is expected and normal behaviour.
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
Umbraco will automatically elect a "Scheduling server" to perform the above services. This means that all of the servers will need to be able to resolve the URL of either: itself, the Backoffice server, the internal load balancer, or the public address.
There are two server roles:
SchedulingPublisher
- Usually this is the backoffice instance.
Subscriber
- These are the scalable front-end instances - not recommended to be used for backoffice access.
These new terms replace 'Master and Replica', in Umbraco versions 7 and 8.
Each instance will be allocated a role by the automatic server role election process, but they can also be set explicitly (recommended)
For example, In the following diagram the node f02.mysite.local is the elected "Scheduling server". In order for scheduling to work it needs to be able to send requests to itself, the Backoffice server, the internal load balancer or the public address. The address used by the "Scheduling server" is called the "umbracoApplicationUrl".
By default, Umbraco will set the "umbracoApplicationUrl" to the address made by the first accepted request when the AppDomain starts. It is assumed that this address will be a DNS address that the server can resolve.
For example, if a public request reached the load balancer on www.mysite.com
, the load balancer may send the request on to the servers with the original address: www.mysite.com
. By default the "umbracoApplicationUrl" will be www.mysite.com
. However, load balancers may route the request internally under a different DNS name such as "f02.mysite.local" which by default would mean the "umbracoApplicationUrl" is "f02.mysite.local". In any case the elected "Scheduling server" must be able to resolve this address.
In many scenarios this is fine, but in case this is not adequate there's a few of options you can use:
Recommended: set your front-end(s) (non-admin server) to be explicit subscriber servers by creating a custom IServerRegistrar
, this means the front-end servers will never be used as the SchedulingPublisher server role.
Set the UmbracoApplicationUrl
property in the WebRouting section of the CMS config
The below section applies to all ASP.NET load balancing configurations.
This section describes the configuration options depending on your hosting setup:
Azure Web Apps - You use cloud based auto-scaling appliances like Microsoft's Azure Web Apps
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)
Full documentation is available here
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.
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.
There are some logging configurations to take into account no matter what type of load balancing environment you are using.
Full documentation is available here
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.
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.
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.