Business Central Extensions: How AL Extensions Actually Work

What Are Business Central Extensions?

A Business Central extension is an AL-language package that adds or modifies functionality without touching the base application's source code. Since Microsoft moved the product away from C/AL and C/SIDE - completing the shift at Business Central Wave 2 (version 15) - the product is fully extension-based. Even the base application itself ships as an extension, alongside the open-source System Application modules that partners can consume.

Extensions are written in AL (Application Language), Microsoft's only supported language for Business Central development. They use constructs like tableextension, pageextension, and enumextension - plus event subscriptions and interfaces - to extend base objects rather than overwrite them. This extension-only architecture is what lets Microsoft ship twice-yearly major release waves without partners re-merging customizations into the core - the exact problem that made the old C/SIDE base-code modifications so expensive to maintain.

Under the hood, when a package is published to a Business Central environment, the AL compiler generates C# assemblies and metadata that are stored in the Azure SQL database and loaded into a runtime cache so objects start faster on subsequent runs. This compile step happens at installation time against the latest dependencies, which is why a correctly built .app file can still behave differently from one environment to the next if the platform version differs.

If you are weighing BC against a modular platform like Odoo (where Odoo Studio customizations layer on top of the core in a similar no-touch way), the parallel is real but the mechanics differ: BC enforces a compiled, signed, version-bound package model, while Odoo's customizations sit inside the app's own inheritance chain. Either way, the strategic lesson for SMEs is identical - extend, do not modify the vendor's base code.

How AL Extensions Work

Development happens in Visual Studio Code with the official AL Language extension installed. The AL: Go! command scaffolds a new project against a sandbox tenant, generating the app.json manifest, launch.json, and a sample HelloWorld page - enough to publish to a sandbox on the first run.

An extension's identity lives in app.json: a unique app ID (GUID), a version number, dependencies on other extensions (including the base application and the System Application), and the object ID range assigned to the publisher. Microsoft's documented object ranges reserve 0-49,999 for the Business Central base application - it must never be used in extensions - while 50,000-99,999 is the range for customer and partner customizations (the classic PTE range). Higher reserved ranges are allocated by Microsoft to AppSource publishers, typically in the 70,000,000+ block.

That object ID range is not a cosmetic convention - it is what distinguishes the extension types at the platform level. As practitioners put it, apps built in the 70,000,000 range are AppSource apps, while apps built in the 50,000 range are Per-Tenant Extensions. The two look similar in AL, but the range dictates where the app can be deployed and how it is governed.

Inside the package, AL enforces a clean structure: one object per .al file, a consistent prefix or suffix naming convention to avoid collisions, namespaces, PascalCase variables, 4-space indentation, and lowercase keywords. Microsoft's CodeCop and AppSourceCop analyzers enforce these conventions at compile time and flag issues before publish - AppSourceCop is mandatory for any app heading to AppSource validation, and PerTenantExtensionCop is the equivalent gatekeeper for PTEs, reminding developers to ship matching permission sets for every new table.

Microsoft's developer documentation defines extension identity precisely by scope. A Global (AppSource) app is uniquely defined by its id and version, and you cannot deploy a Global app with the same id and version but different content to multiple environments. A PTE adds a third dimension - it is uniquely defined by its app id, version, and the environment it is deployed to - which is why the same app id and version can legitimately exist with different content in two separate environments.

Extension Types: PTE vs AppSource vs DEV

Business Central supports three extension scopes, and choosing the right one is one of the most consequential decisions in any BC customization project. Microsoft's developer documentation defines them by scope: Global, Per-Tenant (PTE), and Dev.

Global apps are published by Microsoft or via AppSource and are available across tenants. Per-Tenant Extensions (PTEs) are uploaded directly to a specific environment and exist only there - their metadata and assemblies are not shared across environments, though a PTE can depend on Global apps, other PTEs, or DEV extensions. DEV extensions live only in sandbox environments and are uninstalled when the sandbox is updated or relocated, which is why they are strictly for development and throwaway exploration.

The dependency rules are scope-bound and strict: a Global app can only depend on other Global apps, whereas a PTE or DEV extension can depend on Global apps, other PTEs, or DEV extensions. You control the full lifecycle (publish, install, upgrade, uninstall) of PTEs and DEV extensions and can force-sync them; for Global apps you can install, uninstall, or upgrade but you do not control when they are published or unpublished, because other environments in the service may rely on them.

The simplest framing for an SME: if the customization would be valuable to many customers, build an AppSource app; if it is bespoke to one customer's processes, build a PTE; if it is throwaway exploration in a sandbox, use a DEV extension.

PTE vs AppSource: The Decision Framework

A common misconception is that PTEs and AppSource apps are technically different beasts. They are not: both are written in AL, compiled to a .app file, and scaffolded the same way in Visual Studio Code. The technical work is almost identical; what diverges completely is the application lifecycle management, the support model, and the business case.

