Framework and platform breaking changes

This article covers framework and platform-level breaking changes in Commerce Connect 15, including runtime requirements, CMS platform dependency, serialization, and foundational API changes.

.NET 10 requirement

Commerce Connect 15 requires .NET 10.0. You must update your project target framework from net6.0 (or net8.0) to net10.0 in your .csproj file:

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>

Update your global.json to use the .NET 10 SDK:

{
  "sdk": {
    "version": "10.0.100"
  }
}

This also affects Docker base images and CI/CD pipeline configurations.

CMS 13 dependency

Commerce Connect 15 requires Optimizely CMS 13.0.0 or later. This is a major platform dependency change from Commerce 14, which depended on CMS 12.

CMS 13 introduces its own set of significant breaking changes that affect Commerce implementations. See CMS 13 breaking changes for the full list. The most impactful CMS 13 changes for Commerce developers include:

• .NET 10 requirement – CMS 13 also requires .NET 10, aligning with Commerce 15.
• SiteDefinition replaced by Application model – ISiteDefinitionResolver is replaced by IApplicationResolver in the EPiServer.Applications namespace. Commerce code that referenced SiteDefinition must migrate to the Application model.
• Newtonsoft.Json replaced with System.Text.Json – CMS 13 has migrated from Newtonsoft.Json to System.Text.Json throughout the framework.
• Service registration namespace change – Service registration methods moved from Microsoft.Extensions.DependencyInjection to EPiServer.DependencyInjection.
• IWebHostingEnvironment obsoleted – Use Microsoft.AspNetCore.Hosting.IWebHostEnvironment instead.
• IValidate registration change – Validators must be explicitly registered using AddCmsValidator<T>().
• Opti ID and Optimizely Graph – These are mandatory components in CMS 13.

Update your Commerce NuGet packages to the CMS 13-compatible versions:

<PackageReference Include="EPiServer.CMS.Core" Version="13.0.0" />
<PackageReference Include="EPiServer.CMS.UI" Version="13.0.0" />

Newtonsoft.Json replaced with System.Text.Json

Commerce 15 has migrated from Newtonsoft.Json to System.Text.Json throughout the codebase, aligning with the same change in CMS 13. If your project has code that depends on Newtonsoft.Json, you must either add an explicit package reference or migrate to System.Text.Json.

Custom JSON converters must be rewritten:

// Before (Commerce 14) - Newtonsoft.Json
using Newtonsoft.Json;

public class MyConverter : JsonConverter
{
    public override bool CanConvert(Type objectType) => objectType == typeof(MyType);

    public override object ReadJson(JsonReader reader, Type objectType,
        object existingValue, JsonSerializer serializer)
    {
        // ...
    }

    public override void WriteJson(JsonWriter writer, object value,
        JsonSerializer serializer)
    {
        // ...
    }
}

// After (Commerce 15) - System.Text.Json
using System.Text.Json;
using System.Text.Json.Serialization;

public class MyConverter : JsonConverter<MyType>
{
    public override MyType Read(ref Utf8JsonReader reader, Type typeToConvert,
        JsonSerializerOptions options)
    {
        // ...
    }

    public override void Write(Utf8JsonWriter writer, MyType value,
        JsonSerializerOptions options)
    {
        // ...
    }
}

The following Commerce-specific JSON converters have been removed or rewritten:

• MarketConverter – Rewritten for System.Text.Json.
• CustomerPricingConverter – Rewritten for System.Text.Json.
• ItemCollectionConverter – Rewritten for System.Text.Json.
• HashTableJsonConverter – Rewritten for System.Text.Json.
• MarketIdConverter – Rewritten for System.Text.Json.
• MoneyConverter – Rewritten for System.Text.Json.

BinaryFormatter removal

BinaryFormatter serialization has been removed due to security risks, aligning with .NET platform guidance. The following methods that used BinaryFormatter have been removed:

• Mediachase.BusinessFoundation.Data.Sql.SqlHelper.Serialize – Removed.
• Mediachase.BusinessFoundation.Data.Sql.SqlHelper.Deserialize – Removed.

Use modern serialization approaches such as System.Text.Json.JsonSerializer instead.

📘

Note

Some .NET built-in types are no longer binary serializable (see .NET binary serialization for the full list). NumberFormatInfo is one example. Since serializable commerce types like Money and Currency use NumberFormatInfo, those types become unserializable as well. This is a breaking change for code that relies on binary serialization of those types, which may result in SerializationException.

Membership provider removal

Membership provider support has been removed. Only ASP.NET Core Identity provider is supported in Commerce 15.

The following migration step classes have also been removed:

• MigrateAdminsRoleStep
• PopulateUserPermissionStep
• UpdateContactUserIdStep

⚠️

Important

If you are upgrading from a version earlier than Commerce 14, you must first upgrade to Commerce 14, run the migration steps, and then upgrade to Commerce 15.

Mediachase.Commerce.Catalog.Searchable attribute replacement

The Searchable attribute from EPiServer.DataAnnotations has been removed in CMS 13. Commerce 15 replaces all uses of this attribute with the current alternatives. If your code uses [Searchable] on catalog content properties, update to the replacement attribute provided by CMS 13.

EPiServer.Business.Commerce.CookieHelper removal

The obsolete static CookieHelper class has been removed. Migrate to using IHttpContextAccessor with ASP.NET Core's native cookie handling APIs:

// Before (Commerce 14)
CookieHelper.SetCookie("key", "value");
var value = CookieHelper.GetCookie("key");

// After (Commerce 15)
public class MyService
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public MyService(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public void SetCookie(string key, string value)
    {
        _httpContextAccessor.HttpContext?.Response.Cookies.Append(key, value);
    }

    public string GetCookie(string key)
    {
        return _httpContextAccessor.HttpContext?.Request.Cookies[key];
    }
}

For encrypted cookies, implement a custom encryption service using modern cryptographic APIs instead of the obsolete DES algorithm that CookieHelper used.

Data provider configuration

Mediachase.DataProvider – It is no longer possible to set up a custom data provider via configuration. The config section FrameworkProviders/dataService is ignored. Custom data providers must be registered through dependency injection.