Navigate advanced upgrades

✖
Copy to clipboard

Upgrading from Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK) requires proper project structure, scenario planning, and effective use of AI tools.

This developer-focused resource covers how to structure upgrade repositories, match your scenarios to the right approach, and navigate to educational materials covering topics like advanced data and code migration, optimization, and AI-assisted development.

New to Xperience upgrades? Start with the hands-on walkthrough first, then return here for advanced project structuring and scenario planning.

Understand the migration tool repository

The Kentico Migration Tool repository contains multiple projects. For customization work, you’ll interact primarily with:

  • Migration.Tool.CLI/ - to configure the tool in appsettings.json and run the command-line executable
  • Migration.Tool.Extensions/ - to implement customization related to any content remodelling (e.g., mapping classes, transforming widgets, extracting reusable field schemas)
  • Migration.Tool.KX13.Extensions or Migration.Tool.KX13.NET48.Extensions - to copy controllers from when configuring the Page Builder content migrations

The remaining projects (Core.KX13, KXP.Api, Common, etc.) provide either shared or version-specific migration logic that runs automatically. Generally, you don’t need to modify these, with the exceptions of specific advanced scenarios (e.g., a custom command handler), and contributions to the tool’s development (features/bug fixes).

See the complete repository structure guide in the GitHub documentation.

Use a three-repository approach

For data migration you need:

  1. Your source instance
  2. Your target Xperience by Kentico instance
  3. A copy of the Kentico Migration Tool

We recommend you use a three-repository approach for upgrade projects with a clone of the migration tool repo per project.

Text
Example repository structure 

Your-Upgrade-Reporitory/
├── kx13-source/              # 1. Source KX13 instance
│   └── (existing KX13 code - largely unchanged)
├── xbyk-target/              # 2. Target XbyK instance  
│   └── (new XbyK code - evolves iteratively)
└── migration-tool-custom/    # 3. Kentico Migration Tool (+ customizations)
    ├── Migration.Tool.CLI/
    │   └── appsettings.json
    ├── Migration.Tool.Extensions/
    │   ├── ClassMappings/
    │   ├── CommunityMigrations/
    │   └── WidgetMigrations/
    └── docs/
        ├── decisions.md
        └── scenarios.md

Why a copy of the migration tool per project?
Each project needs unique migration tool customizations. Isolating the tool enables:

  • Version control for migration logic
  • Team collaboration on configurations
  • Records of migration decisions
  • Reusable patterns across migration runs

Git submodules let you include one Git repository as a subdirectory of another, so you can work with all three repositories (source, target, migration tool) from a single parent repository while tracking each independently.

Advanced upgrade tasks - decision tree

Most migrations require combining multiple strategies. Match your scenarios below to find the right approach and implementation guide.

Missing guidance for your scenario? Use the Send us feedback button at the end of the page. We continuously add guides based on partner and client feedback.

Choose what you want to do:

Remodel content

Flatten the content tree

Add structure to your data

Preserve content hierarchies

Transform Page Builder widgets

Upgrade content retrieval code

Optimize media

Utilize AI to speed up data and code migration

Get help and support