Yesterday, I completed a Media Library migration to Content Hub in a project, and I thought it would be great to share the complete experience here.
As most of you already know, Media Libraries have been officially sunset in Xperience by Kentico. Their related API members are now marked as obsolete, and support will end on July 24, 2026. After that date, the entire feature and associated APIs will be removed.
If your project still relies on Media Libraries, it’s the right time to start planning your migration. In our case, the client’s application was still using Media Libraries extensively, so we took the opportunity to move everything to Content Hub and adopt Content Item Assets, which is now the recommended and future-ready approach for managing media files in Kentico.
Why the Migration Was Needed
Media Libraries have been around for years and served their purpose well. However, they were tightly coupled with legacy APIs and didn’t align with Kentico’s new content modeling approach.
Content Hub, on the other hand, provides a centralized and structured way to manage all your digital assets. It offers:
- A more flexible content model
- Better metadata and permissions handling
- Integration with modern workflows
- Long-term compatibility with Kentico’s evolving architecture
For our project, moving to Content Hub was not only about compliance but also about future-proofing the solution.
Migration Overview
The migration process was smoother than I expected — thanks to Kentico’s built-in Media Library Migration Tool.
Here’s the overall process we followed:
1. Migrate Media Library files to Content Hub
2. Create a database backup
3. Set up the local development environment
4. Migrate fields referencing media files
5. Update the codebase
6. Deploy changes
7. Delete old Media Libraries
Let me walk you through each phase in more detail.
Step 1 – Migrate Media Library Files to Content Hub
This is the main step where all your existing media library files get converted into Content Item Assets.
Once I opened the Media Libraries application, I used the new migration option. When you click “Migrate Media Libraries”, Kentico creates a workspace named “Migration from Media Libraries” in the Content Hub.
Here’s what I really liked:
The folder hierarchy is fully preserved (e.g., a file in ~/AcmeLibrary/Icons/ stays under the same structure in Content Hub).
All GUIDs, custom fields, and system fields remain intact.
Permissions from the original media libraries automatically carry over.
Also, this is a non-destructive migration — meaning the original files remain in place, so nothing breaks during the process.
Once the migration finished, I verified the logs in the Event Log and confirmed everything migrated successfully.
Step 2 – Create a Database Backup
After completing the migration, I immediately took a full database backup of the environment.
This is an important step — it ensures you can safely roll back if anything goes wrong during later steps like field or code migration. I also implemented a short content freeze to prevent users from uploading new files during this phase.
Step 3 – Set Up the Development Environment
Next, I restored the backed-up database in my local environment to mirror the client’s production setup. This allowed me to run all migration scripts safely and test changes before pushing anything live.
Step 4 – Migrate Fields Referencing Media Files
This part required some command-line work. Kentico provides a .NET CLI script that migrates database definitions of fields referencing media files.
All fields of type Media files were updated to the new Pages and Reusable Content data type, and the Media file selector was replaced by the Combined Content Selector.
The best part is — the script is re-runnable, so if any field fails to migrate due to a naming conflict or schema issue, it logs an error and continues safely.
To run the migration, I used:
dotnet run --kxp-migrate-media-file-fields
This step ensures that all database-level references to media files now correctly point to Content Item Assets.
Step 5 – Update the Codebase
Now came the manual part — updating the code to remove references to obsolete APIs.
Here are a few key changes we made:
| Old API | New Replacement | Notes |
|---|---|---|
| MediaFileInfo | Generated model of content type | The content type must include a content item asset field. |
| MediaLibraryInfo | ContentFolderInfo | Represents folders inside Content Hub. |
| IInfoProvider<MediaFileInfo> | IContentItemManager | Used for programmatically managing content items. |
| AssetSelectorComponent | ContentItemSelectorComponent | Updated UI form component for asset selection. |
Some APIs like IMediaFileUrlRetriever and IMediaProtectionService don’t have direct replacements, but we implemented custom logic for asset URLs and resizing where needed.
Step 6 – Deploy Changes
After successfully migrating data and updating the code, we deployed the changes to the client’s environment.
We excluded the temporary MediaLibrariesMigration.MigratedMediaFile content type from the deployment package and ensured the Continuous Deployment restore mode was set to CreateUpdate.
Everything worked as expected on the first deployment — always a good feeling!
Step 7 – Delete Old Media Libraries
Once we verified all assets were functional and no broken links existed, we deleted the original Media Libraries from the environment.
I also updated the Role Management settings to remove permissions for the Media Libraries application, preventing any new legacy libraries from being created accidentally.
Redirects and URLs
Kentico does a great job handling redirects automatically.
All old ~/getmedia/... links are redirected to the new ~/getcontentasset/... URLs.
Important note: direct path URLs like ~/AcmeLibrary/coffee.png don’t get redirected, so we ensured no references relied on those patterns.
Conclusion
Overall, the Media Library to Content Hub migration was straightforward and well-supported.
It’s clear that Kentico is moving towards a modern, flexible, and content-first architecture, and this migration is an important step in that direction.
If you’re still using Media Libraries, I’d strongly recommend starting the migration early. It’s not just about compliance with the July 2026 deadline — it’s also about unlocking a more powerful and scalable way to manage assets.
This migration gave me hands-on experience with Kentico’s latest content architecture, and I must say — it’s a big leap forward for content management in Xperience.
Happy Learning.....See You Soon
Thanks
Top comments (0)