Module: Advanced content migration techniques

2 of 9 Pages

Understand the migration tool repository

✖
Copy to clipboard

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.

2 of 9