Try our conversational search powered by Generative AI!

Quan Mai
Jun 5, 2018
(7 votes)

A breaking change regarding IShippingPlugin/IShippingGateway in Commerce 12

As you might already know, we reserve the major versions for breaking changes - when you upgrade to a major version, expect to have to change your code to make it compile and work.

Our latest major version is Commerce 12, which was released almost two months ago, and the full list of breaking changes can be seen here

However one breaking change is easier to miss than the other, that's why I think it should get more attention.

If you only fix your code to build, then when you run it, you will likely run into this exception

<Your super cool shipping gateway> does not implement IShippingPlugin nor IShippingGateway. 

Why is that and how to fix it?

In a Commerce implementation you might have multiple gateways, for example free shipping for customers who can wait and express shipping for ones who can't. For each and every shipment you would need to get the gateway assigned to it and use it to calculate the shipping rate. Previously, the instance of the shipping gateway is created by Activator, and it requires the implementation to have a constructor which takes an IMarket parameter. That is quite obsecure and hard to know before hand. Also if you are a seasoned Episerver developer, you might be like "Activator, seriously?". Well, those code are probably one of the oldest parts in our repository, so it's less "modern".

In Commerce 12 we changed the way to get the implementation of a shipping gateway (and a minor change to the signature of the interfaces themselves. Now you need to pass an IMarket to the method, not to create a constructor which takes one. In fact, you must remove that constructor because there is no default implementation registered for IMarket). And you might have guess it - via dependency injection. We now rely on the Inversion of control framework to give us an implementation of the shipping gateway being used. While that gives us much more flexibility, it also comes at a cost: because the shipping gateways are implementations of IShippingPlugin or IShippingGateway, or both, the IoC framework can't just detect it, unless you register specifically.

So the only extra work you need is to add this attribute to your implementation

    [ServiceConfiguration(ServiceType = typeof(IShippingPlugin))]


    [ServiceConfiguration(ServiceType = typeof(IShippingGateway))]

or both.

And that's it. Your shipping gateways are now ready!

Jun 05, 2018


Maris Krivtezs
Maris Krivtezs Jun 14, 2018 02:52 PM

Registering service with ServiceConfiguration is a bad practice. Episerver should not promote its usage.

I wrote a blog post about it:

Instead, register services in your DI container's registration point - configurable module, DI registry, pure DI composition root etc.

Quan Mai
Quan Mai Jun 14, 2018 03:03 PM

I don't really consider ServiceConfiguration is a bad practice. Yes having unexpected lifecycle is bad, but that is not a problem with ServiceConfiguration.

The upside of ServiceConfiguration is that you can quickly check what type your class is registered for, and with which lifecycle. IConfigurableModule is more useful (or even a must) for complicated registration like interceptor, or if you want to override a default implementation. 

Jun 25, 2018 02:52 PM

Personally I also do not like ServiceConfiguration, I like to have all of the configuration in an Initialization module and separated in to classes relating to the different areas of the project so I can see all of the DI across the project easily without having to go in to the concrete classes or search for usages of ServiceConfiguration. I also agree with the blog post of Māris's about not liking mixing the DI code inside the class code, it just feels dirty to me.

Also as far as being about to see what the type that class is registered easuky if a class is implementing an interface or class it will be in the inheritance defininition of the class file so that's usually pretty easy.

I guess it's preference but I thought I'd throw in my 2 cents

Sujit Senapati
Sujit Senapati Sep 29, 2018 04:44 PM


The solution to inject the type during DI registry also works just fine. I agree I do not prefer ServiceConfiguration either, but registering through structuremap just does the exact thing what is required.

public class ShippingImplementationBootstrapper : Registry
        public ShippingImplementationBootstrapper()

Feb 5, 2020 06:54 PM

If you have multiple Shipping Gateways you will need use IConfigurableModule. 



ServiceConfiguration didn't seem to be smart enough to handle that scenario, it simply registers the last instance it finds. Even if you start with one instance, it's not difficult to fall into this trap. I'd recommend going with IConfigurableModule from the start to save some head scratching when you enevitably do add aditonal instances.

Please login to comment.
Latest blogs
Developer meetups in Stockholm & Helsinki

It's time for developer meetups! Next month we will be in Stockholm and Helsinki. Join us for getting the latest updates from Optimizely, be inspir...

Magnus Kjellander | Feb 23, 2024

Roll Your Own Security Headers

Proper security headers are a must for your Optimizely driven website. There are a variety of tools out there that will help with this, but when...

Ethan Schofer | Feb 21, 2024

Migrate Catalog content properties

A colleague asked me yesterday – how do we migrate properties of catalog content. There is, unfortunately, no official way to do it. There are...

Quan Mai | Feb 20, 2024 | Syndicated blog

Adjust log levels in Optimizely DXP

You may adjust the log levels for your site in Optimizely DXP yourself, but only for the Integration environment. Follow this step-by-step guide.

Tomas Hensrud Gulla | Feb 20, 2024 | Syndicated blog