Forem: Luuk Peters

Upgrade Umbraco 13 to 17: Property Editors + Property Value Converters

Luuk Peters — Thu, 12 Mar 2026 13:30:20 +0000

This is part five in a series about common tasks you'll encounter when upgrading Umbraco 13 to 17. In this part, we’ll look at updating Property Editors and Property Value Converters.

When upgrading several packages, one area that caused confusion was Property Editors. In Umbraco 17 there is a much clearer separation between the UI in the backoffice and the data handling and validation on the backend (C#).

Because of this change, Umbraco introduced migrations that convert existing Data Types (which are essentially instances of a Property Editor) to the new format. In Umbraco 13 a Data Type only referenced a single editor alias, but in Umbraco 17 it contains two: an editor alias (backend) and an editor UI alias (frontend). This makes it possible, for example, to use multiple interchangeable UIs that work with the same underlying data.

Why won't my property editor work anymore?

After upgrading my database to Umbraco 17 I ran into a couple of issues:

How does Umbraco know that it should use my newly created Property Editor UI for existing properties?
Why does Models Builder suddenly return a JsonDocument instead of my custom VideoPlayerValueConverterModel?

The answer lies in understanding what the migration from Umbraco 13 to 14+ actually does and what you need to do with the result. This post walks through that process.

This blog explains how you can update your Property Editors to work in Umbraco 17 without having to create a custom migration. It also helps to read the Umbraco documentation on Property Editor composition. That documentation explains the different pieces that make up a Property Editor in Umbraco 17 and provides useful context for what follows.

The starting point before the migration

There are two different starting points for Property Editors in Umbraco 13, and each leads to a slightly different outcome during the migration to Umbraco 14+. The difference depends on whether the Property Editor is defined in a package.manifest file or in C# code.

Starting point 1: manifest-only Property Editor

In Umbraco 13 a Property Editor can be defined purely in a package.manifest, for example:

...
  "propertyEditors": [
    {
      "alias": "proudnerds.videoplayer.editor",
      "name": "Video player",
      "icon": "icon-play",
      "group": "Proud Nerds",
      "editor": {
        "view": "~/App_Plugins/ProudNerds.Umbraco.VideoPlayer/umbraco.videoplayer.html"
      }
    }
  ]
...

This is enough to create a simple data editor. The value is stored as a string in the database and there is no server-side validation. Anything can be stored as long as it fits into a string.

If needed, you can still transform that value later using a Property Value Converter before it ends up in the cache.

Starting point 2: Property Editor defined in code

You can also define a Property Editor in C#, for example:

using Umbraco.Cms.Core.PropertyEditors;

namespace YourProjectName;

[DataEditor(
    alias: "Suggestions editor",
    name: "Suggestions",
    view: "/App_Plugins/Suggestions/suggestion.html",
    Group = "Common",
    Icon = "icon-list")]
public class Suggestions : DataEditor
{
    public Suggestions(IDataValueEditorFactory dataValueEditorFactory)
        : base(dataValueEditorFactory)
    {            
    }
}

Defining a Property Editor in code gives you more control over validation and how the data is stored.

The resulting database records

When you create a Data Type in Umbraco 13 that uses a Property Editor, the resulting database record is almost identical for both approaches. Each Data Type simply stores a property editor alias and configuration in the umbracoDataType table.

If you register the editor in C#, the dbType may differ, but that detail is not important for this discussion.

The data migration (13 → 14+)

The difference between the two approaches becomes visible during migration.

In one of the later Umbraco 13 versions a pre-migration was introduced that prepares Property Editors for upgrading to Umbraco 14+. During this step, a record is written to the umbracoKeyValue table describing how each Data Type should be migrated.

For a manifest-only Property Editor, the record looks like this:

[{"DataTypeId":1055,
"EditorUiAlias":"proudnerds.videoplayer.editor",
"EditorAlias":"Umbraco.Plain.String"}]

However, if the editor was defined in C#, both aliases will be the same:

[{"DataTypeId":1055,
"EditorUiAlias":"proudnerds.videoplayer.editor",
"EditorAlias":"proudnerds.videoplayer.editor"}]

After the database upgrade to Umbraco 17, this information is used to populate the new propertyEditorAlias and propertyEditorUiAlias columns in the umbracoDataType table.

For the video player editor, the result of the migration looks like this:

Updating the code

Once you understand what the migration produced in the database, updating the code becomes much clearer.

Creating and registering the Property Editor UI

With the new backoffice introduced in Umbraco 14+, the UI part of your Property Editor needs to be recreated because AngularJS is no longer supported.

After creating the UI, you need to register it. I won't go into the details of building a Property Editor UI here (the documentation covers that), but the aliases you use during registration are important.

Based on the migration result:

alias should match PropertyEditorUiAlias
propertyEditorSchemaAlias should match PropertyEditorAlias

For example:

export const manifests: Array<UmbExtensionManifest> = [
{
    type: 'propertyEditorUi',
    alias: "proudnerds.videoplayer.editor",
    name: "Proud Nerds video player property editor",
    js: () => import("./proud-nerds-video-property-editor-ui.element"),
    meta: {
        label: "Video player",
        icon: "icon-play",
        group: "Proud Nerds",
        propertyEditorSchemaAlias: "Umbraco.Plain.Json",
        settings: {
            properties: [
                ...
            ]
        }
    }
}

Updating the DataEditor (if it already exists)

If your editor already had a DataEditor implementation, you can continue using it, but it needs to be updated for Umbraco 17.

Most of the implementation remains similar to Umbraco 13. The main difference is that several parameters have been removed from the DataEditor attribute because of the clearer separation between UI and backend logic.

// Umbraco 13
[DataEditor(
    alias: "proudnerds.videoplayer.editor",
    name: "Video Player",
    view: "/App_Plugins/VideoPlayer/videoplayer.html",
    Group = "Proud Nerds",
    Icon = "icon-play")]
public class VideoPlayerEditor : DataEditor
...

// Umbraco 17
[DataEditor("proudnerds.videoplayer.editor")]
public class VideoPlayerEditor : DataEditor
...

Updating the Property Value Converter (if needed)

If you used the manifest-only approach in Umbraco 13, there is a good chance your Property Value Converter no longer works.

During migration, the EditorAlias for the video editor changed from:

proudnerds.videoplayer.editor

to:

Umbraco.Plain.Json

So if your Property Value Converter checks the editor alias, it will no longer match:

public override bool IsConverter(IPublishedPropertyType propertyType) =>
propertyType.EditorAlias.Equals("proudnerds.videoplayer.editor");

The simplest fix is to check the EditorUiAlias instead:

public override bool IsConverter(IPublishedPropertyType propertyType) =>
propertyType.EditorUiAlias.Equals("proudnerds.videoplayer.editor");

This is not entirely semantically correct, but it is often the easiest solution without introducing additional migrations. After this, your Property Editor will work as expected again and the models builder will use your custom model instead of the generic JsonDocument.

Done

Once you understand how the Property Editor migration works, it becomes much easier to determine which aliases to use in umbraco-package.json and what code changes are required after upgrading.

The concepts themselves are straightforward, but the migration can be confusing the first time you encounter it. Hopefully this overview helps clarify what is happening behind the scenes.

EditorUiAlias or not?

Earlier I mentioned that checking EditorUiAlias inside the IsConverter method of a Property Value Converter is not entirely correct from a semantic point of view.

A Property Value Converter operates on the data stored in the database and converts that to something else to put in the cache. A Property Editor UI is only the interface used to edit that data. In fact, multiple UIs could theoretically exist for the same underlying editor.

Because of that, checking EditorUiAlias introduces some risk. If a different UI were introduced for the same editor, your converter might no longer match the correct data. Checking EditorAlias is the safest way to guarantee you are handling the expected data structure.

That said, in many real-world scenarios a Property Editor has exactly one UI and one DataEditor that always belong together. If you fully control the implementation, checking EditorUiAlias can be a pragmatic and perfectly workable solution that avoids writing additional migrations.

Opinions on this tend to differ. Some developers strongly prefer to always check EditorAlias for correctness, while others consider EditorUiAlias acceptable when the editor and UI are tightly coupled. In the end, the choice depends on how strictly you want to follow the separation between UI and data.

No, you don’t need Lit, Vite, or TypeScript to Extend the Umbraco Backoffice

Luuk Peters — Wed, 05 Nov 2025 10:30:59 +0000

One of the biggest misconceptions I see pop up regularly among developers who start working on the new Umbraco "Bellissima" backoffice for the first time is that they think you need a lot of scaffolding and an entire build pipeline to extend the Umbraco 14+ backoffice.

This makes it seem like arbitrary extensions to the backoffice are very hard, especially for backend developers who aren’t into npm and such.

I'm here to tell you that you don’t need to use Lit, Vite, or TypeScript if you don’t want to.

Why do so many developers think you need all that scaffolding?

For the most part, this is a documentation thing. Umbraco itself uses Lit, Vite, and TypeScript in its codebase, and as a result, most examples in the documentation are based on Lit. Also, the Setup your development environment article talks about setting up TypeScript and Vite, which reinforces that impression.

You might think it’s just a matter of better documentation, and although I agree that the docs could improve, the problem is actually a bit bigger.

A well-designed (and overly flexible) architecture

The funny thing is that biggest problem is that the backoffice architecture is really well designed. That sounds like a contradiction, but hear me out.

The backoffice is built to be flexible, extensible, and framework-agnostic. Because of this, there are actually very few hard requirements for extending it.

UI extensions (like property editors, buttons, or workspaces) must be web components.
Other extensions (like repositories or stores) must follow the requirements of their extension type.
And lastly, you need an umbraco-package.json file to register the extensions.

But that’s practically it.

This means that as long as you follow these basic rules, you can create your extension however you want. Yes, Umbraco uses TypeScript for their code, Lit for its web components, and Vite to bundle it all, but you don’t have to. You can use your own framework and bundler if you like, as long as your bundles use the ES module syntax.

No scaffolding? No problem

You can also use plain JavaScript and skip any compilation or bundling entirely. As long as the requirements are met. That means no npm packages, no build scripts, and no scaffolding.

So, there are many ways to go about this. And that’s what I mean when I say that the backoffice architecture is both a blessing and a curse: there are so many possibilities that it’s impossible to document every one of them.

That said, I also believe the documentation could do a better job at showing this flexibility. I’m part of the Umbraco Documentation Community Team, and I try to spread the message of this blog wherever I can.

When to use what

There’s no absolute right or wrong, but here’s my opinion:

Use plain JavaScript for small and simple things, like a block view or a small Tiptap extension.
For anything bigger, it’s worth investing the time to use TypeScript — it elevates the quality of your code and prevents bugs. Especially if you’re a C# developer, you’ll probably appreciate the strong typing.
Once you’re already using npm and build scripts, it’s just a small step to introduce Lit and bundle it with Vite.

In the end, it’s not that hard. I’m primarily a C# backend developer, and yes, the learning curve exists, but I can honestly say that the quality of my packages has improved significantly since adopting these tools.

I’d also recommend going with Lit for elements. The Umbraco source code and most examples use it, so unless you have a specific reason not to, it’s a good default.

Lit is lightweight and removes the most annoying parts of writing web components by hand.

Want to learn more?

Because I don’t want to bloat this blog with tons of examples, I’ll wrap up with a few useful links if you want to dive deeper:

I recently rewrote the documentation on the extension registry, which hopefully makes things a bit clearer.
For the Umbraco Autumn Contribution Challenge 2025, I created an example showing how to register a custom condition to an existing extension. The example illustrates three different approaches (with the same result): vanilla JavaScript, TypeScript without bundling, and Lit + Vite. You can find it on GitHub.

In short: you don’t need all the scaffolding to extend Umbraco’s backoffice, but knowing how to use it can make your life a lot easier.

How to Sync NuGet and Umbraco Package versions automatically in Umbraco 14+

Luuk Peters — Thu, 09 Oct 2025 10:15:29 +0000

In an Umbraco package, there have always been two versions that matter: the version of the NuGet package and the version of the Umbraco extension.

NuGet Package Version

The NuGet package version is displayed in a NuGet feed and is relevant for your .NET solution. It's easy to see the currently installed version and check if any updates are available using the Semantic Versioning (SemVer) scheme.

The version for the NuGet package is set in the project file. This can be done using different properties, like Version, VersionPrefix, PackageVersion, and others, but for this example, I'll stick to the Version property like this:

<Project Sdk="Microsoft.NET.Sdk.Razor">
    <PropertyGroup>
        <TargetFramework>net9.0</TargetFramework>
        ...
        <Version>16.0.0</Version>
    </PropertyGroup>
</Project>

For example, here are some custom packages in their NuGet feed showing their versions in Visual Studio:

Umbraco Extension Version

On the other hand, we have the version of the Umbraco extension. This is the version specified in the package.manifest in Umbraco 13 or the umbraco-package.json in Umbraco 16. This version number is displayed in the backoffice in the list of installed packages.

For example, this umbraco-package.json:

{
  "$schema": "../../umbraco-package-schema.json",
  "id": "ProudNerds.Umbraco.ContentExpiration",
  "name": "ProudNerds Content Expiration",
  "version": "16.0.0",
  "extensions": [
    ...
  ]
}

will be displayed in the backoffice of Umbraco 16 like this:

Why Keep Them the Same?

I believe these two versions should always be the same. It’s very convenient to check the version of a package directly in the backoffice.

Version Synchronization in Umbraco 13

In Umbraco 13, we actually had an option to take the assembly version and use that as the version of the Umbraco extension:

{
  "name": "ProudNerds Content Expiration",
  "id": "ProudNerds.Umbraco.ContentExpiration",
  "versionAssemblyName": "ProudNerds.Umbraco.ContentExpiration",
  ...
}

By specifying the assembly that holds the NuGet version in the versionAssemblyName property, the extension would automatically use the same version.

Version Synchronization in Umbraco 16

In Umbraco 16, this feature no longer exists. Because the backoffice is now a separate entity that has no knowledge of any backend C# code, there’s no easy way to read a version from an assembly.

The way I currently make sure that my extension version is the same as the NuGet version is by installing a small Umbraco NuGet package. Then I use a task that's in that package in an after-build event to update the version number in the umbraco-package.json file. In this setup, the NuGet version is leading.

Step 1: Install the Helper Package

Install the NuGet package Umbraco.JsonSchema.Extensions.

Its version is 0.3.0 at the time of writing, so it doesn’t feel like a finished product, but it does its job well — and Umbraco uses it themselves.

Step 2: Create an After-Build Event

Add the following target to your project file:

<!-- Updates the version in the umbraco-package.json file to match the NuGet package version -->
<Target Name="UpdateUmbracoPackageJsonVersion" AfterTargets="Build">
    <PropertyGroup>
        <!-- Change the path to your umbraco-package.json file -->
        <UmbracoPackageJsonPath>$(ProjectDir)wwwroot\App_Plugins\ExamplePlugin\umbraco-package.json</UmbracoPackageJsonPath>
    </PropertyGroup>

    <Message
        Text="Checking for umbraco-package.json at: $(UmbracoPackageJsonPath)"
        Importance="High" />

    <!-- This will use the Version property from the project file.
         Change it here if you want to use VersionPrefix, for example. -->
    <JsonPathUpdateValue
        JsonFile="$(UmbracoPackageJsonPath)"
        Path="$.version"
        Value="&quot;$(Version)&quot;"
        Condition="Exists('$(UmbracoPackageJsonPath)')" />

    <Message
        Text="✅ Updated umbraco-package.json version to $(Version)."
        Importance="High"
        Condition="Exists('$(UmbracoPackageJsonPath)')" />

    <Message
        Text="⚠️ Skipped updating umbraco-package.json version - file not found at $(UmbracoPackageJsonPath)."
        Importance="High"
        Condition="!Exists('$(UmbracoPackageJsonPath)')" />
</Target>

This is all you need! On every build, you will now see the messages appear in your output on build:

Conclusion

By automatically updating the version in umbraco-package.json after every build, you can ensure your Umbraco extension version stays in sync with your NuGet package version. This makes it easier to track versions across your solution and in the Umbraco backoffice without manual updates.

Upgrade Umbraco 13 to 16: API controllers

Luuk Peters — Thu, 02 Oct 2025 10:00:53 +0000

This is part four in a series of blogs about common tasks you'll encounter when updating Umbraco 13 to 16. In this part, we'll look into updating Umbraco API controllers to Umbraco 16. We'll cover the UmbracoApiController and the UmbracoAuthorizedApiController, because both of them no longer exist in Umbraco 16.

Update UmbracoApiControllers

The UmbracoApiController is a controller for creating your own Web API endpoints. There really wasn't much special about these controllers, except that they were routed automatically to a certain URL. As an example, take this endpoint:

public class ExampleController : UmbracoApiController
{
    public string HelloWorld()
    {
        return "Hello World!";
    }
}

It would be routed to ~/Umbraco/Api/Example/HelloWorld.

Umbraco likely recognized that an UmbracoApiController isn’t very special, so it was replaced with regular controllers where you are responsible for defining the routing yourself. Umbraco has documentation for porting over old Umbraco API Controllers, so I’ll just refer you to that.

Update UmbracoAuthorizedApiControllers

The changes to the UmbracoAuthorizedApiController are more significant. These controllers were meant to be used by extensions in the Umbraco backoffice and could only be called in the context of a logged-in user. You could think of them as backoffice API endpoints.

Cue the Management API

With the new Umbraco 14+ backoffice, the Management API was introduced as a uniform way for the frontend to communicate with the backend. Compared to Umbraco 13, this is like backoffice API endpoints in steroids! To use custom endpoints for your backoffice extensions, you now add them to the Management API. So we need to change our UmbracoAuthorizedApiControllers to use the Management API.

As an example, here’s a small API endpoint in Umbraco 13 that creates a new website in the content tree. We’ll update this to Umbraco 16:

[PluginController("CoreContent")]
public class CoreContentDashboardApiController(...) 
    : UmbracoAuthorizedApiController
{
    [HttpGet]
    public IActionResult CreateNewWebsite(string websiteName)
    {
        ...
    }
}

Perform the update

First, change the base class from UmbracoAuthorizedApiController to ManagementApiControllerBase:

public class CoreContentDashboardApiController(...) 
    : ManagementApiControllerBase

Second, remove the PluginController attribute and replace it with VersionedApiBackOfficeRoute and ApiExplorerSettings:

[VersionedApiBackOfficeRoute("core-content")]
[ApiExplorerSettings(GroupName = "ProudNerds Core")]
public class CoreContentDashboardApiController(...) 
    : ManagementApiControllerBase

So what did we add?

VersionedApiBackOfficeRoute determines the last part of the URL. To stay consistent with the rest of the Management API, use lowercase letters and separate words with a dash. In this example, the base URL of the endpoints will be /umbraco/management/api/v1/core-content.
ApiExplorerSettings with a GroupName ensures a separate section with that title will appear in the Swagger docs of the Management API.

The individual endpoints don’t need many changes, but keep these caveats and tips in mind:

Umbraco uses a single responsibility per controller in their source code, so typically you’ll have one endpoint per controller. If you place multiple endpoints in a single controller, you need to supply a template for the HttpGet (or other HTTP method) to make sure the endpoints are unique, for example [HttpGet("create-new-website")].
Add ProducesResponseType attributes to enhance the Swagger docs. But avoid adding response types for common codes like 400 and 404, as this will break Swagger because Umbraco already registers those internally.

So a complete API could look like this:

[VersionedApiBackOfficeRoute("core-content/create-new-website")]
[ApiExplorerSettings(GroupName = "ProudNerds Core")]
public class CoreContentDashboardApiController(...) 
    : ManagementApiControllerBase
{
    // Because this controller has only one endpoint,
    // we don’t need to set a template on the HttpGet.
    // The VersionedApiBackOfficeRoute determines the endpoint.
    [HttpGet]
    [ProducesResponseType<int>(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    [ProducesResponseType<ProblemDetails>(StatusCodes.Status500InternalServerError)]
    public IActionResult CreateNewWebsite(string websiteName)
    {
        ...
    }
}

This will add a section in Swagger of the Management API with our custom endpoint:

Granular security

By default, Management API endpoints are accessible to any logged-in Umbraco user. However, sometimes you need to restrict access to specific roles or policies. That’s where the Authorize attribute comes in:

[Authorize(Policy = AuthorizationPolicies.RequireAdminAccess)]
[VersionedApiBackOfficeRoute("core-content")]
[ApiExplorerSettings(GroupName = "ProudNerds Core")]
public class CoreContentDashboardApiController(...) 
    : ManagementApiControllerBase
{
    ...
}

In this example, the endpoint is only accessible to administrators.

The documentation for creating a backoffice API has more information and a more elaborate example.

Summary

Updating Umbraco APIs isn’t difficult once you know what to look for:

Replace UmbracoApiController usage with regular controllers and wire up routing yourself.
Replace UmbracoAuthorizedApiController with ManagementApiControllerBase, add VersionedApiBackOfficeRoute and ApiExplorerSettings, and secure endpoints with Authorize when needed.

Upgrade Umbraco 13 to 16: Localization

Luuk Peters — Thu, 04 Sep 2025 09:35:14 +0000

This is part three in a series of blogs about common tasks you'll encounter when updating Umbraco 13 to 16. In this part, we'll look into updating localization to work with Umbraco 16. First, we'll cover updating backoffice localization, then we'll cover changes to localization in C# code, and finally, I'll briefly touch on using localization in Umbraco backoffice extensions.

Backoffice localization (UI Localization)

Probably the most common localization feature is the ability to localize the backoffice. Think of the names and descriptions of content types and their properties, but also things like sections, dashboards, and message popups.

Backoffice localization works in roughly the same way in Umbraco 13 and 16: you have a file for each language you want to support in the backoffice, and each file defines a set of keys with localized values. You then use those keys in various places in the Umbraco backoffice. Because this blog focuses on upgrading Umbraco, I’ll assume you already know how localization works in the Umbraco 13 backoffice. If not, read the localization documentation of Umbraco 13 first.

The main difference between Umbraco 13 and 16 is the file format and how the files are registered, so for the most part, backoffice localization is not difficult to update.

Update language files

Let’s start by updating the language files to the new format. In Umbraco 13, language files were XML, but in Umbraco 16 they are — like almost everything in the backoffice — extensions. This means they work with JavaScript and must be registered using a manifest. And because they are JavaScript, you can actually do some useful things with them, but I’ll come back to that later.

It’s also good to note that XML language files haven’t completely disappeared; they are still used for localization in backend C# code. However, everything in the backoffice now uses JavaScript.

Here’s an example Umbraco 13 language file, located in wwwroot/App_Plugins/Example/Lang/en.xml:

<?xml version="1.0" encoding="utf-8" ?> 
<language>
    <area alias="exampledocype">
        <key alias="doctype_name">Example</key>
        <key alias="doctype_description">This is an example doc type</key>
        <key alias="property1_name">Property name</key>
        <key alias="property1_description">Use this property for something</key>
    </area>
</language>

We now need to convert this file to JavaScript. The idea remains the same, but unlike Umbraco 13 — where language files had to be in a specific folder to be automatically loaded — in Umbraco 16 you can name your file anything and place it anywhere. The only requirement is that you register the file in a manifest. Just make sure to use the same aliases for your keys.

For example, let's update the Umbraco 13 example and place it at wwwroot/App_Plugins/Example/localization-en.js:

export default {
    exampledocype: {
        doctype_name: "Example",
        doctype_description: "This is an example doc type",
        property1_name: "Property name",
        property1_description: "Use this property for something"
    }
}

And that’s it! For large files, simply let AI do the conversion for you — it’s surprisingly good at it. Now we just need to register the localizations.

Register localization in 16

As mentioned, localizations are backoffice extensions. This means they need to be registered using an Extension Manifest and are not automatically loaded by convention. There are multiple ways to register manifests, but in this example, we’ll register them directly in the umbraco-package.json file.

Create or update wwwroot/App_Plugins/Example/umbraco-package.json and add localization manifests. You need a manifest for each language:

{
    "$schema": "../../umbraco-package-schema.json",
    "id": "Example.Localization",
    "name": "A localization example",
    "version": "1.0.0",
    "extensions": [
        {
            "type": "localization",
            "alias": "Example.Localization.Localize.En",
            "name": "English",
            "meta": {
                "culture": "en"
            },
            "js": "/App_Plugins/Example/localization-en.js"
        },
        {
            "type": "localization",
            "alias": "Example.Localization.Localize.Dk",
            "name": "Danish",
            "meta": {
                "culture": "dk"
            },
            "js": "/App_Plugins/Example/localization-dk.js"
        }
    ]
}

Now, most backoffice localization should work again.

Fix property description fields

The bulk of the work to make your backoffice localizations from Umbraco 13 work in 16 is now done, but we’re not finished yet. Not all localizations work out of the box. Specifically, description fields on properties do not localize as they did in Umbraco 13. If you use a key in a description field the same way as before, the description will not be localized:

Instead, you need to wrap the description key in curly brackets:

This is because descriptions are passed through the Umbraco Flavoured Markdown pipeline, which requires the correct formatting.

See the Umbraco 16 documentation on backoffice localization for more details.

Backend localizations (.NET localization)

Backend localizations in .NET are useful when you need to localize texts for things like sending emails, handling errors, or running health checks.

No more ILocalizationService

The ILocalizationService no longer exists. It was a bit of an odd service with too many responsibilities. You could use it to manage content languages in Umbraco as well as manage the Umbraco dictionary. This functionality has now been split into two services: ILanguageService and IDictionaryService. It’s straightforward to use them, so you shouldn’t have much difficulty updating code that uses the IDictionaryService.

The ILocalizeTextService still exists and works the same as in Umbraco 13. It is the backend service for reading localization files using keys. This service still uses XML files and not the JavaScript files from the backoffice.

See the Umbraco 16 documentation on .NET localization for more details.

Localization in your extensions

I also want to briefly touch on localization in custom Umbraco extensions and provide some links to the documentation.

You can also reference localization keys directly in your extension manifests. For instance, this is an example of the title of a dashboard in the backoffice:

const UmbExtensionManifest: UmbExtensionManifest = {
    type: 'dashboard',
    ...
    meta: {
        label: "#dashboardTabs_contentExpirationDashboard"
        ...
    }
};

If you are building a custom Umbraco web component, make sure it inherits from UmbLitElement or uses the UmbElementMixin on the LitElement. If you do, you’ll get a helper for localization in your component:

import { LitElement, css, html } from "lit";
import { customElement } from "@umbraco-cms/backoffice/external/lit";
import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";

export default class MyElement extends UmbElementMixin(LitElement) {
    render() {
        return html`<uui-button .label=${this.localize.term('general_close')}>
        </uui-button>`;
    }
}

You can also use the umb-localize element in your component like this:

<button>
    <umb-localize key="dialog_myKey"></umb-localize>
</button>

This works the same way as the <localize> element in AngularJS back in Umbraco 13.

Read the documentation on using localization in Umbraco 16 for more information.

Because localizations are now in JavaScript, this opens up new possibilities. You can use arguments and placeholders in your localizations. For example, you can define a localization for singular and plural using the same key and an argument:

export default {
    section: {
        numberOfItems: (count) => {
            count = parseInt(count, 10);
            if (count === 0) return 'Showing nothing';
            if (count === 1) return 'Showing only one item';
            return `Showing ${count} items`;
        },
    },
};

Read the documentation on using arguments and placeholders in Umbraco 16 for more information.

Upgrade Umbraco 13 to 16: First upgrade steps

Luuk Peters — Tue, 26 Aug 2025 11:18:58 +0000

This is part two in a series of blogs about common things you'll encounter when updating Umbraco 13 to 16. In this part, we'll look into the prerequisites for an update, perform the first upgrade steps and fix a number of errors as a result of the upgrade steps.

Prerequisites

Let's look at what needs to be in place before you can start the update.

Umbraco 16 requires .NET 9, whereas Umbraco 13 used .NET 8. So you'll need to have .NET 9 installed on your development system. If you're using Visual Studio, you need at least version 17.12, which is the first version with .NET 9 support.

There are also two notable missing features in Umbraco 14+ that were still present in Umbraco 13 (although deprecated): Nested Content and Macros. You'll need to migrate these to Block Lists and Blocks, respectively. I prefer handling migrations while still on Umbraco 13, so everything is up-to-date before the upgrade and there's one less thing to worry about during the upgrade process. I might cover this in more detail in a future blog.

Lastly, before any update, always ensure you're on the latest Umbraco 13 version and using the latest compatible versions of all your packages. This gives you the best chance of a smooth upgrade.

Update .NET Version

The first upgrade step is updating the .NET version. Umbraco 13 uses .NET 8, while Umbraco 16 uses .NET 9. Simply update the Target Framework in all project files:

<!-- Original -->
<TargetFramework>net8.0</TargetFramework>

<!-- Updated -->
<TargetFramework>net9.0</TargetFramework>

Update NuGet Packages

Next, update all NuGet packages. Start with the Umbraco packages, then move on to the others.

Remove the Umbraco.Cms.Web.Backoffice package. This package no longer exists in Umbraco 16.
Update all Umbraco packages to the latest version (16.1.1 at the time of writing). Due to dependencies, updating via the NuGet Package Manager can be tricky. I usually update the version numbers directly in the project file(s) using find/replace.
Update all other NuGet packages. Be aware that some popular packages, like Contentment and SEOChecker, may not have final versions for Umbraco 16 yet. You might need to check for pre-release versions.

Once all packages are updated, you'll likely see a massive amount of build errors—this is expected. Let's fix some common ones.

Fix Caching and Especially the Models Builder

Umbraco 15 introduced the HybridCache as a replacement for NuCache. As a result, IPublishedSnapshotAccessor is no longer available. Any code using it needs to be updated.

Most errors will probably come from models generated by the Models Builder, as every generated model references IPublishedSnapshotAccessor.

Manually updating all models would be a waste of time. Fortunately, Søren Kottal wrote an excellent blog on how to fix this quickly:
Quick fix for IPublishedSnapshotAccessor issues

Outside of Models Builder, you can use IPublishedContentCache instead of IPublishedSnapshotAccessor. Updating the code should be straightforward.

Other Small Suggestions and Fixes

Larger topics—like updating UmbracoApiController, UmbracoAuthorizedApiController, and localization—will be covered in separate blogs. But here are a few small things you might run into:

You'll notice many more functions are now async. In most cases, it's just a matter of making the wrapping function async and using the await keyword.
If a function name has changed, it's usually obvious what the new name is. For example, Save functions are now often split into Create and Update.
It's not perfect yet, but most code now uses GUIDs for identifiers (e.g., for nodes or users).
This is reflected in the fact that UmbracoCore.Constants.Security.SuperUserId is deprecated. You now need to use UmbracoCore.Constants.Security.SuperUserKey.
Since SuperUserKey is not a constant, you can't use it as a default parameter value in functions anymore.

That’s it for now! Hopefully this gives you a solid start on upgrading to Umbraco 16. I’ll be covering more topics like API controller changes, localization tweaks, and migrating deprecated features in future posts. If you’ve run into anything interesting or hit a snag during your own upgrade, I’d love to hear about it—drop a comment or reach out!

Vibecoding a Mobile-Friendly Umbraco backoffice experience

Luuk Peters — Mon, 25 Aug 2025 12:13:44 +0000

One of the pain points of the new backoffice introduced in Umbraco 14, is that the backoffice is not mobile-friendly. This issue has been raised in this discussion on GitHub.

As of Umbraco 16, the experience on a mobile device is still far from usable. Buttons and navigation elements are either inaccessible or too small to interact with properly. Sure, you can switch your browser to “desktop mode,” but then the entire interface becomes tiny and awkward to use.

Now, I don’t expect every complex application to be perfectly optimized for mobile. Some things make sense only in a desktop context. But the lack of mobile usability makes even small edits or urgent fixes on the go impossible. And sometimes, that’s exactly what you need: just a quick update while you’re away from your laptop.

That got me thinking:

Since Umbraco 14, we have the Management API that technically allows us to build a completely different backoffice experience if we wanted to. What if we built a lightweight, mobile-focused backoffice—not with every feature, but just the essentials for content editing and publishing?

Vibecoding a Proof of Concept

So I decided to experiment. I started vibecoding with Claude, armed with access to an Umbraco MCP, the source code, and the documentation. The goal was clear:

Browse the content tree easily
Edit content and media
Save and publish changes
All in a mobile-friendly layout

Here’s what came out of it:

Some highlights of the prototype:

Browsing and selecting content happens in a modal to have the best overview.
Navigation elements are sized and spaced for mobile.
The functionality is deliberately minimal: save and publish only.

Why This Matters

This proof of concept isn’t about replacing the full Umbraco backoffice. It’s about reimagining what’s possible with the Management API and showing how a streamlined “editor on the go” could work.

There are still plenty of challenges to solve:

Handling complex property types like Blocks or Nested Content
Creating new content from scratch
Permissions and user flows

But even in its rough state, this little POC proves that a mobile-friendly backoffice is possible. And more importantly, it sparks inspiration: what if the future of Umbraco included a dedicated “mobile backoffice mode” built right into core?

For now, this vibecoded prototype shows that with a bit of creativity—and the power of the Management API—you can start bridging the gap.

Upgrade Umbraco 13 to 16: introduction

Luuk Peters — Fri, 08 Aug 2025 09:48:48 +0000

It feels like only yesterday that the current LTS version of Umbraco (Umbraco 13) was released. Yet by the end of this year, it will already be celebrating its second birthday — and that can only mean one thing: time for a new Umbraco LTS version! At the end of the year, Umbraco 17 will arrive alongside .NET 10, which will also be an LTS release.

Version 13 will still receive security updates until December 2026, but feature updates, regression fixes, and compatibility tweaks? Those are done. So, if you haven’t already, it’s time to start thinking about your Umbraco 17 upgrade plan.

The biggest change in Umbraco 17 compared to 13 is, of course, the completely new bellissima backoffice, built with web components instead of AngularJS — first introduced in Umbraco 14. That release also brought us the Management API, giving full control over Umbraco through an API. In the same release, we waved goodbye to Nested Content and Macros (probably for the best 😉). Then Umbraco 15 introduced the HybridCache (replacing NuCache), block-level variants, and the shiny new TipTap rich text editor.

As of now, Umbraco 17 isn’t out yet — not even a release candidate — but I don’t expect it to be drastically different from Umbraco 16. Version 16 was more of an evolution than a revolution compared to 14 and 15, with a strong focus on stability and performance rather than big new features. I expect Umbraco 17 will follow the same approach.

In this blog series, I’ll go over some of the most common changes you’ll encounter when upgrading from Umbraco 13 to 16 (and, by extension, 17).

Over the next few weeks, I’ll cover the following topics based on my experiences upgrading both Umbraco projects and packages to versions 15 and 16 (this list will be updated with links as the posts go live):

I’ll only lightly touch on the new backoffice in these posts. This series isn’t meant to be an advanced guide to backoffice extensions, so I won’t be covering Lit, Vite, or TypeScript here — those deserve their own blog series in the future.

Use the Umbraco MCP in your IDE with GitHub Copilot

Luuk Peters — Wed, 09 Jul 2025 13:22:48 +0000

At Codegarden 2025, we were introduced to the awesome first version of the Umbraco MCP by Matthew and Phil. And while still in development, it already shows great promise. As someone who uses GitHub Copilot daily, I wondered: Can I integrate Copilot with the Umbraco MCP in my IDE? Turns out—it’s totally doable.

For this example, I’m using Visual Studio on Windows 11, but the general approach should work on other operating systems and IDEs as well. The idea is to run the Umbraco MCP locally and connect GitHub Copilot to it so I can use it in Visual Studio. This way, when my local Umbraco instance is running, Copilot can query Umbraco for more context or even execute actions within Umbraco.

Before we can actually do anything with the mcp there are a few things we need to do first.

Install Node.js

The Umbraco MCP is written in Node.js and requires version 22 or higher. So we need to have Node.js installed on the machine that runs the mcp server, in this case my local development machine. You can get Node.js from their website.

Create an Umbraco API User

The mcp works with the management API that was introduced in Umbraco 14. To access the management API, you obviously need to be authorized to access it. So we need to create credentials for when the mcp is accessing the management API. This is done by creating an Umbraco API User in the backoffice of the Umbraco instance the Umbraco MCP needs to access.

I'm just giving the Umbraco API maximum access by making it an administrator because this is just for development. Obviously be careful in other scenarios!

Log into the Umbraco backoffice, go to the member section and create a new API User
An API User can have one or more client credentials. These are the credentials we need for the Umbraco MCP. So when the API User is created, open the details of the user and add new client credentials. Remember these credentials, we need them later. Also Assign access to all content and media.

Now that we have the prerequisites done, it's time to add the mcp server to GitHub Copilot. You need Visual Studio 17.14 or later for this.

Create an mcp file in the solution

Create a new file that will hold the Umbraco MCP configuration in the root of your solution: .mcp.json. This file will be solution scoped, but you can have other scopes by placing the file in other locations. See the official documentation for that.

Add the following server to the file, update the variables and save the file:

{
    "servers": {
      "umbraco-mcp": {
        "command": "npx",
        "args": ["@umbraco-mcp/umbraco-mcp-cms@alpha"],
        "env": {
          "UMBRACO_CLIENT_ID": "CLIENT_ID",
          "UMBRACO_CLIENT_SECRET": "CLIENT_SECRET",
          "UMBRACO_BASE_URL": "URL",
          "NODE_TLS_REJECT_UNAUTHORIZED": "0"
        }
      }
    }
  }

The CLIENT_ID and CLIENT_SECRET are the client credentials we set up for the API User in Umbraco. Make sure the base URL does not end with a /, so for instance: https://localhost:44327. And because I use a self signed certificate locally, I set NODE_TLS_REJECT_UNAUTHORIZED to 0.

As an example, I use this in my testproject:

{
    "servers": {
      "umbraco-mcp": {
        "command": "npx",
        "args": ["@umbraco-mcp/umbraco-mcp-cms@alpha"],
        "env": {
          "UMBRACO_CLIENT_ID": "umbraco-back-office-mcpuser",
          "UMBRACO_CLIENT_SECRET": "test123456!",
          "UMBRACO_BASE_URL": "https://localhost:44327",
          "NODE_TLS_REJECT_UNAUTHORIZED": "0"
        }
      }
    }
  }

Getting it up and running in Visual Studio

Open your Umbraco Visual Studio project. In agent mode, you will now see the Umbraco MCP in the tools list.

It will shown an error, because it cannot connect to our Umbraco instance because it's not running. Start your Umbraco instance and reload the tool. It should now show 195 available tools!

As long as your Umbraco instance is running, you can query your Umbraco instance from you GitHub Copilot chat. It will ask for permission the first time a tool is used and you can decide how long you want to grant permission before it will ask for permission again:

Visual Studio Code

For Visual Studio Code, the idea is the same. I haven't tried it, but the two main differences are:

You need to enable MCP support with a setting
The location of the .mcp.json file differs.

See the official documentation for Visual Studio Code.

Done!

We can now use the Umbraco MCP in Copilot as long as Umbraco is running! This was just an experiment to see if I could get it to work, the next step is to find out how this can help me during Umbraco development.

But it's already so cool to be able to talk to Copilot and have it access and manage Umbraco: