Last updated: Mar 01 2018

Area: Episerver Commerce Applies to versions: 12

Breaking changes in Commerce 12

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

While some changes are binary breaking, they do not necessarily require code changes - a project recompilation may be adequate. Breaking changes are changes in method signatures or behavior compared to the previous version's documented API. These APIs are described below.

Changes to order entities

IMarket.PricesIncludeTax: new setting on a market, indicating if the price of its items includes tax.
ILineItem.TaxCategoryId: the line item's tax category, rarely changed during order processing, is now stored in an ILineItem. So, Commerce does not need to retrieve it from the DB/cache system whenever an order is calculated. Another benefit is that, even if a product in a line item is removed or no longer taxed after an order is made, if the order needs to be recalculated, that line item's price should not change.
The pre-release API IPaymentOption was obsoleted and replaced by IPaymentMethod. This change clarifies the name.
IShippingGateway and IShippingPlugin: The GetRate() method now takes IMarket as a parameter. A parameterless constructor is no longer required.
However, the custom implementations of IShippingGateway and IShippingPlugin must be registered for those interfaces (via the ServiceConfiguration attribute or at initialization by using the IConfigurableModule).
See also: A breaking change regarding IShippingPlugin/IShippingGateway in Commerce 12.
IOrderGroup: The market property was obsoleted. In its place, Commerce 12 introduces three new properties: MarketId, MarketName and PricesIncludeTax. As a result, a saved purchase order should be complete without needing to refer to other tables/entities.
Also, each order has a setting indicating its prices, including/excluding tax. An order can allow changes to the tax setting on a market without causing future re-calculation issues. When creating a new order, this setting is retrieved from the market's PricesIncludeTax setting.
IOrderForm: introduces a new property, PricesIncludeTax, which gets the Includingtaxinprices setting from its parent, IOrderGroup.

Changes to workflow activities

All calculations in activities are now carried out by calculators. This change ensures that order calculations are consistent between workflow and non-workflow systems (using calculators).

Changes to calculators

For more information, see Calculating orders: introduction.

ITaxCalculator: All existing methods were obsoleted. Commerce 12 adds two new methods, GetSalesTax() and GetShippingTax() for an ILineItem. As a result, the tax calculator only calculates tax values at the lowest level, that is, line item. Tax calculations for shipment, order form, and order group are moved to the corresponding calculator.
ILineItemCalculator: Introduces new APIs: GetLineItemPrices() and GetSalesTax().
IShippingCalculator
- Obsoletes GetShippingCost() methods for IOrderGroup and IOrderForm. It means the shipping cost is only at the shipment level.
- GetShipmentDiscountPrice() is now an extension method of IShipment and was obsoleted in this calculator.
- Introduces five new methods for getting shipping totals (for the order form and the return form), shipping tax, and sales tax for a shipment in an order form or a return order form.
IOrderFormCalculator
- GetOrderDiscountTotal() for an IOrderForm was no longer used and is obsoleted.
- Introduces three new methods for getting an IOrderForm's shipping subtotal, order form totals, and tax total.
IOrderGroupCalculator
- GetOrderDiscountTotal() method needs only IOrderGroup as parameter. The overload with Currency parameter was obsoleted because Currency is included in IOrderGroup.
- Introduces three new methods for getting an IOrderGroup's shipping subtotal, order group totals, and tax total.
IOrderGroupTotalsCalculator was no longer used and is obsoleted. To get order group totals, use IOrderGroupCalculator instead.

Other changes

ILineItemValidator: The Validate() method that accepts IMarket as parameter is obsoleted and replaced by the new one, which accepts MarketId as parameter.
IPlacedPriceProcessor: All methods of this interface are obsoleted and replaced by the corresponding one, which accepts MarketId as parameter instead of IMarket.
IReturnOrderService: Introduces a new method, InvalidatePromotions, to determine the invalidated promotions of a return form. This method updates IReturnOrderForm.Promotions by invalidated promotions. It also updates the discount amount of all return line items in the form.
Money: Changed explicit operator decimal(Money) to implicit operator decimal(Money).

Changes to pre-release APIs

IReturnLineItemCalculator: added a new API for getting sales tax and LineItemPrices object for an IReturnLineItem.
IReturnOrderFormCalculator: added three new APIs for getting an IReturnOrderForm's return order form totals and tax total.
IReturnPurchaseOrderCalculator: This interface was no longer used and obsoleted. To get totals of a return order form, use IReturnOrderFormCalculator instead.

Also, some extension methods were obsoleted because they were no longer being used or have replacements. They include:

