Updates and Patches - Optimizely CMS 12

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

---

1. NuGet Package Updates

CMS 12 components are distributed as NuGet packages. Update via .NET CLI or Package Manager:

# Check for outdated packages
dotnet list package --outdated

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

# Or update all in Visual Studio: right-click solution → Manage NuGet Packages

---

2. Semantic Versioning

MAJOR.MINOR.PATCH  e.g.  12.4.2

MAJOR  → Breaking change (e.g. CMS 11 → CMS 12)
MINOR  → New features, backward compatible
PATCH  → Bug fixes and security patches, backward compatible

CMS 12 uses the format:

EPiServer.CMS  12.MINOR.PATCH
                ↑
                Always 12 (the major version we're studying)

---

3. Before Updating

Checklist:

1. ✅ Read the Release Notes / Changelog for the target version
2. ✅ Check for breaking changes and migration notes
3. ✅ Update in a development environment first
4. ✅ Run the full test suite
5. ✅ Take a database backup before deploying to production
6. ✅ Check all add-on package compatibility (EPiServer.Forms, Find, etc.)
7. ✅ Review deprecated APIs that may affect your code

---

4. Database Migrations

CMS automatically applies database schema changes on application startup:

Application starts → CMS checks DB schema version
    ↓
If schema version < required version:
    → Runs pending migration scripts automatically
    → Logs: "Database upgrade from version X.Y to X.Z complete"
    ↓
Application continues startup

Exam tip: You do not need to run SQL scripts manually. CMS handles DB migrations automatically. However, always backup first.

---

5. DXP Update Process

For deployments to the Optimizely DXP (Azure PaaS):

1. Create deployment package (.zip via msdeploy or Deployment API)
2. Upload to Integration environment
3. Smoke test Integration
4. Promote to Preproduction
5. Full regression test on Preproduction
6. Schedule maintenance window (if needed)
7. Promote to Production
8. Monitor Application Insights for errors

---

6. Deployment API (DXP)

# Using Optimizely Deployment API CLI
epi-deployment deploy \
  --environment integration \
  --package ./deploy.zip \
  --project-id <your-project-id>

---

7. Rolling Back

If an update causes issues:

DXP Portal → Deployments → Previous deployment → Re-deploy
  → Optionally restore database from pre-upgrade backup

Warning: Rolling back the application without also restoring the database can cause schema mismatch if the new code ran DB migrations.

---

8. Add-on Compatibility

After updating CMS core, check add-on compatibility:

# Common add-ons that need version matching:
EPiServer.Find          → Must match major CMS version
EPiServer.Forms         → Check release notes
Optimizely.CMS.UI.React → Check release notes

---

9. Zero-Downtime Deployments

Best practices for production updates with minimal downtime:

1. Deploy new code to servers in a rolling fashion (one at a time)
2. Use health checks (/health) to verify each server before switching traffic
3. Keep DB schema backward compatible during the transition
4. Use feature flags to enable new features after all servers are updated

---

Review Questions

1. Does CMS apply database migrations manually or automatically? (Automatically on application startup)
2. What does PATCH in semantic versioning mean? (Bug fixes and security patches — backward compatible)
3. What should you always do before deploying a CMS update to production? (Take a database backup)
4. What happens if you rollback the application code but don't restore the database? (Schema mismatch — the old code may not be compatible with the new DB schema)
5. In DXP, which environment should you test on before promoting to Production? (Preproduction)