Skip to main content
Optimizely Academy

End-user eLearning

Upcoming events

Certification

Partner training

Community

All Topics

Managing Add-ons

  • By Optimizely Education
  • Published: Mar 3, 2026
  • Rating
    Average rating: 0 No reviews

Outline
At a glance:
  • Compatibility shift: CMS 12 + Commerce 14 run on .NET 6 + ASP.NET Core; most CMS 11 add-ons need refactoring.
  • Installation changes: Add-ons installed via NuGet; service registration moved to Program.cs with ASP.NET Core middleware.
  • Upgrades: Third-party add-ons may have new versions; custom add-ons likely require full migration.
  • Best practices: Minimize customizations, keep dependencies up-to-date, and maintain clear documentation.

This module addresses the critical aspects of managing add-ons within Optimizely CMS 12 and Commerce 14 solutions. The transition to ASP.NET Core significantly impacts add-on compatibility and the installation/upgrade processes. Development teams must understand how to identify compatible add-ons, correctly install and configure them in the new environment, and navigate the complexities of upgrading existing add-ons or custom solutions.

1. Add-on compatibility in an ASP.NET Core environment

The shift to ASP.NET Core means add-ons developed for CMS 11 (ASP.NET Framework) are generally not directly compatible with CMS 12 and Commerce 14. Add-on vendors must often recompile and refactor their add-ons to target .NET 6+ and use ASP.NET Core APIs.

The impact of ASP.NET Core on add-ons ▼
  • Framework mismatch: Add-ons built against System.Web and .NET Framework cannot run directly.
  • API changes: Internal Optimizely APIs have changed; use Microsoft.Extensions.DependencyInjection for services, IApplicationBuilder for middleware, and modern APIs.
  • Project structure: UI components and configuration must adapt to the new ASP.NET Core project layout.
Identifying compatible add-ons ▼
  • Optimizely Marketplace: The primary source for compatible add-ons; vendors specify supported Optimizely and .NET versions.
  • Vendor documentation: Always review installation instructions, compatibility notes, and migration guides before proceeding.
  • NuGet packages: Look for packages targeting .NET 6+ and referencing EPiServer.CMS.AspNetCore. or EPiServer.Commerce.AspNetCore. namespaces.

2. Installation process for ASP.NET Core add-ons

Installing add-ons in CMS 12/Commerce 14 largely follows standard ASP.NET Core practices via NuGet and startup configuration.

NuGet package installation

Add-ons are installed via the .NET CLI or the Visual Studio NuGet Package Manager UI.

Bash
dotnet add package EPiServer.Commerce.Payment.Stripe --version 14.x.x

Service registration and configuration

Add-ons typically require service registration and middleware configuration in Program.cs. The example below shows how an add-on registers its services and middleware in the ASP.NET Core startup pipeline.

C#
// In Program.cs (minimal hosting model) var builder = WebApplication.CreateBuilder(args); builder.Services.AddCms() .AddCommerce() .AddSomethingCoolAddon(options => { options.ApiKey = builder.Configuration["SomethingCoolAddon:ApiKey"]; options.EnableFeatureX = true; }); // ... other service registrations var app = builder.Build(); // ... other middleware app.UseSomethingCoolAddon(); // Add-on specific middleware app.UseEndpoints(endpoints => { endpoints.MapContent(); endpoints.MapControllerRoute( name: "default", pattern: "{controller=Home}/{action=Index}/{id?}"); endpoints.MapRazorPages(); }); app.Run();

Database updates: Some add-ons require schema updates, usually handled automatically on startup or via dotnet ef migrations for EF Core-based add-ons.

3. Upgrading existing add-ons

Upgrading add-ons from CMS 11/Commerce 13 to CMS 12/Commerce 14 can be more complex than fresh installs, especially for custom or heavily modified add-ons.

Third-party add-ons ▼
  • Check for CMS 12/Commerce 14 versions: Confirm the vendor has published compatible releases before starting.
  • Migration guides: Follow vendor-specific migration instructions carefully.
  • Replace NuGet packages: Uninstall the old ASP.NET Framework version and install the new ASP.NET Core version.
  • Update configuration: Move settings from web.config to appsettings.json and update service registration in Program.cs.
Custom or heavily modified add-ons ▼

Custom add-ons usually require a full migration - treat them as new development rather than a simple package update.

  • Project conversion: Convert the project file to SDK-style format.
  • Target framework: Update to .NET 6+ (e.g., net8.0).
  • API refactoring: Use ASP.NET Core APIs, refactor IInitializableModule code, service registration, and UI components.
  • Dependency updates: Update all NuGet dependencies to ASP.NET Core-compatible versions.
  • Testing: Test thoroughly both in isolation and integrated into the full Optimizely solution.

4. Best practices for add-on management

  • Minimize customizations: Encapsulate changes or use extension points rather than altering third-party code directly.
  • Regular updates: Keep add-ons updated to the latest compatible versions to benefit from fixes and improvements.
  • Dependency management: Use automated tools like Dependabot or Renovate to track NuGet package updates.
  • Documentation: Maintain clear records of installed add-ons, versions, configurations, and any modifications made.

Conclusion

Managing add-ons in CMS 12 and Commerce 14 requires a clear understanding of ASP.NET Core compatibility and updated installation and upgrade procedures. Third-party add-ons may be relatively straightforward to update, but custom solutions often need significant refactoring. Following best practices ensures add-ons remain maintainable, functional, and beneficial within Optimizely DXP solutions.