Explore. Build. Grow
Explore. Build. Grow

Our flexible three-stage framework to craft digital experiences.

Learn more
Expertise
Outcomes
View our portfolio
View our portfolio

Explore our range of digital solutions.

Learn more
Industries
Optimizely
Optimizely

Kentico
Kentico

Umbraco
Umbraco

DXP
Headless
Cloud Platforms
Marketing Optimisation
Contact Us
Contact Us
Explore. Build. Grow
Explore. Build. Grow

Our flexible three-stage framework to craft digital experiences.

Learn more
Expertise
Outcomes
View our portfolio
View our portfolio

Explore our range of digital solutions.

Learn more
Industries
Optimizely
Optimizely

Kentico
Kentico

Umbraco
Umbraco

DXP
Headless
Cloud Platforms
Marketing Optimisation
Contact Us
Home / Insights / ＿

Hot tips for upgrading to Kentico Xperience 13

Solutions Architect Thai Tran offers some helpful tips to help you succeed in your upgrade to Kentico 13.

Thai Tran
Thai Tran

11 May 2022

10 minute read

Kentico Xperience (formerly known as Kentico EMS) is a digital experience platform (DXP) that offers a content management system (CMS), digital marketing, and e-commerce tools. It allows content creators and marketers to create a seamless digital experience from a single platform.

The latest major version of Kentico's flagship DXP is Kentico Xperience 13. This major release brings significant changes to developers and adds support for ASP.NET Core in .NET 6. Previous versions of Kentico Xperience only supported ASP.NET MVC in .NET Framework.

Among its many benefits, .NET 6 offers huge performance improvements, new features, and security updates. Upgrading existing Kentico sites to version 13 will also add additional years of long-term support when using .NET 6. According to Kentico, the flagship product will be supported beyond 2026: Product support lifecycle policy.

Although getting to Kentico Xperience 13 is not a simple one-click upgrade, the upgrade is still possible but it will require custom code to be migrated from .NET Framework to .NET 6. The time required to upgrade a Kentico site depends on its size and complexity. 

Kentico Xperience is now MVC-first

Using MVC - rather than the older WebForms, or ‘Portal Engine’ approach - is considered best practice for building all new Kentico Xperience projects, and will therefore be the only technology supported going forward. 

If you’ve been on Portal Engine and wish to stay supported, you might want to consider rebuilding completely on the latest Kentico Xperience 13 for MVC. This article, however, will only cover what you should know when upgrading from a Kentico version 10 or newer MVC project to Kentico Xperience 13. 

Luminary CTO Andy Thompson has also thoughtfully explained the differences between a rebuild and an upgrade in this blog post: How should I upgrade Kentico Xperience?

Application architecture

There are several web applications and databases within a Kentico Xperience solution. Web applications can be categorised into two main types, namely CMS (Admin interface) and content delivery (front-end) sites.

Application architecture

Web applications

The CMS Admin interface is used to create, edit and publish the content to the content delivery sites which are accessible to the general public. 

Kentico Xperience allows us to add multiple sites and languages to the same installation. Each installation can use a single CMS to manage content for multiple content delivery sites. These applications must use the same database connection strings and have web farms enabled.

Databases

If online marketing is enabled, you can enable database separation in Kentico Xperience to store its data in a separate database.

Target frameworks

Kentico Xperience separates the CMS Admin interface from the content delivery sites and they require different target frameworks.

The CMS application (Admin interface) is a traditional ASP.NET Web Forms application using .NET Framework, as opposed to the content delivery site (front-end) which is a modern MVC application using either .NET Framework or .NET 6.

Target frameworks

.NET 6 is a new stack and it doesn’t replace .NET Framework (For a guide to these frameworks, check out this article by our CTO, Andy Thompson: What does .NET Core mean for me and my DXP?). Released by Microsoft in Nov 2021, .NET 6 is the latest version of .NET and it will be supported for three years as a long-term support (LTS) release. ASP.NET Core is based on .NET 6 but retains the name ‘Core’ to avoid confusing it with ASP.NET MVC in the .NET Framework.

Libraries

Kentico Xperience libraries can be installed on the content delivery sites from NuGet packages.

The Kentico.Xperience.Libraries package uses .NET Standard 2.0 and can be installed on any class library project.

For a .NET 6 application, only the Kentico.Xperience.AspNetCore.WebApp package needs to be installed.

For an ASP.NET MVC (.NET Framework) application, only the Kentico.Xperience.AspNet.Mvc5.Libraries and Kentico.Xperience.AspNet.Mvc5 packages are needed.

Kentico Xperience 13 and older versions do not use the same NuGet packages. If the following packages are used by your project, they must be uninstalled before you can install the new packages for Kentico Xperience 13:

Kentico.Libraries
Kentico.LanguagePack.English
Kentico.Libraries.Tests
Kentico.AspNet.Mvc
Kentico.Libraries.Web.UI
Kentico.AspNet.Mvc.Libraries
Kentico.Glimpse

