Upgrading content block

This is a continuation of the upgrade implementation tutorial.

If you have a content block add-on implemented and you need to provide upgrades for the content block data, you can follow the steps below to get to know how it is done.

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

[ContentBlockId("TutorialExtension")]
public class TutorialContentBlockExtension : ContentBlockExtension<TutorialContentBlockModel>
{
}

And here is a source code of our TutorialContentBlockModel class:

public class TutorialContentBlockModel : ContentBlockModel
{
    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 content block model. This is how it would look like in Sana Admin:

So how do we actually implement upgrades where we can modify this model's data between add-on's versions? Please find below.

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

public class TutorialContentBlockModel : ContentBlockModel
{
    public string SomeConfigValue { get; set; }

    public int AnotherConfigValue { get; set; }
}

Create new class to keep the 'new' model

Create a new TutorialContentBlockModel 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 TutorialContentBlockUpgrade 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 ContentBlockUpgrade<TOldModel, TNewModel>

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

Implement abstract members

Because the base ContentBlockUpgrade<,> 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 ContentBlockId property

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

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

Implement UpgradeContentBlock method

This is the actual upgrade implementation. Implement what you need to upgrade in your content block 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 UpgradeContentBlock(v1_0_0.TutorialContentBlockModel oldModel, TutorialContentBlockModel 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 TutorialContentBlockUpgrade 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 content block in Sana Admin:

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 content block extension add-on is complete.

< Back to general implementation tutorial