How to prepare your Per-Tenant Extension for the Business Central Wave 2 Update

Recently, I’ve got a bunch number of e-mails starting with this Subject “Your extension is incompatible with an upcoming release of Microsoft Dynamics 365 Business Central”


So, I thought, not me only getting this, and maybe someone is getting stuck of how to react on this. This post is for you 


That situation could happen not only with the upcoming Wave 2 release. Any new update of Business Central brings us new features or depreciation of the old features, which our extension could rely on. So, when you extend some base field and Microsoft decides to delete it, you probably need to restructure your extension. And that not only about fields, that could also happen if any peace of base code, that you call or subscribe to or extend will be refactored by the Microsoft. 

Wave 2 brings us not only AL-only, but also split Base App and System App approach. Which resulted in a huge number of breaking changes and how to resolve them document.  Be aware that the list is not full there. 


Let me describe my case, and how did I resolve it. Hopefully, you will find this similar to yours.

I had an app that worked excellently for Business Central 14.3. And one of the parts of my app, was auto-fill-with-demo-data for the sandbox environments.


with these settings in app.json file


Then I received those message “Your extension is incompatible with an upcoming release of Microsoft Dynamics 365 Business Central”.

How to resolve


Get new AL version

First, you need to create a Business Central Wave 2 environment: cloud or local. But, I guess before Wave 2 will become publically available, you need to create local environment, at least for 1 thing – next version of AL for vscode.

It should have the version


Maybe in the nearest future, it will come with new logo according to this info 🙂 

So, create a new local environment



					$imageName = ""
$containerName = "test"
$auth = "UserPassword"
$credential = New-Object pscredential 'admin', (ConvertTo-SecureString -String 'P@ssword1' -AsPlainText -Force)
$licenseFile = ""

New-BCContainer -accept_eula `
                -imageName $imageName `
                -containerName $containerName `
                -auth $auth `
                -credential $credential `
                -licenseFile $licenseFile `

and install new .vsix file as described here.

Get new dependencies

Second, create a new extension for Wave 2


The only reason you should do that is to grab dependencies on the base app and system app, and copy them into your extension app.json file


To make life easier, i’ll just post it here in a copy-paste mode

					  "dependencies": [
      "appId": "63ca2fa4-4f03-4f2b-a480-172fef340d3f",
      "publisher": "Microsoft",
      "name": "System Application",
      "version": ""
      "appId": "437dbf0e-84ff-417a-965d-ed2bb9650972",
      "publisher": "Microsoft",
      "name": "Base Application",
      "version": ""

Change app.json file

So, copy dependencies to you extensions app.json file, change runtime to 4.0, change platform to 15,  and don’t forget to change version of your extension!

Here is the whole list of changes I did in app.json file


Let’s move to the launch.json

Change launch.json file

The main difference here is that “serverInstance” was changed from NAV to BC.


Get new symbols

Now the same steps as before, get new symbols.


As a result, you’ll have old symbols and new symbols in your .alpackages folder. You can leave as is, but I prefer to delete the old ones.


Now you symbols should look like this


Compile your code

Usually, your code will be compiled automatically, but i found that after getting new symbols, the old symbols where saved in the memory. So, i reopened the folder in the vs code for auto-compile, or you can run Package function.


Check errors

Now I see what was changed by Microsoft


Resolve the errors

This is, of course, will depend on your errors. In my case, I found here that “Tenant Management” was replaced by “Environment Information”, so changing my code to the next one, fixed my issue.


Create new .app file

Package your fixed extension (with the new version!) to the new .app file


Publish your new .app file to your Production tenant

Now it’s time to upload your extension version, compatible with Wave 2 release to the production tenant.

Online Production Tenant > Extensions > Upload Extension 

Choose you new .app file and select Deploy to: Next major version, and Deploy


and here we go


Now your per-tenant extension will remain in your production tenant, even after upgrade to Wave 2 … hopefully 🙂


Share Post:

Leave a Reply

About Me


A Microsoft MVP, Business Central architect and a project manager, blogger and a speaker, husband and a twice a father. With more than 15 years in business, I went from developer to company owner. Having a great team, still love to put my hands on code and create AI powered Business Central Apps that just works.

Follow Me

Recent Posts