Choose a PTE when the customization is bespoke to one customer's processes, when speed to a single tenant matters more than market reach, and when the partner wants to retain direct control of the release schedule. PTEs carry no AppSource validation overhead and no marketing requirements - the partner compiles and uploads the .app and owns every upgrade.

Choose an AppSource app when the same functionality would be valuable to many customers, when recurring per-user revenue is the goal, or when the customization needs to run across multiple tenants in a single environment. AppSource apps also share their compiled assemblies and metadata across environments, which keeps memory usage lower and object load times faster than a PTE deployed many times - an important consideration in high-transaction environments.

The runtime difference is real even though it is invisible in the AL code. AppSource apps share their C# assemblies and metadata across every environment they are installed in, because they carry a single global identity granted by AppSource. A PTE does not share them - its assemblies and metadata are specific to each environment, so if you install the same PTE into two environments within a tenant, the metadata and assemblies are duplicated. Microsoft's guidance is direct: if you plan to distribute the same extension across different environments and tenants to multiple customers, distributing it via AppSource is usually the better choice.

The AL Extension Development Lifecycle

A typical PTE engagement moves through a predictable loop. The partner scaffolds the project in VS Code, develops against a sandbox, tests, and then publishes the compiled .app file to the customer's production environment via the Extension Management page or, since 2024 release wave 2, through the Business Central admin center.

On first install, an optional Install codeunit (SubType = Install) runs two triggers: OnInstallAppPerDatabase fires once per database, and OnInstallAppPerCompany fires once per company. These triggers seed default data, set up configuration, or migrate entries from a legacy table. Install codeunits run on first install and on reinstall - they do not run on a version upgrade, which is handled by a separate Upgrade codeunit.

That install-versus-reinstall distinction trips up many first-time PTE developers. Because the install triggers fire again whenever an app is uninstalled and reinstalled, naively seeding default configuration in OnInstallAppPerCompany will overwrite a customer's edits on the next reinstall. The reliable pattern is to call NavApp.GetCurrentModuleInfo and check whether DataVersion equals Version.Create(0,0,0,0) - if it does, it is a true fresh install and defaults are safe to populate; otherwise treat it as a reinstall and leave existing data alone.

1. 01
   Scaffold and develop

   Run AL: Go! in VS Code against a sandbox, write table/page/enum extensions and event subscribers, and validate with CodeCop and AppSourceCop (or PerTenantExtensionCop for a PTE).

2. 02
   Match the runtime version

   Ensure the runtime version in app.json is less than or equal to the platform version of the target tenant; download fresh symbols from the online tenant and confirm the platform version in System Information before building the .app.

3. 03
   Test in sandbox

   Publish as a DEV extension to a sandbox, exercise the new behavior, and confirm no regressions against the base objects you extended.

4. 04
   Package the .app

   Compile the project to a signed .app file with the correct app ID, version, and assigned object ID range recorded in app.json - and always increment the version before uploading, or the tenant rejects it as a duplicate.

5. 05
   Install or deploy

   Upload the .app to the customer's environment via Extension Management or the admin center (PTE), or submit to AppSource for Microsoft validation (Global app).

6. 06
   Maintain and upgrade

   Ship new versions with an Upgrade codeunit that migrates data and schema between versions, using upgrade tags to keep each step idempotent.

Dependencies and Moving Between Scopes

Dependencies are how BC composes functionality, and the rules are scope-bound. A PTE can take a dependency on an AppSource (Global) app - this is common when a bespoke customization builds on top of a purchased marketplace app. To compile such an extension, the developer adds the dependency in app.json using the AppSource app's id, name, publisher, and version, and Microsoft has progressively removed the friction of obtaining the dependent apps for development and testing.

Moving an extension from one scope to another is supported, but it is never a clean rename. Microsoft documents several migration paths, and each carries real consequences. Moving a PTE to the Marketplace is the most common ambition: a partner proves a customization with a few customers as a PTE, then productizes it as an AppSource app. The hard requirements are that you cannot have a Marketplace app and a PTE with the same app id, so you must change the id - which means the installed PTE's data is not automatically available to the new Marketplace app. You must also change every object's ID (PTEs live in the 50,000 range, Marketplace apps in their allocated range) and rename objects to use the affixes that Marketplace apps require but PTEs do not.

Because the data does not follow the new id, Microsoft's documented approach for preserving it is to run the PTE and the Marketplace app side by side - they must not share object names or IDs - and define a third PTE that depends on both and is responsible for migrating the data across. Note that even if you discontinue the Marketplace offer entirely, the app id remains reserved in Business Central and cannot be reused for a PTE later, so scope changes are effectively one-way at the identity level.

The reverse - narrowing a Marketplace app down to a PTE for select customers - follows the same identity and object-ID constraints. The practical takeaway for SMEs is to decide the scope early: building bespoke work as a PTE and later trying to productize it into an AppSource app is doable, but it is a migration project with data-handling work, not a settings toggle.

