Upgrading extension configuration

This is a continuation of the upgrade implementation tutorial.

Let's say, we have a configuration class implemented in our extension and we want to modify some configuration values when the add-on will be upgraded from 1.0.0 to 1.0.1 version.

Step 1: Snapshot of the 'old' model

First we need to have an 'old' model class for extension configuration. Here's our extension class:

The configuration model is the class which we pass as type parameter when implementing IConfigurable<T> interface, which in our example is TutorialConfiguration.

Find previous version of the model

In order to have the 'old' version of that class you need to take the 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.

Let's assume our 'old' TutorialConfiguration class looked like this when we released 1.0.0:

[ConfigurationKey("TutorialConfig")]
public class TutorialConfiguration : ExtensionConfiguration
{
    public string SomeConfigurationValue { get; set; }
}

Very simple class, with only one property there, called SomeConfigurationValue.

Create new class to keep your 'old' model

Let's create a new class with the same TutorialConfiguration name in 'Upgrades/v1.0.0' folder:

Fix namespaces

Notice the messed up dots and underscores which were generated by the Visual Studio in the namespace: v1._0._0. Please correct it to something more readable, remove dots and leave only underscores for example v1_0_0:

Copy properties

Now simply copy properties from your 'old' model class to this newly created class:

Important

Make sure you did not copy base class inheritance from the original model. In our example, the original TutorialConfiguration class inherits ExtensionConfiguration base class:

public class TutorialConfiguration : ExtensionConfiguration

So make sure you do not copy this inheritance by accident. In the newly created 'old' model class it should look like this:

public class TutorialConfiguration

Step 2: Snapshot of the 'new' model

Now that we already have our 'old' model created and kept in 'v1.0.0' folder, it is time to do the same but with the current model, which is our 'new' model to which the 'old' model will be upgrading.

So let's assume our current TutorialConfiguration class looks like this in current version (that is version 1.0.1):

[ConfigurationKey("TutorialConfig")]
public class TutorialConfiguration : ExtensionConfiguration
{
    public string SomeConfigurationValue { get; set; }

    public int AnotherConfigurationValue { get; set; }
}

For simplicity we won't do any big changes to the 'old' one, so let's say in our example we only added another property to our model in version 1.0.1: AnotherConfigurationValue.

Create new class to keep the 'new' model

Just the same way we did with the 'old' model - create a new TutorialConfiguration class but now 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 TutorialConfigurationUpgrade 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 ConfigurationUpgrade<TOldModel, TNewModel>

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

Implement abstract members

Because the base ConfigurationUpgrade<,> 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 ConfigurationKey property

This property helps Sana Commerce Cloud map the configuration data entity, when it is loaded from the database, to this configuration upgrade class. The value of this property must be exactly the same as the value of ConfigurationKey attribute which you specified on original TutorialConfiguration class. So here is the original class:

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

Implement UpgradeConfiguration method

This is the actual upgrade implementation. Implement what you need to upgrade in your configuration 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 SomeConfigurationValue property and for newly added AnotherConfigurationValue we will pre-set some default dummy value:

public override void UpgradeConfiguration(v1_0_0.TutorialConfiguration oldModel, TutorialConfiguration newModel)
{
    // Appending some dummy text to the existing value.
    newModel.SomeConfigurationValue = oldModel.SomeConfigurationValue + " - 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.AnotherConfigurationValue = 42;
}

This is how our complete TutorialConfigurationUpgrade 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 add-on's settings page (click 'Configure' button). You should see that the values have been upgraded correctly.

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 configuration is complete.

Back to general implementation tutorial