Upgrading content block to configuration

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 to move settings into configuration, 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")]
[AdjustableBlock(SupportsFullWidth = true)]
public class TutorialContentBlockExtension : ContentBlockExtension<TutorialContentBlockModel>
{
}

And here is a source code of our TutorialContentBlockModel class:

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

As you can see we keep it simple for this tutorial and we'll have only one SecretKey property in the content block model. This is how it would look like in Sana Admin:

Step 1: Snapshot of the 'old' content block 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' content block model

Let's assume that in the new 1.0.1 version we removed new SecretKey property to the TutorialContentBlockModel class and now it looks like this:

public class TutorialContentBlockModel
{
}

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. Also as we migrate SecretKey prop to configuration we will get rid of it in our snapshot:

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

Step 3: Snapshot of the 'new' configuration model

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

public class TutorialConfiguration
{
    [SecureString]
    public string SecretKey { get; set; }
}

Create new class to keep your 'new' model

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

Fix namespaces

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

Copy and add new properties

Now simply copy properties from your 'old' model class to this newly created class and add new SecretKey:

Step 5: Implement upgrade class

Now that you have configuration model class, 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.ContentBlockToConfigurationUpgrade<TContentBlockModel, TConfigurationModel> generic abstract class. Here, you'll have to specify your model TContentBlockModel type parameter and your configuration model TConfigurationModel type parameter, respectively:

Implement abstract members

Because the base ContentBlockToConfigurationUpgrade<,> 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 and ConfigurationKey properties

This properties tells Sana Commerce Cloud to which content block model needs to be upgraded to which configuration model:

Implement Upgrade method

This is the actual upgrade implementation. Implement what you need to upgrade in your content block model from previous version to configuration model (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 copy some text in SecretKey from content block model to configuration model:

public override void Upgrade(IReadOnlyList<v1_0_0.TutorialContentBlockModel> contentBlockModels, TutorialConfiguration configurationModel)
{
    if (contentBlockModels.Count > 0)
        configurationModel.SecretKey = contentBlockModels[0].SecretKey;
}

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:

Content block model before the upgrade, version 1.0.0:

Configuration model 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 simply add a new 'Upgrades/v1.0.2' folder and continue from Step 1: Snapshot of the 'old' content block modell:

Conclusion

That's it, the upgrade of content block to configuration model add-on is complete.

Back to general implementation tutorial