---
title: Framework and platform breaking changes
slug: commerce-connect-15/docs/framework-and-platform-breaking-changes-commerce-15
docTags: 
createdAt: 2026-07-30T20:34:44.000Z
---

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:

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

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

```json
{
  "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](docId\:byC7COq00R-mLmWVV9_eE) 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:

```xml
<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:

```csharp
// 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.

:::hint{type="info"}
**Note**
Some .NET built-in types are no longer binary serializable (see [.NET binary serialization](https://docs.microsoft.com/en-us/dotnet/standard/serialization/binary-serialization#net-core) 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`

:::hint{type="info"}
**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:

```csharp
// 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.