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...
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...
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...
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.
How to install the latest nightly builds.
This is the documentation for the next major of Umbraco, version 14.
This documentation is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.
The new Backoffice for Umbraco CMS is scheduled for release along with Umbraco 14 in May 2024.
#### Recommended starting points
Install v14-RC
If you have previously installed the Nightly or pre-release feeds versions you must clear the cache to use the new versions. This can be done by running the following command:
dotnet nuget locals all --clear
Then restore your package with dotnet restore
and run the solution again with dotnet run
.
Setup your development Environment followed by Vite package setup
You can also find a list of other resources related to the new backoffice of Umbraco in the Umbraco v14 "Bellissima" Resources article.
Some breaking changes have been introduced in the Umbraco 14. You can find the list of breaking changes or other changes from v14 in the Version Specific Upgrades article. In the same article, you can find the breaking changes between each v14 version.
You can also find a sneak peak of what is upcoming on v14 of the CMS in the Umbraco Product Update Blog.
Below you will find a list of new and updated articles for Umbraco 14.
The list will be updated as more articles have been created and updated.
FUNDAMENTALS:
SETUP
Upgrade your project
BACKOFFICE:
Document Blueprints (previously known as Content Templates)
EXTENDING BACKOFFICE (new section)
All articles under it are mostly new
REFERENCE:
Management API (new article)
Setup OAuth using Postman (new article)
Custom Swagger API (new article)
Instructions on installing Umbraco on various platforms using various tools.
This page is a work in progress. It will be updated as the software evolves.
If you have previously installed the Nightly or pre-release feeds versions, you must clear the cache to use the new versions. This can be done by running the following command:
dotnet nuget locals all --clear
Then restore your package with dotnet restore
and run the solution again with dotnet run
.
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 works in all modern browsers:
Chrome (Latest)
Edge (Chromium)
Firefox (Latest)
Safari (Latest)
Below you can find the minimum requirements to run Umbraco 13 on your machine:
One of the following .NET Tools or Editors:
As Umbraco releases are aligned to the .NET release cadence, it's also aligned with Microsoft's Long-term support policy for the underlying framework. For the best experience, we would recommend that you ensure to be on the latest and supported Microsoft versions to run and host Umbraco CMS:
For the above, as Umbraco version 13 is based on .NET 8 you will need to follow the .NET 8 supported versions.
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 permission to read and write from tables. It will also require permission to create schema during installs and upgrades:
The db_owner
role has full permissions on the database.
To use an account with more restricted permissions, the db_datareader
and db_datawriter
roles will be needed for normal use to read from and write to the database. The db_ddladmin
role, which can modify the database schema, is required for installs and upgrades of the CMS and/or any packages that create database tables.
One of the
with the
2022 version 17.8 or higher.
Optional: version 2022.3 and higher
and higher
When using Visual Studio as your primary Integrated Development Environment (IDE) we recommend .
and other
For more information, see the article in the Microsoft documentation.
You can use to manage the hosting infrastructure. All Umbraco Cloud plans are hosted on Microsoft Azure, which gives your site a proven and solid foundation.
For more information on the Database-level roles, see the .
For more information on how to create a database user via SQL, you can check the .
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.
Install the latest .NET SDK.
Run dotnet new install Umbraco.Templates
to install the project templates.
The solution is packaged up into the NuGet package Umbraco.Templates and can be installed into the dotnet CLI.
Once that is complete, you can see that Umbraco was added to the list of available projects types by running
dotnet new --list
:
In some cases the templates may silently fail to install (usually this is an issue with NuGet sources). If this occurs you can try specifying the NuGet source in the command by running dotnet new install Umbraco.Templates --nuget-source "https://api.nuget.org/v3/index.json"
.
To get help on a project template with dotnet new
run the following command:
dotnet new umbraco -h
From that command's output, you will get a better understanding of what are the default template options, as well as those command-line flags specific to Umbraco that you can use (as seen below):
Create a new empty Umbraco solution:
dotnet new umbraco -n MyCustomUmbracoProject
You will now have a new project with the name MyCustomUmbracoProject, or the name you chose to use. The new project can be opened and run using your favorite IDE or you can continue using the CLI commands.
If you want to create a solution file as well you can run the commands below.
dotnet new 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 project is now running on the Kestrel server and has assigned a free available port to run it on. Look in the terminal window after the dotnet run
command to see the URLs.
The next step is to run through the Umbraco CMS installation. If you chose to use MS SQL Server/Azure you will need to add your connection string during this setup process to get access to the Umbraco backoffice.
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 Install Umbraco with .NET CLI.
Go to File > New > Project and search for Umbraco
in the Search for templates field.
Once you select Umbraco Project (Umbraco HQ) navigate to the next step by clicking Next.
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.
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.
Once installed, launch VS Code.
Click the extensions menu at the bottom on the left side. Then search for C# and install it.
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:
Now you'll see a green play button appear with a dropdown where ".NET Core Launch (web)" is selected.
If you navigate to the Files section, a new launch.json
file is created in the .vscode
folder. When you press F5, the launch.json
file tells VS Code to build your project, run it, and then open a browser .
With that, you're ready to run the project! Press F5, or click the little green play button in the Run and Debug section to run your brand new Umbraco site locally.
This section continues from where we left off but covers the installation and configuration of Umbraco inside your web browser when you run Umbraco for the first time.
You will see the install screen where you will need to fill in some data before Umbraco can be installed.
When the installer is done, you will be logged into the backoffice.
Congratulations, you have installed an Umbraco site!
You can log into your Umbraco site by entering the following into your browser: http://yoursite.com/umbraco/.
Go to and download VS Code for free.
Follow the to create your project folder.
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.
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 File and folder permissions article.
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:
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.
This page is a work in progress. It will be updated as the software evolves.
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 to complete the upgrade of your project.
Icons in the new backoffice are based on .
A in Swagger - replacement for Controllers that were not restful
. Use partial views and/or blocks in the Rich Text Editor.
XPath has been removed. An alternative is using the Dynamic Roots in the Multinode Treepicker and for ContentXPath the alternative is .
along with RuntimeMinification setting. Smidge can be manually installed if needed and you can read the documentation on how to setup a similar setting to .
external documentations.
In-depth and further breaking changes for v14 can be found on the repository and on .
Learn more about the Umbraco backoffice which is the admin side of your Umbraco website.
In this article you can learn more about the common terms and concepts that are used throughout the Umbraco backoffice.
Content Templates provide a blueprint for content nodes based on an existing node.
Since Umbraco 9 it has been possible to run Umbraco CMS natively on Linux or macOS High Sierra 10.13 and newer.
With Umbraco CMS on .NET Core, Linux and macOS is natively supported with SQLite as the database.
In the below section, we describe how to get started with running Umbraco CMS on Linux or macOS.
To get started with Umbraco CMS first have a look at the requirements for running Umbraco CMS.
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 Install using .NET CLI guide.
With the templates installed on your system, it is now possible to create Umbraco projects.
To create a project, there are two options:
Continue creating projects using the .NET CLI.
Create new projects using Visual Studio (only macOS).
To create new projects using Visual Studio, you can use the Install using Visual Studio guide.
Once you create a new project it will use SQLite by default on Linux/macOS.
If you want to use an SQL server database, you will need to set up Docker.
This is the guide for upgrading existing installations in general.
This page is a work in progress. It will be updated as the software evolves.
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.
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 Install an Umbraco project template.
As you will not be running through the installation wizard when using this feature, you need to manually tell Umbraco which database to use.
Set up and configure a new database - see Requirements for details.
Add the connection string using configuration.
Umbraco can create an SQL Server database for you during the unattended install process. The user specified by the credentials in your connection string needs to have the CREATE DATABASE
permission granted and the global setting InstallMissingDatabase is set to true
.
If your connection string is for SQLite or SQL Server Express LocalDB it is assumed that a database should be created when missing. This is regardless of the value of the InstallMissingDatabase
setting.
The 'umbracoDbDSN_ProviderName' attribute sets the .NET Framework data provider name for the DataSource control's connection. For more information on the data providers included in the .Net Framework, see the Microsoft Documentation.
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
.
Alternatively you may set your configuration with Environment Variables or other means. Learn more about this in the Microsoft .Net Core config documentation.
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.
For more information about installing Umbraco, see the Installation article.
Get started with the New Backoffice in Umbraco 14.
Each block is an extension point that can be extended, customized, replaced, or removed.
You are also not limited to the mentioned frameworks. You can use any other framework or library of your choice. The new backoffice will be available in the Umbraco CMS from Version 14.
In this article, we'll provide an overview of the different ways you can extend the backoffice using the new frameworks.
There are a few words that cover certain concepts, which is good to learn to decode the purpose of code. These terminologies can be handy when starting to customize the new backoffice:
Resource: An API enables communication with a server.
Observable: An observable is the hook for others to subscribe to the data of a State.
Observe: Observe is the term of what we do when subscribing to an Observable.
Context Provider: One that provides a class instance as a Context API.
Context Consumer: One that consumer subscribes to a class instance as a Context API.
Controller: An abstract term for a thing that hooks into the lifecycle of an element. Many things in our system are Controllers.
Controller Host: A class that can host controllers.
Controller Host Element: The element that can host controllers.
In this article you can learn about how to create and use Document Blueprints in Umbraco.
This page is a work in progress. It will be updated as the software evolves.
Previously known as Content Templates, Document Blueprints allows a content editor to create a blueprint for new content nodes based on an existing node.
Select a Content node from the Content menu:
Right-click the Content node and select the Create Document Blueprint option. Alternatively, select the Actions dropdown of the content node and select the Create Document Blueprint option:
Give your document blueprint a Name:
Click the Create button and if the creation was successful, you will see a success notification:
The new document blueprint will be created in Document Blueprints node of the Settings tree:
Refresh your browser, if you do not see the new document blueprint in the Document Blueprints folder.
Click on the Settings menu:
Right-click on the Document Blueprints tree and select the Create menu item:
Select the Document Type you want to create a document blueprint for:
You can create document blueprints only from Document Types or Document Types with Templates
Give your document blueprint a Name and click the Save button:
The new document blueprint will be created in Document Blueprints folder of the Settings tree:
To edit an existing document blueprint, select a document blueprint from the Document Blueprints folder of the Settings tree. When you have finished editing click the Save button:
Once you have created a document blueprint, you can use the template to create new content nodes. To use a document blueprint, right-click the Content tree and select Create:
When you click on a Document Type that has a document blueprint you will see to options:
Create a new node based on a document blueprint
Create a blank one
"Belissima", code name for the frontend code of the backoffice, is a re-creation of the backoffice of Umbraco with a more modern approach. While replacing the deprecated angular code with , and , you can customize or extend more or less everything in the backoffice:
You can also find a list of other resources related to the new backoffice of Umbraco in the article.
Store: An API representing data, generally coming from the server. Most stores would talk with one or more resources. You can read more about this in the article.
State: A reactive container holding data, when data is changed all its Observables will be notified. You can read more about state and observables in the article.
Context-API: The name of the system used to serve APIs (instances/classes) for a certain context in the DOM. An API that is served via the Context-API is called a Context. You can read more about this in the article.
Umbraco Controller: Enables hosting controllers. Additionally, it provides a few shortcut methods for initializing core Umbraco Controllers. You can read more about this in the article.
Umbraco Element: The UmbLitElement
or UmbElemenMixin
enables hosting controllers. Additionally, it provides a few shortcut methods for initializing core Umbraco Controllers. You can read more about this in the article.
Before following this method you should have some created beforehand.
Learn about the recommended development environment to extend Umbraco.
Make sure you have followed the requirementsarticle, especially having installed the following on your machine:
Node.js version 20.11.0 (LTS) and higher
Extensions will go into a folder called App_Plugins
. If you don't have this folder, you can create it at the root of your Umbraco project.
Source code for your extensions should ideally be placed in a different project. This will make it easier to maintain and test your code. You can create a new project in the root of your Umbraco project, or you can create a new project in a separate folder. If you are using a bundler like Vite, you can configure it to copy over the files to the App_Plugins
folder when you build your project.
You can use any package manager you like to install dependencies. We recommend using NPM or Yarn. You can install packages by running the command:
This will install the package and save it to your package.json
file.
You need to setup a package.json
file if you don't have one already. You can do this by running the command:
Umbraco publishes an NPM package called @umbraco-cms/backoffice
that holds typings and other niceties to build extensions.
You can install this package by running the command:
This will add a package to your devDependencies containing the TypeScript definitions for the Umbraco Backoffice. The -rc3
is the version of the package, which will change as new versions are released.
It is important that this namespace is ignored in your bundler. If you are using Vite, you can add the following to your vite.config.ts
file:
This ensures that the Umbraco Backoffice package is not bundled with your package.
Read more about using Vite with Umbraco in the Vite Package Setup article.
If you're using Visual Studio Code we recommend the extension called Lit-Plugin to get IntelliSense for Lit Elements and Umbraco UI Library Components.
In this article, you will learn how to create your custom API in the Umbraco backoffice. This is a great way to extend the functionality of the Umbraco backoffice and create custom endpoints for your use.
To create a custom API, you need to create a class that inherits from Umbraco.Cms.Web.BackOffice.Controllers.ManagementApiControllerBase
.
The ManagementApiControllerBase
serves as the foundation for your custom API class. It provides essential functionalities and utilities required for managing APIs within the Umbraco backoffice environment.
We also use the VersionedApiBackOfficeRoute
attribute to define the route for our API. This attribute takes a string parameter that defines the route for the API. This route will be appended to the base route for the backoffice API.
Now that we have our class set up, we can add an action to get all items. We will use the HttpGet
attribute to define the HTTP
method and route for the action.
The AllItems
field is an in-memory list of items to simulate the use of a repository. We use the skip
& take
parameters here, so users of this endpoint can implement paging. We also use the PagedViewModel
to return the given items (10 by default), and then the total number of items.
AllItems is a local list:
The model for MyItem
is a basic class with an Id
and a Value
property.
We can now create some logic to return a response based on the ID
. The route parameter {id:guid}
specifies that the id
parameter should be a GUID
. Here we're creating a local in-memory list of items and returning the item with the matching ID
.
To note here is the use of the OperationStatusResult
method. This method allows you to return a response with a status code and a body. This is useful for returning error responses with additional information.
The method also needs an enum
operationStatus, as it will be attached to the response. This is a basic example, however, this OperationStatus
would be returned from your service layer, based on the error in the service layer method.
We can now add an action to create a new item. We use the HttpPost
attribute to define the HTTP
method and route for the action. Here we can see some validation logic.
If the value does not start with "New", we return a BadRequest
response with an error message. This highlights why we use the OperationStatusResult
method. We can return a detailed response.
We also use CreatedAtId<MyItemApiController>
, a helper method to create a response with a 201 Created
status code and a Location
header.
Now we can add an action to update an item. We can use the HttpPut
attribute to define the HTTP
method and route for the action.
Finally, we can add an action to delete an item. We can use the HttpDelete
attribute to define the HTTP
method and route for the action.
Now we have created the custom API for our Umbraco project. Below you can see the full example of the implementation.
Learn how to work with data or request the data when extending the backoffice.
Repositories are used for talking to the server by requesting data and getting notified about updates.
Context APIs work with “local/runtime” data and enables receiving APIs.
A store holds data throughout the session. It is used to create reactivity across different parts.
A reactive container holding data, when data is changed all its Observables will be notified.
Umbraco Elements enables hosting controllers.
A Dataset Context is the connection point between a Property Editor and a Workspace and covers a set of properties.
An extension begins with a Package Manifest
A Package is declared via an Umbraco Package Manifest. This describes the Package and declares one or more UI Extensions.
JSON file format is used to describe one or more custom Umbraco extensions such as property editors, dashboards, sections, or entity actions. This page outlines the file format and properties found in the JSON.
This is a sample manifest. It is always stored in a folder in App_Plugins/{YourPackageName}
, with the name umbraco-package.json
. In this example, the package name is SirTrevor
and is a text box property Data Type.
Before Umbraco 14, the manifest was declared in a package.manifest
file instead of umbraco-package.json.
This is a work in progress. It's currently not possible to register a manifest with Csharp such as it was supported in previous versions of Umbraco CMS.
The manifest takes four fields:
Allows you to specify a friendly name for your package that will be used for telemetry. If no name is specified the name of the folder will be used instead.
The version of your package, if this is not specified there will be no version-specific information for your package.
With this field, you can control the telemetry of this package, this will provide Umbraco with the knowledge of how many installations use this package.
The extensions
field is an array of UI Extension Manifests, each Manifest describes a single UI Extension. You can read more about this in the UI Extension Types article.
Make your IDE aware about the opportunities of the umbraco-package.json
by adding a JSON schema. This gives your code editor abilities to autocomplete and knowledge about the format. This helps to avoid mistakes or errors when editing the umbraco-package.json
file.
Editors like Visual Studio can use the $schema
notation in your file.
Hover over any of the properties to see the description of the property. You can also use the Ctrl + Space
(Windows/Linux) or CMD + Space
(macOS) shortcut to see the available properties.
Umbraco will automatically pick up any umbraco-package.json
files found in the /App_Plugins
folder. You need to restart the application for new packages to be loaded or if you changed anything in existing files.
Get started with a Vite Package, setup with TypeScript and Lit
This page is a work in progress. It will be updated as the software evolves.
Umbraco recommends building extensions with a setup using TypeScript and a build tool such as Vite. Umbraco uses the library Lit for building web components which we will be using throughout this guide.
Vite comes with a set of really good presets to get you quickly up and running with libraries and languages. For example: Lit, Svelte, and Vanilla Web Components with both JavaScript and TypeScript.
Before following this guide, read the Setup Your Development Environment article.
Run the following command in the App_Plugins
which is found (or needs to be created) at the root of your project:
This command will help you set up your new package, asking you to pick a framework and a compiler.
To follow this tutorial, we recommend you enter my-dashboard
as the Project Name when prompted, although you can choose any other you like. Then choose Lit and TypeScript.
This creates a new folder, sets up our new project, and creates a package.json
file, which includes the necessary packages.
Instead of the 2 above steps, you can do the following:
This will create a Vite Package with Lit and Typescript in a folder called my-dashboard.
Navigate to the new project folder my-dashboard and install the packages using:
Install the Backoffice package. You can install the package using the following command:
Optionally you can use --legacy-peer-deps
in the installation command to avoid installing Umbraco´s sub-dependencies like TinyMCE and Monaco Editor:
npm install --legacy-peer-deps -D @umbraco-cms/backoffice@14.0.0-rc3
If this is used the Intellisense to those external references will not be available.
Create a new file called vite.config.ts
in my-dashboard
folder and insert the following code:
This alters the Vite default output into a library mode, where the output is a JavaScript file with the same name as the name
attribute in package.json
. The name is my-dashboard
if you followed this tutorial with no changes.
The source code that is compiled lives in the src
folder of your package folder and that is where you can see a my-element.ts
file. You can confirm that this file is the one specified as our entry on the Vite config file that we recently created.
The build:lib:entry
parameter can accept an array which will allow you to export multiple files during the build. You can read more about Vite's build options here.
Build Package
Build the ts
file in the my-dashboard
folder so we can use it in our package:
If you like to continuously work on the package and have each change built, you can add a watch
script in your package.json
with vite build --watch
. The example below indicates where in the structure this change should be implemented:
Then in the terminal, you can run npm run watch
.
Declare your package to Umbraco via a file called umbraco-package.json
. This should be added at the root of your package. In this guide, it is inside the my-dashboard
folder.
This example declares a Dashboard as part of your Package, using the Vite example element.
Umbraco needs the name of the element that will render as default when our dashboard loads.
This is specified in the manifest as the elementName
.
Another approach would be to define your default element in the TS code. To do this, in the src/my-element.ts
add default
to your MyElement
class in the file like so:
Learn more about the abilities of the manifest file in the Umbraco Package Manifest article.
To be able to test your package, you will need to run your site.
Before you do this, you need to include all the files in the src
folder and the umbraco-package.json
file in your project.
If you try to include these resources via Visual Studio (VS), then only the dist
folder needs to be included. Otherwise, VS will try to include a few lines on your .csproj
file to compile the TypeScript code that exists in your project folder. When you run your website, VS will try to compile these files and fail.
Result
The final result looks like this:
If the Vite logo is not found, the path to its location needs to be changed. Update the my-element.ts
file in the src
folder accordingly:
In the same file, you will need to change the background-color
of the button
to white so it is visible:
With this, you have set up your Package and created an Extension for the Backoffice.
This Dashboard will appear on all sections, so continue the following tutorial on Creating A Custom Dashboard.
A store holds data throughout the session. It is used to create reactivity across different parts.
This page is a work in progress. It will be updated as the software evolves.
A store is the link between a Resource and a Repository. A store is mainly taken from a Context API. In other words, we will have to Consume the Context (Store) to get the Store.
In this example, we created an ArrayState, A State which is specific to Arrays. This holds the data for one or more Observables to convey to outsiders.
This example shows how to use the store:
Here we added a method that returns an Observable that is specific to the requested product.
An example implementation using this method:
Create many Observables
A Store must hold different Observables, some exceptionally general and others highly specific, all in perspective of the types of observers we aim to accommodate.
This example gives some inspiration to how fine-grained this can become:
An observer of an Observable will only be triggered if the specific part of that data has changed. With this we can make a high-performance application, only triggering the parts that need to update when data is changed.
Ensure unique data
For incoming data to replace existing data, we need to clarify what makes an entry of the array unique. In the examples of this guide, each product has an id
. We have clarified this to the State by giving it the little method (product) => product.id
as part of its creation:
Communicate across different boundaries with the Context API
This page is a work in progress. It will be updated as the software evolves.
The Context API enables receiving APIs. Depending on where your code is executed from, it affects which and what instances of APIs can be received.
The Context API enables an element or a controller to receive an API provided via any ascending element. In other words, it can receive APIs provided via a parent element or parent of a parent element, and so forth.
The Context API enables connections between Elements and APIs. DOM structure defines the context of which an API is exposed for. APIs are provided via an element and can then be consumed by any decending element.
There are different ways to consume a Context API. The most straightforward implementation is done on an Umbraco Element with a Context Token.
All Umbraco Context APIs have a Context Token which can be imported and used for consumption, for example:
The above example takes place in an Umbraco Element or Umbraco Controller.
The above examples utilize an Umbraco Controller to hook into an element's life cycle. This Controller is named UmbContextConsumerController
.
If you need to consume a Context API from a non-controller host, then look at the UmbContextConsumer
.
A Context Token is a context identifier and is generally a string matched with a type. In this way, users of the token can be sure to get the right type of context.
For additions to Contexts, we can use the API Aliases to identify the additional API. Using the same Context Alias for additional APIs will ensure that such API must be present with the first encounter of that Context Alias. Otherwise, a request will be rejected. In other words, if the addition is not part of the nearest matching Context, the request will be rejected.
Using API Alias only provides value when two or more APIs should share the same Context. This is needed for Context Extensions that are provided along with other Contexts.
The Token declared above can be used to provide an additional Context API at the same Element as another Context API is provided at. Below is an example of how the two APIs are made available.
This is no different than using two different Context Aliases. But it has an important effect on what happens if one of them is not provided. This is demonstrated in the example below:
The consumption of the Additional API will never happen as the token uses the same Context Alias as MY_API_TOKEN
. This means that any request containing this Context Alias will be stopped at the first API it encounters. To ensure addition to a specific context, do it locally at the nearest API that uses the same Context Alias.
This is only relevant if you are going to make multiple context API for the same context. Discriminator only gives value for consumption of Context APIs that have a varying interface. The backoffice uses this for the different types of Workspace Contexts.
If someone wants the workspace name, they might not care about the specific API of the Workspace Context. These implementations can use a standard Context Token with a type of generic Workspace Context.
The features related to Publishing in the Document Workspace Context do not require a new Context. However, we should not accidentally retrieve the workspace context of a parent workspace when in a Workspace. Therefore, we need to provide a workspace context in each workspace, and the one we retrieve is the one we will be using. Since Publishing is not part of the generic Workspace Context, check if the context is a Document Workspace Context and recast it accordingly.
To avoid each implementation taking care of this, Context Tokens can be extended with a Type Discriminator. This will discard the given API if it does not meet the necessary requirements. When it is the desired type, the API will be converted to the appropriate type.
This example shows how to create a discriminator Context Token that will discard the API if it is not a Publishable Context:
Context Token Example:
Implementation of Context Token Example:
This allows implementers to request a publishable context without needing to know the Type or how to identify the context.
In detail, the Context API will search for the first API that matches the alias My.Context.Token
, and not look further. If the API meets the type discriminator, it will be returned, otherwise the consumer will never reply.
You can provide a Context API from an Umbraco Element or Umbraco Controller:
Or with a Controller using a 'host' reference to Controller Host (Umbraco Element/Controller):
Generally, a Store will be holding one or more , with each Subject made available for Observation via Observables.
In some cases, it is needed to have different APIs for the same context. For example, the .
Contexts
This page is a work in progress.
Below you can find some articles on how you can work with different contexts:
Make reactivity with Umbraco States
This page is a work in progress. It will be updated as the software evolves.
Umbraco States enables you to create Observables based on a State. The Observables can then be observed, and when a change to the State occurs, all observers of Observables will be triggered.
Umbraco comes with a State type for the most common types of data:
Array State
Boolean State
Class State
Number State
Object State
String State
[TBD: Describe Observable]
The Umbraco Element or Controllers comes with the ability to observe an Observable.
While observing all changes will result in the callback being executed.
The example below creates a State and then turns the whole state into an Observable, which then can be observed.
The value of a state can be changed via the setValue
method. This replaces the current data with new data.
The following example shows how to change the value of the state to hold item2
and item3
. As the example extends the example from above, it means that item1
is no longer part of the value of this state.
Observe part of a state
With the asObservablePart
method, you can set up an Observable that provides a transformed outcome, based on the State.
In the above example, the asObservablePart
mapping function will be executed every time there is a change to the State. If the result of the method is different than before it will trigger an update to its observers.
Ease the integration with Backoffice by using a Umbraco Element
This page is a work in progress.
This provides a few methods to connect with the Backoffice, giving you the ability to:
Consume a Context — Learn more about Consuming Contexts
Provide Context — Learn more about Providing Contexts
Observe a State — Learn more about States
Localization — Learn more about Localization
Host Controllers — Learn more about Controllers
You can turn any Web Component into an Umbraco Element by using the Umbraco Element Mixin, as done in the following example:
Reuse functionality across components by writing it as a Controller
This page is a work in progress. It will be updated as the software evolves.
A Controller must follow the interface of UmbController, to ease the implementation you can base your class on the UmbController
:
This page is a work in progress. It will be updated as the software evolves.
Most of BackOffice is based on Extensions making it crucial to understand how to register your own extensions. This introduction will give you an outline of the abilities of the extension registry.
The extension registry is a global registry that can be accessed and changed at anytime while Backoffice is running.
To provide new UI to backoffice, you need to register them via an extension manifest. This has to initially happen on the server, via a JSON Package Manifest. This will enable you to register one or more extensions.
The abilities of the extensions rely on the specific extension type. The Type sets the scene for what the extension can do and what it needs to be utilized.
Some extension types rely on a reference to other extensions.
Most extension types support conditions. Defining conditions enables you to control when and where the extension is available.
The kinds feature enables you to base your extension registration on a preset. A kind provides the base manifest that you like to extend.
A Package is declared via an Umbraco Package Manifest. This describes the Package and declares one or more UI Extensions.