How to handle breaking changes?

Wagner and I are on our way to Vienna to present at Directions EMEA, and now we got into our second flight after flying over 15000Km from Auckland New Zealand, to Dubai. We got another 6 hours to complete on this flight before we step our foot in Vienna. Went through the in-flight entertainment system, but almost all the movies are not my type or watched already. What better way to spend 6 more hours rather writing some blog posts on Wave 2 release. Here we go.


What are these breaking changes?
If there are any schema changes that may result in any data loss, then it can be categorized as a breaking change. Changing the primary key of the table, or changing the data type, reducing the field length can be categorized as breaking changes.


What is the big deal about it as we used to do this all (most) the time?
Exactly! If you are so much used to C/AL then must be wondering is this something even to blog about? Oh yes! Because with the Wave 2 release Microsoft officially stopped shipping C/AL code with the product DVD. Even if you want to run Microsoft Dynamics 365 Business Central on-premise version just because you want to do C/AL changes, you are no longer able to do that with the latest version. This means fob is no longer available and with that force-sync option is gone too.

That is why we need to handle the breaking changes in Microsoft’s way. At the start, this whole process will feel like taking to much time, but when you think about it, it is all about giving a better (seamless) experience to the customer.

How do we handle breaking changes?
If your extension is only in sandbox then you are lucky, because you got a couple of easy options.

  1. Drop the sandbox and create a new one. 
  2. In the launch.json file changes the “synchronization” parameter to recreate or force

If the option selected was,


Force: It will force changes regardless of the data loss. This does not guarantee any data loss preventions, it simply applies the changes.

Recreate: It will definitely drop all the tables and table extensions created through the extension. This action will lead to data loss and then create the schema from scratch.

These options are acceptable since it’s the sandbox and you may be comfortable losing data. However above-mentioned options are not available in the production environment.

Then how to handle breaking changes in production?
It all depends on the change you want to make, if the change is related to a field then your option would be to obsolete the field and create a new field on the table, then write an upgrade codeunit to transfer the data from the old field to the new field during the installation.

Dimitri wrote a very nice blog on how to write an upgrade codeunit to transfer data. I might be creating a similar post on that, but I would suggest you read that and get a good understanding of how things work in SaaS.

What if the change is related to the Primary Key of the table?
Unfortunately, you will have to obsolete the entire table and create a new table. Then write an upgrade codeunit to do the data transfer. There are few things to keep in mind when obsoleting a table of a field. Make sure all the table relationships are commented out in the code.

As an example, you create a table and one of the fields has a table relationship to dimension code. Then you went ahead and obsolete your table. It all looks good and works fine if the user did not delete or rename the dimension code.

As soon as a user rename or delete the dimension code system will try to modify all the related fields, and it will throw an error to the user. This seems to be something Microsoft should fix but for time being just to make sure when you obsolete any field or table, remove the table relationship to be on the safe side.

How to make a field or table obsolete?
If you want to obsolete the entire table then you can add Obsolete Status and Reason just like below.

If you want to obsolete the field, then you need to add the status and reason as below.

Once you do that just make sure to handle the data upgrade as well. You need to write a small codeunit to upgrade the data from your old table/field to the new table/field.

What annoys me the most?
There are few things annoys me with this process,

  1. All the obsolete tables and fields still are in the schema which means it will be in the extension code.
  2. Finding a new name: As a developer what I always struggle is to come up with a shorter but good name to a field or to a table. Then have to drop that field or table? That is just sad. 

Is there any solution for this?
As per this moment we don’t, we will have to come up with new names and to maintain all the obsolete fields and tables on our codebase, but the good news is Microsoft knows this and they are working on the solution. They will release function to clean up the schema. ? 


As per now, just be careful and think twice before releasing any schema changes to the production environment.

Please provide your feedback with a comment.
Thank you and Regards,
Tharanga Chandrasekara

Click on a star to rate it!

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?