An Episerver upgrade can involve much more than changing the CMS version. The work depends on where your site is starting, which Optimizely version you are moving to, and how much custom functionality has been built around the CMS.
Most sites have more than the CMS to account for. There may be custom APIs, third-party packages, search, external integrations, content models, and frontend applications that all depend on the current setup. A major version upgrade can affect any of them.
For example, upgrading to Optimizely CMS 13 requires moving to .NET 10 and addressing changes to platform APIs and package architecture. Search, content delivery, and Graph implementations may also need changes depending on how the existing site is built.
So before estimating development hours, start with a simpler question:
What needs to change between our current setup and the target Optimizely version?
In this Episerver upgrade guide, we’ll walk through the key technical areas you should review before starting development.
What to Consider Before an Episerver Upgrade
Before finalizing the scope, review the parts of the application that depend on the current CMS and framework.
CMS and Framework Changes
A major CMS upgrade can also mean a framework upgrade. You may also need to update container configurations, build pipelines, hosting infrastructure, and runtime dependencies.
Check:
- Current and target .NET runtime versions
- Hosting environment and infrastructure requirements
- Docker and container configurations
- Continuous Integration and Deployment (CI/CD) pipelines
- Framework-dependent libraries and extensions
API and Platform Changes
Major platform releases can remove deprecated APIs or change how existing services work.
Before upgrading, check for:
- Compiler deprecation warnings in the existing solution
- Removed interfaces, classes, and namespaces
- Changes to serialization and dependency injection
- Custom UI extensions and editor add-ons that rely on older endpoints
Packages and Custom Code
You need to review every Optimizely and third-party package against the target version.
With CMS 13 changing how NuGet packages are structured, some packages that were previously included as transitive dependencies in CMS 12 now require explicit PackageReferences, so you’ll want to check that nothing is missed during the upgrade.
Search and Content Delivery
Keep your search early because a CMS upgrade can affect the underlying technology.
- If your current implementation uses Search & Navigation, check what needs to change for the target CMS version. Optimizely documents Optimizely Graph and third-party search providers as options for CMS 13.
- If your site uses Optimizely Graph, check existing queries against the target schema, as they can affect how the frontend retrieves and displays content.
- For headless implementations, test existing content delivery flows rather than assuming they will work after the CMS upgrade.
Integrations and Frontend Applications
Review every application or service that consumes content or exchanges data with the CMS, including:
- Content Management and Content Delivery APIs
- Optimizely Graph endpoints
- Custom web APIs and webhooks
- ERP, CRM, PIM, DAM, and ecommerce platforms
For example, changes to Content Delivery API 13, including route prefixes or JSON serialization, can require updates to connected frontend applications.
Once you’ve identified what could be affected, the next step is to turn those findings into a clear upgrade plan.
How Do You Plan an Episerver Upgrade? – Step-By-Step Guide
Step 1: Start With Your Current Version
- Document the production environment before defining the target requirements.
- Capture the current CMS and framework versions, third-party libraries, custom extensions, search solution, API consumers, frontend setup, and deployment infrastructure.
- Then map each component against the target environment:
Current State → Target State → Technical Impact - This makes it easier to see where the upgrade will require code changes, package replacements, migrations, or additional testing.
Step 2: Define Scope and Work Items
Translating your technical findings into clear development tasks requires auditing everything from custom business logic to third-party endpoints.
If your internal team lacks the bandwidth to audit every custom integration and package dependency, bringing in specialized Optimizely upgrade services can help define the technical roadmap and de-risk the deployment.
| Area | Current | Target | What to Check |
|---|---|---|---|
| CMS | Current CMS version | Target CMS version | Upgrade path and breaking changes |
| Framework | Current .NET | Required .NET | Application and hosting compatibility |
| Packages | Current package versions | Target versions | Package availability and dependencies |
| APIs | Current APIs | Target APIs | Removed or changed APIs |
| Search | Current search solution | Supported target solution | Migration or replacement requirements |
| Integrations | Current endpoints | Target endpoints | Client-side changes |
| Frontend | Current implementation | Target implementation | API and content delivery compatibility |
Step 3: Separate Your Upgrade Work From Optional Improvements
An upgrade can uncover other technical issues. That does not mean all of them belong in the upgrade scope. Keep unrelated work separate unless it is required for the upgrade.
Optional enhancements can include:
- Template redesigns
- UX changes
- Content architecture changes
- Unrelated technical debt refactoring
Step 4: Test the Changes That Actually Matter
Testing should focus on the parts of the application that changed.
Prioritize:
- Editorial workflows and content publishing
- Page rendering and layout templates
- Web forms
- Search indexing and query results
- Graph queries and REST API endpoints
- Data movement across external integrations
- URL routing and redirects
- Analytics tracking
Step 5: Plan the Production Move
Once staging testing is complete, document how the upgraded application will move to production.
The plan should cover:
- Integration dependencies
- Content editing restrictions, if required
- Deployment sequence
- Post-deployment checks
- Rollback conditions
The rollback plan should answer one practical question:
What will we do if a critical upgrade issue appears after deployment?
The answer depends on your hosting and deployment setup. Document the actual recovery process for the project instead of relying on a generic rollback plan.
Step 6: Monitor the Areas Affected by the Upgrade
Focus monitoring on the parts of the system that changed. After launch, check application errors, publishing stability, search performance, API traffic, and system telemetry. Compare these against your pre-upgrade baseline so you can spot problems that were introduced during the upgrade.
Conclusion
An Episerver upgrade is easier to manage when you know what is changing before development begins. Start by reviewing your current CMS and framework, then check your packages, custom code, APIs, search, integrations, and frontend applications against the target Optimizely version.
From there, define the required work, test the changes in staging, and plan the production rollout and rollback before launch. A clear upgrade plan gives your team a better view of the work involved and helps avoid surprises once development starts.