Upgrading payment method settings

This is a continuation of the upgrade implementation tutorial.

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

We will start with the same extension add-on we've created in the configuration upgrades tutorial. This is a very basic implementation of payment extension add-on, which has the TutorialExtension class implementing the PaymentExtension abstract class. Let's assume we already have a payment method settings model class implemented too, and the name of the model class will be TutorialPaymentMethodSettings and according to the payment method settings tutorial we must pass this class as a generic type parameter to generic PaymentExtension<> base class:

[PaymentModuleId("UpgradesTutorial")]
public class TutorialExtension : PaymentExtension<TutorialPaymentMethodSettings>, IConfigurable<TutorialConfiguration>
{
    public TutorialConfiguration Configuration { get; set; }

    public override void FinalizePayment(PaymentContext context)
    {
    }

    public override NextAction ProcessCallback(PaymentContext context)
        => NextAction.None;

    public override NextAction StartPayment(PaymentStartContext context)
        => NextAction.None;
}

And here is a source code of our TutorialPaymentMethodSettings class:

public class TutorialPaymentMethodSettings : PaymentMethodSettings
{
    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 payment method settings. This is how it would look like in Sana Admin (Setup > Ordering > Payment > create new payment method and set 'UpgradesTutorial' as payment provider:

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 TutorialPaymentMethodSettings 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 TutorialPaymentMethodSettings 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 TutorialPaymentMethodSettings class and now it looks like this:

public class TutorialPaymentMethodSettings : PaymentMethodSettings
{
    public string SomeConfigValue { get; set; }

    public int AnotherConfigValue { get; set; }
}

Create new class to keep the 'new' model

Create a new TutorialPaymentMethodSettings 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 TutorialPaymentMethodUpgrade 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 PaymentMethodSettingsUpgrade<TOldModel, TNewModel>

Now inherit your newly added class from Sana.Extensions.Upgrades.PaymentMethodSettingsUpgrade<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.TutorialPaymentMethodSettings, which makes it easy to read.

Implement abstract members

Because the base PaymentMethodSettingsUpgrade<,> 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 PaymentModuleId property

This property helps Sana Commerce Cloud map the payment 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 PaymentModuleId attribute which you specified on the TutorialExtension add-on's class. So here is the TutorialExtension class once again:

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

Implement UpgradePaymentMethodSettings method

This is the actual upgrade implementation. Implement what you need to upgrade in your payment 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 UpgradePaymentMethodSettings(v1_0_0.TutorialPaymentMethodSettings oldModel, TutorialPaymentMethodSettings 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 TutorialPaymentMethodUpgrade 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 payment method settings in Sana Admin (Setup > Ordering > Payment > edit your payment 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 payment method settings is complete.

Back to general implementation tutorial