EPiServer.Commerce.Order.IOrderFormExtensions: All overloads of the GetOrderDiscountTotal() method were obsoleted and have no replacements.
EPiServer.Commerce.Order.IShipmentExtensions: The overload of the GetShipmentDiscountPrice() method with IShippingCalcualtor parameter was obsoleted. Use the one without IShippingCalculator instead.
EPiServer.Commerce.Order.IOrderGroupExtensions: All overloads of the GetOrderDiscountTotal() method which use Currency as parameter were obsoleted. Use the overloads without Currency instead.
EPiServer.Commerce.Order.OrderGroupExtensions: All overloads of the Save() method which don't use IOrderGroupCalculator were obsoleted. Use the overloads with IOrderGroupCalculator instead.

Reduced remote event replication

Events raised when changes to Catalog DTOs are about to be saved, for example CatalogEntryUpdating, are no longer replicated on the remote event channel. Events raised when a change transaction is completed, for example CatalogEntryUpdated, are still replicated.

The Updating events are no longer replicated because they provide no additional value. A remote party cannot intervene and manipulate the data before it is saved, and the transaction may have completed and raised its Updated event before the remote party has processed the Updating event. So, the Updated event is sufficient for the remote party, and the Updating event only adds noise and unnecessary network/service bus traffic.

Related to this, the following remote event keys were removed from Mediachase.Commerce.Catalog.Events.CatalogEventBroadcaster:

AssociationUpdatingEventType
CatalogEntryUpdatingEventType
CatalogNodeUpdatingEventType
CatalogUpdatingEventType
RelationUpdatingEventType

Removed obsoleted APIs

Several APIs that were marked as obsolete with a removal date in the obsolete messages of February 2018 or earlier were removed. These include:

Types

EPiServer.Commerce.Catalog.Linking.ILink interface

EPiServer.Commerce.Catalog.Linking.ILinksRepository interface

EPiServer.Commerce.Catalog.Linking.LinksRepository class

EPiServer.Commerce.Catalog.CatalogLanguageSettingsHandler class

EPiServer.Commerce.Order.IOrderFactory

EPiServer.Commerce.Order.DefaultOrderFactory

EPiServer.Commerce.Catalog.Provider.Construction.CatalogContentFactory class

EPiServer.Commerce.Routing.RequestCacheUrlResolver class

Mediachase.Commerce.Catalog.Dto.CatalogDataTable class

Members

EPiServer.Commerce.Catalog.Provider.Construction.CatalogPropertyLoader.LoadMetaDataContentProperties method

EPiServer.Commerce.Catalog.ContentTypes.AssociatingExtensions.GetAssociations(this IAssociating associating, ILinksRepository linkRepository) extension method

EPiServer.Commerce.Catalog.ContentTypes.CategorizableExtensions.GetNodeRelations(this ICategorizable categorizable, ILinksRepository linksRepository) extension method

EPiServer.Commerce.Catalog.ContentTypes.VariantContainerExtensions.GetVariantRelations(this IVariantContainer variantContainer, ILinksRepository linksRepository) extension method

EPiServer.Commerce.Catalog.Provider.CatalogContentVersionStore:

List(ContentReference contentLink) method overload
List(ContentReference contentLink, string languageBranch) method overload
ListDelayedPublish method
ListPublished method

EPiServer.Commerce.Marketing.ShipmentPriceMatrix.GetShipmentCost method

EPiServer.Commerce.Order.Calculator.DefaultShippingCalculator:

CalculateShipmentCost(IOrderGroup orderGroup, IMarket market, Currency currency) method overload
CalculateShipmentCost(IShipment shipment, IMarket market, Currency currency) method overload
ValidateShipmentCostForOrder method
ValidateShipmentCostForOrderForm method

Mediachase.Commerce.Catalog.CSVImport.EntryMappingMetaClass.AddSystemFieldsMapping method

EPiServer.Commerce.Order.IOrderGroupExtensions

AddLineItem(this IOrderGroup orderGroup, ILineItem lineItem, IOrderFactory orderFactory) extension method overload.
AddLineItem(this IOrderGroup orderGroup, IOrderForm orderForm, ILineItem lineItem, IOrderFactory orderFactory) extension method overload.
AddPayment(this IOrderGroup orderGroup, IPayment payment, IOrderFactory orderFactory) extension method overload.
AddPayment(this IOrderGroup orderGroup, IOrderForm orderForm, IPayment payment, IOrderFactory orderFactory) extension method overload.
AddShipment(this IOrderGroup orderGroup, IShipment shipment, IOrderFactory orderFactory) extension method overload.

Mediachase.Commerce.Catalog.CatalogIdentityResolver.GetIdsFromDatabase method

Mediachase.Commerce.Catalog.ReferenceConverter.GetContentLink(int contentId, int versionId) method overload

Mediachase.Commerce.Website.Helpers.CartHelper.AddItemToFirstShipment method

Mediachase.Commerce.Workflow.Activities.OrderGroupActivityBase:

GetResultingPaymentsByTransactionType method
GetPaymentTransactionType method
GetAllRelatedPayments method

Mediachase.MetaDataPlus.Configurator.MetaField.OwnerMetaClass property

Mediachase.MetaDataPlus.Import.MappingMetaClass.AddSystemFieldsMapping method