Migrating Major Versions and Updates - Optimizely CMS

Exam Area: Content Area 2 – Installation, Operation & Configuration (20%)
Reference: https://docs.developers.optimizely.com/content-management-system/docs/upgrade-to-cms-12

---

1. Upgrading CMS 11 → CMS 12

Key Differences:

---

2. Upgrade Assistant Tool

# Install the Upgrade Assistant
dotnet tool install -g upgrade-assistant

# Analyze the project
upgrade-assistant analyze ./MySite.csproj

# Run the upgrade
upgrade-assistant upgrade ./MySite.csproj

What the tool automates:

• Converts Web.config → appsettings.json
• Updates the target framework
• Replaces deprecated packages
• Fixes namespace changes

---

3. Breaking Changes in CMS 12

Namespace Changes:

// CMS 11
using EPiServer.ServiceLocation;  // ServiceLocator

// CMS 12 - Still available but prefer DI
using EPiServer.ServiceLocation;

IoC Container:

// CMS 11 (StructureMap/Unity)
[ServiceConfiguration(typeof(IMyService))]
public class MyService : IMyService { }

// CMS 12 (Microsoft DI)
// Register in Startup.cs
services.AddScoped<IMyService, MyService>();
// Or use IConfigurableModule

InitializableModule:

// CMS 11
[InitializableModule]
[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public class MyInit : IInitializableModule
{
    public void Initialize(InitializationEngine context)
    {
        context.Locate.Advanced.GetInstance<IContentEvents>()
               .PublishedContent += OnPublishedContent;
    }
    
    public void Uninitialize(InitializationEngine context)
    {
        context.Locate.Advanced.GetInstance<IContentEvents>()
               .PublishedContent -= OnPublishedContent;
    }
}

// CMS 12 (similar, but use MS DI in constructor)
[InitializableModule]
[ModuleDependency(typeof(ServiceContainerInitialization))]
public class MyInit : IInitializableModule
{
    private readonly IContentEvents _contentEvents;
    
    public void Initialize(InitializationEngine context)
    {
        _contentEvents = context.Locate.Advanced.GetInstance<IContentEvents>();
        _contentEvents.PublishedContent += OnPublishedContent;
    }
    
    public void Uninitialize(InitializationEngine context)
    {
        _contentEvents.PublishedContent -= OnPublishedContent;
    }
    
    private void OnPublishedContent(object sender, ContentEventArgs e) { }
}

---

4. Upgrade Steps: CMS 11 → 12

1. Backup the database and codebase
2. Check compatibility of all add-ons
3. Update target framework → net6.0
4. Update NuGet packages → v12.*
5. Replace Web.config → appsettings.json
6. Replace Global.asax/Startup → Program.cs
7. Update DI registrations → MS DI
8. Fix breaking changes (namespace and API changes)
9. Run database migration
10. Test thoroughly

---

5. Upgrading Optimizely (Minor Updates)

# Check for outdated packages
dotnet list package --outdated

# Update packages
dotnet add package EPiServer.CMS --version 12.x.x
dotnet add package EPiServer.CMS.UI --version 12.x.x

---

6. Database Schema Updates

# CMS runs schema updates automatically when AutoUpdateDatabaseSchema = true

# Production: Run manually
dotnet episerver database update

---

7. Add-ons Compatibility

# Check add-on compatibility
# See: https://nuget.optimizely.com/

# Update add-ons to versions compatible with CMS 12
dotnet add package EPiServer.Forms --version 5.*
dotnet add package EPiServer.Find --version 14.*

---

8. Post-Upgrade Checklist

• Database schema updated
• All content types still working
• Edit View accessible
• Admin View accessible
• Scheduled Jobs running correctly
• Forms working
• Search & Navigation working
• Add-ons compatible

---

Review Questions

1. Which IoC container does CMS 12 use? (Microsoft.Extensions.DependencyInjection)
2. What replaces Web.config from CMS 11 in CMS 12? (appsettings.json)
3. What replaces Global.asax? (Program.cs / Startup.cs)
4. How is the Upgrade Assistant installed? (dotnet tool install -g upgrade-assistant)
5. What is the first step when upgrading a major version? (Backup the database and codebase)