Upgrade Safety: Why Compatibility Matters

Business Central ships twice-yearly major release waves, and every installed extension must stay compatible with them. Microsoft's monthly cumulative updates do not introduce breaking changes, so extensions auto-uplift cleanly between minor versions. The major versions, every six months, are where extensions can break, and that is where the mandatory maintenance commitment bites.

If a publisher lets an extension go incompatible and does not ship a compatible version in time, Microsoft enforces a strict upgrade window rather than allowing indefinite postponement. The clock starts when the new major version is available: for roughly the first 30 days Microsoft alerts administrators, resellers, and ISVs until the upgrade succeeds; if upgrade attempts keep failing into the second month, Microsoft escalates to the customer, and for AppSource extensions that have not been made compatible within that window the app can be removed from AppSource. If incompatibility is still unresolved around day 60, Microsoft initiates a wind-down period that can culminate in automatically uninstalling the extension to keep the tenant operational.

Version-to-version migration is handled by an Upgrade codeunit (SubType = Upgrade). Microsoft's developer documentation defines its triggers: OnCheckPreconditions (and its PerDatabase/PerCompany variants) to fail fast if the environment is not ready; OnUpgradePerDatabase and OnUpgradePerCompany to perform the actual data and schema migration; and OnValidateUpgrade (with its PerDatabase/PerCompany variants) to assert the result is sound - an error here rolls the upgrade back.

Upgrade tags - recorded in a per-tenant upgrade tag table - are the recommended way to make each migration step idempotent, so a re-run does not double-apply data changes. The operational lesson is simple but easy to underestimate: every extension you install is a long-term maintenance commitment, not a one-time deployment. Either the publisher keeps it compatible with each major release wave inside that window, or the customer eventually loses upgrade headroom and risks a forced uninstall.

Managing Extensions: Install, Upload, Uninstall

Administrators manage extensions from the Extension Management page inside Business Central. From there they can install AppSource apps, upload and deploy PTE .app files, and uninstall extensions when no longer needed.

Since 2024 release wave 2, administrators can also manage Per-Tenant Extensions through the Business Central admin center and its API - the same surface already used to manage AppSource apps. This unifies PTE and AppSource operations and gives partners a cleaner remote-management story across environments.

Uninstalling an extension retains its data by default; the extension can be reinstalled later and the data is still there. To purge the data, an admin must explicitly choose to delete it - via clean-mode sync through the Administration Shell, or through the Delete Orphaned Extension Data page in the client. Dependents must be uninstalled first, which protects against accidentally orphaning another extension that relies on the one being removed.

Common PTE Pitfalls and Best Practices

Most PTE problems are not exotic; they come from a handful of habits that compound across release waves. The first is overusing the in-client Designer. Every time you save a change from Design mode, Business Central creates a separate extension, and if you then make a further change it creates a second extension that depends on the first. A few iterations in and you have an unmanageable dependency chain: upgrading the base extension forces you to uninstall the dependent one, upload the new version, and reinstall the dependent manually. The fix is to avoid Design mode for production PTEs - use F6 (Publish and open in Designer) from VS Code connected to the online tenant, which keeps everything inside one extension.

The second pitfall is a runtime version mismatch. The runtime version declared in app.json must be less than or equal to the platform version of the tenant you are uploading to. A PTE built against a newer runtime will upload and even build locally, then fail at install with an obscure object-reference error. Download fresh symbols from the target online tenant and confirm the platform version in System Information before packaging.

The third is missing permission sets. Uploading a PTE that adds tables without a matching permission set fails with a clear but easily forgotten error. Activating the PerTenantExtensionCop analyzer catches this at compile time, and the AL: Generate permission set containing current extension objects command generates the file for you.

The fourth is treating one PTE as reusable across many tenants. The same app id and version cannot be uploaded to different tenants within the same regional service without an error, because a PTE's identity is scoped to its environment. If a customization truly serves multiple customers, that is precisely the signal to productize it as an AppSource app rather than copy a PTE around. The discipline that ties all of this together is simple: the fewest, most deliberate extensions per tenant, each with clean versioning, matching permission sets, and an upgrade-tag strategy from version one.

How Flectic Approaches BC Extensions

Flectic implements Business Central (and Odoo) for SMEs across Canada, the UK, and the US. On BC projects we default to the fewest, most disciplined extensions possible - because every extension is a long-term upgrade commitment bounded by Microsoft's compatibility window, and the partners who over-extend are the ones whose customers lose upgrade headroom two release waves later.

Our AI-Assisted Delivery model is designed to deliver up to 3x faster than a traditional partner engagement on suitably scoped work - not unconditionally, and never as a substitute for the prerequisites that actually de-risk a BC project: a clean RapidStart data load, a documented extension inventory, and an upgrade-tag discipline from version one. If your current BC environment has accumulated years of ad-hoc PTEs or tangled Designer-mode dependency chains, an Extension Readiness review is usually the highest-value first step.

Frequently asked questions