Migrate from Konstrukt to Umbraco UI Builder

Step-by-step guide to migrating a Konstrukt solution to Umbraco UI Builder.

This guide walks you through migrating a default Konstrukt solution to Umbraco UI Builder.

Key Changes

Before starting, review these key changes that impact the migration process.

Project, Package, and Namespace changes

Konstrukt	Umbraco UI Builder
Konstrukt.Core	Umbraco.UIBuilder.Core
Konstrukt.Infrastructure	Umbraco.UIBuilder.Infrastructure
Konstrukt.Web	Umbraco.UIBuilder.Web
Konstrukt.Web.UI	Umbraco.UIBuilder.Web.StaticAssets
Konstrukt.Startup	Umbraco.UIBuilder.Startup
Konstrukt	Umbraco.UIBuilder

Code and UI Changes

C# Class Changes

• Namespace changes as mentioned above.

• Most Konstrukt-prefixed classes have had the prefix removed.

  • Examples: IKonstruktRepository -> IRepository

  • Exceptions:

    • KonstruktConfig and KonstruktConfigBuilder now use a UIBuilder prefix.

    • AddKonstrukt extension for IUmbracoBuilder is now AddUIBuilder

JavaScript Changes

• All Konstrukt controllers are now under the Umbraco.UIBuilder namespace.

• All Konstrukt prefixed directives, services, and resources now use uibuilder.

UI Changes

• All static UI assets are now served via a Razor Compiled Library (RCL) instead of being stored in the App_Plugins folder.

• The App_Plugins/Konstrukt folder is now App_Plugins/UmbracoUIBuilder.

Step 1: Replace Dependencies

Replace all existing Konstrukt dependencies with Umbraco UI Builder dependencies.

1. Remove existing Konstrukt packages:

dotnet remove package Konstrukt

1. Delete the Konstrukt App_Plugins folder:

rmdir App_Plugins\Konstrukt

1. Install Umbraco.UIBuilder:

dotnet add package Umbraco.UIBuilder

1. Compile your project against .NET 7.0.

Step 2: Update Namespaces and Entity Names

Update all Konstrukt references to their Umbraco UI Builder alternatives. Ensure you update any Views/Partials that also reference these. See the Key Changes section for reference.

Step 3: Update Configuration

If your configuration is in a single statement, replace AddKonstrukt with AddUIBuilder.

For multi-step configurations using Action or Card classes, update the config builders and base classes to their UI Builder alternatives as described in Key Changes.

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .AddUIBuilder(cfg => {
        // The rest of your configuration
    })
    .Build();

Step 4: Finalize the Migration

1. Delete obj/bin folders for a clean build.

2. Recompile all projects and ensure all dependencies are restored correctly.

3. Remove existing Konstrukt license files from umbraco\Licenses folder.

4. Add your Umbraco.UIBuilder license key to the appSettings.json file:

"Umbraco": {
  "Licenses": {
    "Umbraco.UIBuilder": "YOUR_LICENSE_KEY"
  }
}

1. Run the project.