Hide menu Last updated: Aug 17 2017
Area: Episerver Commerce Applies to versions: 11

Breaking changes in Commerce 11

This topic describes breaking changes for Episerver Commerce in relation to the previous major version (10), and the steps needed to update affected code. To view the complete list of changes, see release notes.

Some changes are binary breaking but do not necessarily require code changes but rather just a recompilation of the project. Breaking changes are changes in method signatures or behavior compared to the previous version's documented API. These APIs are described below.

Removal of old Asset Management system

The old Asset Management system in Commerce Manager was removed.

Classes removed:


Properties and methods removed:

Class Mediachase.Commerce.Assets.Import.ImportBase:

public System.Void .ctor (System.String p1, System.String p2);
public Mediachase.Commerce.Assets.FolderEntity get_AssetFolder ();
public Mediachase.Commerce.Assets.FolderElementEntity GetOrCreateElementEntity (Mediachase.Commerce.Assets.FolderEntity p1, System.String p2, System.String p3);
public Mediachase.Commerce.Assets.FolderEntity GetOrCreateFolderEntity (Mediachase.Commerce.Assets.FolderEntity p1, System.String p2);

Class Mediachase.Commerce.Permissions:

public Mediachase.Commerce.Assets.AssetsPermissions get_Assets ();


Class Mediachase.Commerce.FrameworkContext:

public Mediachase.Commerce.Assets.AssetContext get_AssetSystem ()


Class EPiServer.Business.Commerce.CommerceManagerSettings:

public static System.Boolean get_UseLegacyAssetSystem ()

Catalog import handling of cleared fields consistent with API

When clearing a meta field that is not multi-language, it is now required to have an empty element for the value to be included for the catalog's default language. In the previous version, you could use any language to clear the value, which was an exception to how non-null fields are handled. Field values for other languages are not used, since data for non-multilanguage fields is always loaded from the default language.

Improved home category handling for entries

In previous versions, a catalog entry's home category, used for the content's ParentLink and when rendering default hierarchical URLs, was determined by the relation with the lowest SortOrder. This version introduces a separate field for marking one relation as the primary relation, used as home category. The following changes support this change:

  • The upgrade mimics the old behavior of selecting the relation with the lowest sort order for each entry, and marks it as primary.
  • The Catalog import XML format now supports an "IsPrimary" element in Node-Entry relations. The import works in a backwards compatible way as follows:
    • If the XML defines a primary relation, it is set as the primary relation.
    • If the XML does not define a primary relation, and a primary relation for the entry exists in the database, it is not changed.
    • If the XML does not define a primary relation, and there is no primary relation for the entry in the database, the import selects the relation with the lowest sort order, and marks it as primary.
  • When importing via the Catalog CSV import, you can define multiple categories for an item. The first category in the list is set as the home category.
  • The Catalog UI's Edit Categories view no longer supports reordering the Relations and does not update the sort order of the Relations.
  • The view also shows the primary category under a separate heading.
  • Entries with no primary relation are considered to be direct children of the catalog, even if they have other relations.
  • Relation objects have two new properties: Parent and Child, added to make the relation easier to understand, instead of Target and Source. Target and Source still exist, but the recommendation is to use Parent and Child.

Home category in Service API

The Service API model for node-entry relations also supports an IsPrimary property. If the property is omitted, a POST request results in a relation with IsPrimary set to false, and a PUT request results in no modification of the relations IsPrimary state.

Improved API for relations and associations

  • In IRelationRepository, the GetChildren and GetParents methods supercede GetRelationsBySource and GetRelationsByTarget. On the relation objects, the properties Parent and Child serve the same purpose.
  • Both IRelationRepository and IAssociationRepository have improved cache. Relation and Association therefore implement IReadOnly, which requires a call to CreateWriteableClone to get a writeable copy for updating values.
  • The ILinksRepository interface has been obsoleted; use IRelationRepository and IAssociationRepository instead.
  • The ILink interface has been obsoleted and is no longer used. It served very little purpose, and its Source/Target properties for Relations are superceded by Parent/Child.

Improved API for payments in the order system

The ProcessPayment method in the IPaymentProcessor and IPaymentPlugin interfaces returns more information for supporting redirect payments (such as PayPal, DIBS and DataCash). The returned information is wrapped in an object of type PaymentProcessingResult, which contains a flag indicating whether the payment processing is successful, and displays a message during processing, and a redirect URL.