These packages are used for Kentico Xperience 12 but can't be used with Kentico Xperience 13.

The CMS app can't be installed or upgraded from NuGet packages but it can be done using Kentico Installation Manager (KIM). The libraries will be added to the Lib folder that should be checked into the source control. If the solution has multiple projects, you must use the same hotfix or release version of Kentico for all projects within the solution.

Do the right tasks in the right order!

To make it easier, I'd recommend you perform the upgrade in the following order:

  1. Download and install the latest version of KIM and use it to upgrade the CMS to version 13
  2. Upgrade the databases separately by executing the SQL scripts from this folder: C:\Program Files (x86)\Kentico\13.0\Upgrade120_130\SQL\Separation
  3. Apply the latest hotfix to the CMS using KIM
  4. Apply the database hotfix by executing the SQL scripts from the hotfix folder: C:\Program Files (x86)\Kentico\13.0\Hotfix130_XX\SQL
  5. Add a new project targeting .NET Framework 4.8 for ASP.NET MVC or .NET 6 for ASP.NET Core. Install Kentico Xperience 13 NuGet packages and migrate features from the old applications

Xperience 13 features

After the upgrade is finished, you will be taken to the new Kentico Xperience administration interface, and voila! 

Xperience 13 features

Here are some hot tips for getting the most out of the latest and greatest version of Kentico Xperience and .NET 6. These bits are technically not required for the upgrade but you should really do it!

1. HTML extensions

Kentico Xperience 13 extends the IHtmlHelper interface in .NET 6 to offer many HTML extensions out-of-the-box for view templates. Here are the most common ones:

Page Title

@Html.Kentico().PageTitle()

Page Description

@Html.Kentico().PageDescription()

Page Builder Styles

@Html.Kentico().PageBuilderStyles()

Page Builder Scripts

@Html.Kentico().PageBuilderScripts()

Resolve URLs

@Html.Kentico().ResolveUrls(someText)

Resolve dynamic text in rich-text

@Html.Kentico().ResolveRichText(richText)

Render inline editor for a property

@Html.Kentico().BeginInlineEditor("inlineEditorName", "propertyName")

Canonical URL (extending IUrlHelper)

@Url.Kentico().PageCanonicalUrl()

These extensions are also available as tag helpers in .NET 6. For example, instead of using @Html.Kentico().PageBuilderStyles() to render the page builder styles markup, you can also use the <page-builder-styles /> tag helper in your templates. Don't forget to add the following directive to import these tag helpers.

@addTagHelper *, Kentico.Web.Mvc

You may also want to add custom implementation to your solution. For example:

public static IHtmlContent PageNoIndexNoFollow(this 
HtmlHelperExtensionPoint htmlHelper

These common extensions should be utilised as they could save you a lot of time when working with Kentico Xperience 13.

2. Widgets

Widgets are reusable components in the page builder to give content editors the flexibility when editing page content. The ASP.NET MVC (.NET Framework) application and the ASP.NET Core (.NET 6) application differ in the implementation of widgets.

In the ASP.NET MVC (.NET Framework) application, a widget is a controller that inherits the WidgetController and outputs a partial view result from the Index action.

public class CustomWidgetController : 
WidgetController<CustomWidgetProperties>

Custom widgets can be registered using the RegisterWidgetAttribute with the controller type parameter.

[assembly: RegisterWidget("CustomWidget", 
typeof(CustomWidgetController), "Custom widget")]

When converting from an ASP.NET MVC (.NET Framework) application into an ASP.NET Core (.NET 6) application, this widget controller must be converted into a view component that inherits the ViewComponent and outputs an instance of the IViewComponentResult interface from the Invoke() or InvokeAsync() method.

public class CustomWidgetViewComponent : ViewComponent

Custom widgets can also be registered using the RegisterWidgetAttribute with the view component type parameter.

[assembly: RegisterWidget("CompanyName.CustomWidget",
typeof(CustomWidgetViewComponent), "Custom widget")]

3. Dependency injection (DI)

Kentico recommends developers use DI to instantiate objects from their classes.

Dependencies are best to be injected into the constructors of non-static classes. They can also be resolved in the methods of static classes which are not allowed to have instance constructors.

public class PageService
{
   readonly PageDataContextRetriever _pageDataContextRetriever;
   public PageService(IPageDataContextRetriever pageDataContextRetriever){
      _pageDataContextRetriever = pageDataContextRetriever
   }
}

This example uses the constructor parameter DI to get an instance of the IPageDataContextRetriever and sets it to a read-only field which can be used to retrieve the page context later on.

If your class cannot have instance constructors, you can also get an instance of the IPageDataContextRetriever using the following method:

public static class PageContextHelper {
   public static TreeNode CurrentPage() {
      Service.Resolve<IPageDataContextRetriever>().TryRetrieve(out
IPageDataContext<TreeNode> data);
      return data?.Page;
   }
}

Kentico Xperience 13 allows developers to register custom dependencies to the service collection in several ways. If you're using ASP.NET Core in .NET 6, you can register your classes or interfaces and their implementation in the Startup as follows:

services.AddSingleton<ArticleRepository>();

Alternatively, the implementation can be registered using the built-in RegisterImplementationAttribute as follows:

using CMS;
[assembly:RegisterImplementation(typeof(ISitemapRepository),
typeof(SitemapRepository), Lifestyle =
CMS.Core.Lifestyle.Transient)]

4. Provider objects

If you've worked with Kentico Xperience before, you know that you can use its data providers to retrieve data from the database. For instance, the SettingsKeyInfoProvider provides access to the settings keys:

var settingsKeyInfo =
SettingsKeyInfoProvider.GetSettingsKeyInfo("KeyName");

The SettingsKeyInfoProvider implements the INotManagedByContainer interface and is not managed by the IoC container.

However, in Kentico Xperience 13, you can use the ProviderObject property of an info provider to get or set a provider instance that is managed by the IoC container.

var settingsKeyInfo =

SettingsKeyInfoProvider.ProviderObject.Get("KeyName");

Setting the provider instance must be performed before IoC container initialisation finishes.

5. Page retrievers

It's not uncommon in Kentico Xperience projects to retrieve data from the current context. For example, you can get the page info from the DocumentContext in older versions. The proper way of achieving this in Kentico Xperience 13 is to use context retrievers.

public class Index([FromServices] IPageDataContextRetriever dataContextRetriever, [FromServices] IPageRetriever pageRetriever)
{
   var section = dataContextRetriever.Retrieve<TreeNode>().Page;
   var articles = pageRetriever.Retrieve<Article>(query => query.Path(section.NodeAliasPath, PathTypeEnum.Children))
   return View(articles);
}

The IPageDataContextRetriever provides an interface for retrieving the data context of the current page and the IPageRetriever can be used for retrieving the pages based on the given parameters.

Best practices

1. Think big! Start small

Upgrading a Kentico Xperience solution could be either straightforward or tricky depending on the size and complexity of the previous implementation. For instance, a simple widget can be subject to multiple service dependency levels. Trying to upgrade all widgets and their dependencies at once will send us down a rabbit hole. In addition, some legacy code has been made obsolete in Kentico Xperience 13. Therefore, it might be good to break down a more complex project into feature-based components that could be migrated independently to the new version.

Before starting the upgrade, you might want to consider documenting all existing features and customisations that are used on the current websites, including routing, caching, logging, handlers, etc. If you're a sole developer, you might want to keep the audits and log the progress as you go in a spreadsheet. If you work together in an Agile team that has access to JIRA, you might want to add these tasks to JIRA and provide some criteria for acceptance and estimation.

In addition, when converting a project from .NET Framework to .NET 6, it might be best to start over from an empty project and gradually migrate over the features.

When adding multiple projects to a solution, remember to set up the project dependencies and review the build order. The upgrade should start from the library class projects before any MVC projects.

2. Get backups before you get knocked down

Chances are pretty low that we'll do it right the first time. We should always remember to take backups and set restore points as we go. If you don't use any Git or SVN version control systems, you might want to consider adopting one and following the best practices.

Assume that there's already been a Git repository for the legacy sites. To reduce complexity and speed up development, I'd recommend you not to git push straight to the same repository. However, you should clone it so that you could keep the old version as a reference when gradually migrating over the features to the new version. Pushing commits is cheap when using Git. That said, you should also write descriptive and relevant commit messages and commit only the lines that make sense together.

3. Invest your time

Upgrading a version 10 or older version to Kentico Xperience 13 is an achievable but time-consuming task. If there are other active developments on the current legacy sites, the upgrade gets more difficult. Lead times should be carefully calculated and accounted for to give you and your team enough time to finish the upgrade. It might be a good idea to set goals with the key results and estimations, and detail any anticipated risks before you start the upgrade.

Conclusion

With a huge performance improvement and .NET 6 support, alongside additional features that will lead to increased productivity and efficiency, Kentico Xperience 13 actively works to provide tangible benefits to developers. While there may be potentially a large effort, it is a worthwhile investment to upgrade to Kentico Xperience 13 from an older version to stay supported and to take full advantage of the Kentico DXP. 

If all of this sounds a bit daunting, come talk to us at Luminary and we can give you a hand to upgrade your Kentico website to the latest version.

Thai Tran
Thai Tran

11 May 2022

10 minute read

Enjoyed this article? Share it...

Considering a Kentico upgrade?

Speak to one of our Kentico experts about keeping your platform up to date.

Get in touch

Keep Reading

Want more? Here are some other blog posts you might be interested in.

Follow
Contact Us
1300 554 891
hi@luminary.com

Our locations

Stay informed
Our best articles, observations and news delivered to your inbox
Subscribe
Flags

We acknowledge the Traditional Custodians of the land on which we work, live and engage. We pay respect to Elders past and present.

Luminary is a registered trademark of Luminary Digital Pty Ltd

Terms of Services
Privacy Policy