Installing and upgrading add-ons

---

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. This section provides technical guidance and best practices for effective add-on management.

---

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.

1. The Impact of ASP.NET Core

• 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: Adapt UI components and configuration to the new ASP.NET Core project layout.

2. Identifying Compatible Add-ons

• Optimizely Marketplace: Primary source for compatible add-ons; vendors specify supported Optimizely and .NET versions.
• Vendor Documentation: Always review installation instructions, compatibility notes, and migration guides.
• NuGet Packages: Look for packages targeting .NET 6+ and referencing EPiServer.CMS.AspNetCore. or EPiServer.Commerce.AspNetCore..

---

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.

1. NuGet Package Installation

• Command Line:
  Copy

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

• Visual Studio: Use NuGet Package Manager UI or Console to install the package.

2. Service Registration and Configuration

Add-ons usually require service registration and configuration in Program.cs.

• Program.cs Integration:
  Copy

  // 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();

  This shows how add-ons integrate into the ASP.NET Core startup, registering services and middleware.

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

---

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.

1. Third-Party Add-ons

• Check for CMS 12/Commerce 14 Versions: Confirm vendor has compatible releases.
• Migration Guides: Follow vendor-specific migration instructions.
• Replace NuGet Packages: Uninstall old ASP.NET Framework version, install the new ASP.NET Core version.
• Update Configuration: Move settings from web.config to appsettings.json and update service registration in Program.cs.

2. Custom or Heavily Modified Add-ons

• Treat as New Development: Custom add-ons usually need full migration:
  • Project Conversion: Convert project file to SDK-style.
  • 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 NuGet dependencies to ASP.NET Core-compatible versions.



• 
  Testing: Test thoroughly in isolation and integrated into the Optimizely solution.

---

Best Practices for Add-on Management

• Minimize Customizations: Encapsulate changes or use extension points rather than altering third-party code.
• Regular Updates: Keep add-ons updated to latest compatible versions.
• Dependency Management: Use tools like Dependabot or Renovate for NuGet packages.
• Documentation: Maintain clear records of installed add-ons, versions, configurations, and modifications.

---

Conclusion

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