Upgrading shipping method settings

This is a continuation of the upgrade implementation tutorial.

So let's say you have a shipping add-on implemented. And now you need to provide upgrades for shipping method settings data. Follow the steps below to get to know how it is done.

We'll have to start with a fresh example of a shipping extension add-on. This is a very basic implementation of shipping extension, which has the TutorialShippingExtension class implementing the ShippingExtension abstract class. Let's assume we already have a shipping method settings model class implemented too, and the name of the model class will be TutorialShippingMethodSettings and according to the shipping method settings tutorial we must pass this class as a generic type parameter to generic ShippingExtension<> base class:

[ShippingModuleId("UpgradesTutorial")]
public class TutorialShippingExtension : ShippingExtension<TutorialShippingMethodSettings>
{
    public override bool WeightRequired => false;

    public override bool BasketTotalsRequired => false;

    public override IList<ShippingRate> CalculateShippingRates(ShippingContext shippingContext)
        => new ShippingRate[0];
}

And here is a source code of our TutorialShippingMethodSettings class:

public class TutorialShippingMethodSettings : ShippingMethodSettings
{
    public string SomeConfigValue { get; set; }
}

As you can see we keep it simple for this tutorial and we'll have only one SomeConfigValue property in the shipping method settings. This is how it would look like in Sana Admin (Setup > Ordering > Shipping > create new shipping method and set 'Upgrades tutorial' as calculation method:

So if you've already followed that tutorial, you should be already familiar with the concept of 'old model snapshot + new model snapshot + upgrade class'.

Step 1: Snapshot of the 'old' model

First we need to create a snapshot for our 'old' model.

Find previous version of the model

Take the TutorialShippingMethodSettings class as it was when the 1.0.0 version was released. Go through the history in Git (or SVN, or whatever version control system you're using) and find this class when it was in 1.0.0 version. In our example the model will be the same as we have already shown above.

Create new class to keep your 'old' model

Create a new class with the same TutorialShippingMethodSettings name in 'Upgrades/v1.0.0' folder:

Fix namespaces

Don't forget to change messy v1._0._0 namespace name generated by the Visual Studio to more readable v1_0_0:

Copy properties

Copy properties from your 'old' model class to this newly created class:

Important

Do not copy base class inheritance from the original model. Only properties are needed.

Step 2: Snapshot of the 'new' model

Let's assume that in the new 1.0.1 version we added new AnotherConfigValue property to the TutorialShippingMethodSettings class and now it looks like this:

public class TutorialShippingMethodSettings : ShippingMethodSettings
{
    public string SomeConfigValue { get; set; }

    public int AnotherConfigValue { get; set; }
}

Create new class to keep the 'new' model

Create a new TutorialShippingMethodSettings class, this time in 'Upgrades/v1.0.1' folder:

Fix namespaces

Don't forget to fix messy namespace: change it from v1._0._1 to v1_0_1 (already shown in the screenshot above).

Copy properties

Again, the same as we did for 'old' model, simply copy properties from your current model class to this newly created 'new' model class:

The same rules apply here: do not copy base class inheritance from the original model. Only properties are needed.

Step 3: Implement upgrade class

Now that you have two model snapshots: 'old' and 'new' model classes, you can start implementing the actual upgrade class.

Create upgrade class in 'new' version folder

Create a new class in your 'new' version's folder, which in our example is 'Upgrades/v1.0.1' folder:

We named this class TutorialShippingMethodUpgrade as you can see.

Fix namespaces

Once again, do not forget to fix namespace by changing it from messy v1._0._1 to nice v1_0_1.

Inherit from ShippingMethodSettingsUpgrade<TOldModel, TNewModel>

Now inherit your newly added class from Sana.Extensions.Upgrades.ShippingMethodSettingsUpgrade<TOldModel, TNewModel> generic abstract class. Here, you'll have to specify your 'old' model for TOldModel type parameter and your 'new' model for TNewModel type parameter, respectively:

Notice that because our 'old' and 'new' model classes have the same class name, we have to prevent 'ambiguous name' conflict by explicitly specifying the 'old' class's namespace v1_0_0.TutorialShippingMethodSettings, which makes it easy to read.

Implement abstract members

Because the base ShippingMethodSettingsUpgrade<,> class is abstract, you now need to implement it's abstract members.

Implement UpgradeTo property

This is a property which tells Sana Commerce Cloud to which version this upgrade class upgrades the data to. So in our case we're creating upgrade to version 1.0.1, so our UpgradeTo should indicate exactly that:

Implement ShippingModuleId property

This property helps Sana Commerce Cloud map the shipping method data entity, when it is loaded from the database, to this upgrade class. The value of this property must be exactly the same as the value of ShippingModuleId attribute which you specified on the TutorialShippingExtension add-on's class. So here is the TutorialShippingExtension class once again:

We must use the value of ShippingModuleId attribute as the value of the ShippingModuleId property in the upgrade class:

Implement UpgradeShippingMethodSettings method

This is the actual upgrade implementation. Implement what you need to upgrade in your shipping method model from previous version to current (from 1.0.0 to 1.0.1). Change only those values that you really need to change. Sana Commerce Cloud will do the rest: it will keep all unchanged properties.

You can read more about what exactly you can do in the upgrade with your model with examples in a separate article.

In our example we will simply append some dummy text to our SomeConfigValue property and for newly added AnotherConfigValue we will pre-set some default dummy value:

public override void UpgradeShippingMethodSettings(v1_0_0.TutorialShippingMethodSettings oldModel, TutorialShippingMethodSettings newModel)
{
    // Appending some dummy text to the existing value.
    newModel.SomeConfigValue = oldModel.SomeConfigValue + " - the value has been upgraded to 1.0.1";

    // Pre-set some dummy default value to the new prop added in the 'new' model.
    newModel.AnotherConfigValue = 42;
}

This is how our complete TutorialShippingMethodUpgrade class looks like in the end:

Step 4: Test it

When your upgrade has been implemented, you can build your extension add-on and update it in Sana Admin (Apps > Add-ons > click Update on your add-on). After the newest version has been installed, proceed to the shipping method settings in Sana Admin (Setup > Ordering > Shipping > edit your shipping method):

Before the upgrade, version 1.0.0:

After the upgrade, version 1.0.1:

Next version

When you implement the next version of your extension, in our example it will be version 1.0.2, you can use your model's snapshot class from the 1.0.1 version folder as your 'old' model. So you simply add a new 'Upgrades/v1.0.2' folder and continue from Step 2: Snapshot of the 'new' model:

Conclusion

That's it, the upgrade of extension add-on's shipping method settings is complete.

Back to general implementation tutorial