Migrate your code and adapt your project

While sites built on Kentico Xperience 13 (KX13) and Xperience by Kentico (XbyK) are all .NET applications, there are some differences in the code to consider when migrating to XbyK, and considerations for where to go with a project once it is on the new platform.

This guide will provide more details about the points from the later top-level sections of the migration overview.

Migrate your code

Update content querying code

Xperience by Kentico uses the Content item API to query content, in place of DocumentQuery and MultiDocumentQuery from Kentico Xperience 13.

The documentation in the above link has more information about the specifics of how it works, but in broad strokes, here are the steps to retrieve content:

• Use a ContentItemQueryBuilder object to construct a query.
  • Apply one of the ForContentType or ForContentTypes extension methods to filter the query based on system aspects of the content type. For example, whether content items include a given reusable field schema, whether they link to or are linked from another item, and whether they are part of a given website channel.
  • Call the Parameters extension method to add standard query operations like OrderBy and Where conditions that test the values of the content type’s fields.
  • Call the InLanguage extension method to determine which language versions of content items Xperience should retrieve.
• Use an IContentQueryExecutor to get a result from the query.

We recommend creating some kind of shared resource that you can use across your project to centralize content querying logic, such as a service.

There are some notable changes in related functionality as well:

• PageDataContext and IPageDataContextRetriever are now WebPageDataContext and IWebPageDataContextRetriever.
  • Unlike the Page property of PageDataContext in KX13, XbyK’s WebPageDataContext does not contain the full page data. It contains a RoutedWebPage object with information you can use to retrieve the correct page.
• KX13’s IPageUrlRetriever corresponds to IWebPageUrlRetriever, which now works asynchronously.
• The Kentico migration tool converts page attachments to media library files, and the page type fields that represent them now contain AssetRelatedItem objects. You can use information from this object to look up a media file, and then retrieve its URL with an IMediaFileUrlRetriever.

Adjust Page Builder components

In Kentico Xperience 13, Page Builder components such as widgets, page templates, and sections use C#-based editing components for their properties. These editing components are assigned to properties using attributes such as this one:

// Assigns the 'TextInputComponent' as the editing component of the 'TextProperty' property
[EditingComponent(TextInputComponent.IDENTIFIER)]
public string TextProperty { get; set; }

Xperience by Kentico supports the same format for the sake of backward compatibility, but primarily uses a new format of UI form components. These components are assigned using dedicated attributes, for example:

// Assigns the 'TextInputComponent' as the editing component of the 'TextProperty' property
[TextInputComponent(Label = "Enter text")]
public string TextProperty { get; set; }

If you chose to enable Source instance API discovery during data migration, you will need to change the attributes used by the properties of your Page Builder components to the new UI form components.

Rehome custom tables

Xperience by Kentico does not have a direct analog for the Custom tables functionality in legacy Kentico products.

The Kentico migration tool creates a custom object type for each custom table, but leaves you in charge of defining their user interface.

If you choose to do so, each custom table will correspond to an object type or class, and each custom table row will correspond to an object of that type. You’ll need a UI application page to host one or more custom tables to define the following parts for each of these custom table types:

• An alternative form that determines which form controls Xperience should render for each field of the object type
• A listing page that displays a list of the objects and includes delete functionality
• An Edit section and an Edit page that allow editors to alter the values of individual objects
• A Create page to add new objects

You can choose whether each type should have its own UI application page or if they should be located collectively beneath the same application page.

This may sound complicated, but these basic operations are fairly simple to implement, and you can find an example of building such a UI in our training guides. The CLI tools in this repository can help to speed up the process.

We recommend this approach when it is important for your client to edit the values in a dedicated area of the UI.

If custom table data does not need to be separate from other content, we recommend using reusable content items instead.

If you define a reusable content type corresponding to each custom table and write a one-time script that creates reusable content items you will not need to build a dedicated UI for the existing types, or any similar types your client might want in the future.

Editors can use the Content hub to manage the items. By selecting a content type in the content hub’s filter, they can view the custom table’s data.

Convert custom module pages

Xperience by Kentico’s admin UI no longer runs on web forms, so you’ll need to recreate any custom module pages as UI pages in XbyK.

Most custom modules revolve around performing basic operations on custom objects, so in many cases, the previous heading’s guidance about the types of pages you’ll need still applies.

Xperience by Kentico also supports custom page templates, if your scenario requires more advanced customization. You can find an example in the admin boilerplate project.

You can find resources covering the process of creating custom modules with complex hierarchical structures in the training guides.

You can find general guidance and reference material in the admin UI documentation.

Alter auth and user management

Xperience by Kentico introduces a new Member object type to represent people who register and sign in to the live site. Your team must change old registration and authentication code to work with the changes.

The approaches are fairly similar, as both utilize ASP.NET Identity, but syntax has changed. You’ll need to make some alterations to your controllers and initialization.

Multi-factor authentication is not natively supported for Xperience by Kentico at this time. It is on the roadmap for relase in an upcoming refresh.

Choose a search integration

Xperience by Kentico does not support search functionality natively, but it has three search integrations:

• Lucene
• Azure AI search
• Algolia.

Each integration has its own specifics regarding how the code should look, so we recommend reviewing the docs folder of the one you choose for specific advice on how to structure its code.

Address differences in localization

Xperience by Kentico uses Languages, where KX13 used Cultures.

In cases where you want to know the preferred language of current site visitor you can use IPreferredLanguageRetriever.

As mentioned earlier, you can use the InLanguage extension method for content item query to determine which variant of content items Xperience should retrieve.

Note that languages are global in XbyK, so if you have KX13 code to retrieve cultures associated with a given site, you’ll need to adjust it to account for this.

Localization of resource strings

Editors in Kentico Xperience 13 were able to define custom resource strings in the administration interface. This functionality doesn’t exist natively in XbyK, and there are a few possible approaches to handle custom resource strings.

• Move them to a resource file - If you move custom resource strings to a resource file, you can resolve them easily in your application. This, however, does not allow your editors to create new strings.

• Use the content hub - If you want to allow editors to create strings, you can create a reusable content type to represent a string. Editors will create language versions of this type in the Content hub. Then, in code, you can dynamically look up the appropriate translation via the Content item API, for example, in your custom IStringLocalizer and IHtmlLocalizer implementations.

• Use the Community localization module - If it is important to your client to have a separate localization module to manage their custom resource strings rather than working in the content hub, consider the Xperience community localization module by Nittin, which recreates the experience from KX13.

• Implement your own custom module - If your project requires a specific way of handling resource strings, your team can create a custom implementation using the XbyK custom module that suits your client’s needs.

Migrate commerce

Since Xperience by Kentico does not yet support commerce natively, the way your code will need to change will depend heavily on which service you choose to integrate with.

If you choose the E-commerce bridge integration, you can leave calculation logic unchanged on the KX13 side. Then, you can use the approaches exemplified in the repo to list products and interface with the KX13 shopping cart from the XbyK side.

If you choose to migrate your commerce to Shopify and use the Shopify integration, you won’t need your calculation and checkout code, as these things are handled directly in Shopify. From the Xperience side, you’ll need to add code to manage the contents of shopping carts and discount coupons.

Handle marketing changes

XbyK and KX13 both feature online marketing, but key differences exist. Let’s take a look into some of them.

When you log custom activities from server-side code in Xperience by Kentico, use ICustomActivityLogger instead of IActivityLogService. Custom activities no longer need an initializer class for the logger to work. Note that XbyK also allows you to log custom activities with client-side code.

Custom automation steps like those in Kentico Xperience 13 are not currently available, so you can archive their code for now.

Since A/B tests are not supported natively, you can also archive any code related to them, such as custom conversions.

Regarding marketing and consents, note that you should register custom cookies by configuring CookieLevelOptions during startup, rather than using CookieHelper. Additionally, set cookies in the visitor’s browser using ICookieAccessor.

Think about the future

Adapt your content model

Xperience by Kentico offers new content modeling features that can help you modernize your project’s structure.

It allows channel-specific items like web pages and mobile app screens to hold fields their channel needs, while referencing reusable content stored in a central Content hub.

In order to convert flat KX13 pages that contain both web-specific fields and content fields into this new structure, you can follow these general steps:

1. Create a new reusable content type that has all the same fields as your web page type.
2. Add a Content items field to the Web page content type, referencing an item of the reusable content type.
3. Create a one-off script that utilizes Xperience APIs to do the following:
   1. Create a new item of the reusable type, copying all the values of their matching fields.
   2. Reference the new reusable item from the web page item’s Content items field.
4. Delete all the web page-specific fields from the reusable content type.
5. Delete all the content-specific fields from the web page content type.

Utilize new capabilities

Reusable field schemas

Similarly to the above approach for reusable content items, you can create one-off scripts to help convert common fields that exist in several content types into reusable field schemas.

Just add the schema to all the child content types, write a one-off script to copy content from the old fields to the schema fields, and then delete the old fields.

Taxonomies

If you want to start taking advantage of taxonomies, you’ll have to consider how to hierarchically structure the tags to best fit your content model. Then, you can filter content queries based on taxonomies, as in this example.

Smart folders

If your editors utilize smart folders, you can incorporate their contents into the live site and filter content item queries.

What’s next?

We hope you feel a little more prepared for the migration after this series of guides.

Let us know if you come across anything that needs additional explanation over the course of your migration, and we will do our best to cover it in future materials.

In the meantime, you can find more information on the migration process in the documentation and the Xperience by Kentico: Kentico Migration Tool repository. For additional context, check out this blog by Jeroen Fürst of TrueLime, who put together useful tips and key things to consider before the KX13 to XbyK migration.