+1 480 485 7373
Microsoft Teams
How a per-tenant extension works in Business Central
Microsoft builds Business Central from extensions. The base application is one, AppSource apps are others, and your own customizations are more. An extension cannot edit another extension's code. Instead, it adds new objects and extends existing ones through defined points. Table and page extensions add fields and actions. Event subscribers run logic when the base application raises an event. There are also report extensions and new objects of its own.
A per-tenant extension, often shortened to PTE, uses object IDs in the range reserved for customer-specific work, 50000 to 99999. Your team uploads it to a single tenant. Developers write it in AL using Visual Studio Code with Microsoft's AL extension. They compile it against the Business Central version it targets and package it as an app file.
Because the base application stays untouched, Microsoft can update it underneath your extension. That is the whole point, and it is also the discipline. Your code must rely only on published events and interfaces. It must not assume how Microsoft's internals happen to behave this month.
Per-tenant extension or AppSource app in Business Central
A Business Central extension from request to production
- 1
Write the requirement in business terms
State the problem, who has it and how you will check the result. Many requests dissolve at this point because standard setup already covers them.
- 2
Check standard features and AppSource
Look for configuration, a newer standard feature or a maintained app before approving code. Building is the last resort, not the first.
- 3
Develop in a sandbox
The developer builds and publishes to a sandbox from Visual Studio Code, never directly to production. The source code lives in a Git repository.
- 4
Test with users
Key users test the change in the sandbox with their real permissions, alongside regression checks on nearby processes.
- 5
Deploy a versioned package
Upload the signed-off app file to production through extension management or a build pipeline. Raise the version number every release.
- 6
Record and own it
Document what the extension does, who owns it and which events it depends on. Then the next person can support it.
Keeping Business Central extensions compatible with update waves
Business Central online receives two major releases a year, in spring and autumn, plus smaller monthly updates. Microsoft makes each major release available early for preview in sandbox environments. Administrators also get a window to schedule the production update. Test your extensions against the new version during that preview, not in the week the update becomes mandatory.
Microsoft marks code it intends to remove as obsolete well ahead of removal, and the compiler warns about it. Treat those warnings as a to-do list. If an extension would fail against a new version, Microsoft notifies the tenant administrator. An extension that nobody makes compatible can block the update until someone fixes it.
Teams that do this well keep every per-tenant extension in Business Central in source control. They compile automatically against upcoming versions and keep automated tests for the logic that matters. Microsoft's AL-Go for GitHub templates exist to make that setup straightforward.
Questions before approving a new Business Central extension
- ✓Can setup, a workflow or a newer standard feature solve this instead?
- ✓Does a maintained AppSource app already do this well enough?
- ✓Is this process genuinely how we compete, or just how we have always done it?
- ✓Who will own and support this code in three update waves' time?
- ✓Does it depend only on published events rather than copied Microsoft logic?
- ✓Is there a test that proves it still works after each update?
Per-tenant extensions in Business Central: common questions
What is the difference between a per-tenant extension and an AppSource app?
A per-tenant extension serves one customer and lives only in that customer's tenant, while an AppSource app is a product for many customers. AppSource apps go through Microsoft's technical validation, and their publisher maintains them. You and your partner maintain your own extensions. Both use AL and run the same way inside Business Central.
Will our extensions break when Microsoft updates Business Central?
They should not, if developers build them only on published events and test them against each release during the preview. Problems come from relying on obsolete code or undocumented behavior. Microsoft warns about obsolete code in advance and notifies administrators about incompatible extensions. A routine of compiling and testing against preview versions catches issues early.
Code ownership, environments and extension count
Do we own the source code of our per-tenant extension?
You should, and the contract with whoever builds it should say so plainly. Ask for the AL source in a repository you control, not just the compiled app file. Without the source, changing partners or fixing a problem becomes very difficult. We put code ownership in writing before development starts.
Can we move a per-tenant extension to another environment?
Yes, you can install the same app file in sandbox and production environments of the same tenant, which is how testing works. A different customer's tenant is another matter. That usually signals it should become an AppSource app or a shared product. Object ID ranges and dependencies also need checking when environments differ in the apps they have installed.
How many extensions is too many?
There is no fixed number, but every extension is code someone must maintain through every update. A few well-owned extensions that close real gaps are healthy. Dozens of small ones, each copying a spreadsheet habit, recreate the upgrade pain of older systems. A periodic check keeps the count honest. It retires any per-tenant extension in Business Central that a new standard feature has made redundant.
Talk to us about your project.
Tell us what you run today and what has to change. A senior consultant replies with a written next step.