Skip to content
VANGELDER

Business Central

Upgrade-safe AL: the boring habits that pay off

Business Central updates on its own schedule, whether your customisation is ready or not. What event subscribers, table extensions and upgrade codeunits actually do at update time — and how it presents when the discipline was skipped.

18 Oct 2026 · 7 min read

Business Central online updates on a fixed rhythm: two major releases a year, with minor updates in between. About a month before each major release, Microsoft automatically tests the per-tenant extensions running in production against the upcoming version and emails the notification recipients about any incompatibility. If an extension still breaks the update, it fails, the environment rolls back and the attempt is rescheduled a week later — until the enforced update period.

That is the whole design constraint. There is no release you get to skip. Code that only works against the version of Business Central it was written on is not finished code; it is a scheduled outage with a date already on it. The habits that survive that rhythm are dull, cheap at the start of a project, and expensive to retrofit halfway through.

Subscribe, don’t override

The base application is not yours to change. You add fields with table extensions, controls with page extensions, and behaviour by subscribing to events. A publisher has no knowledge of its subscribers, and that asymmetry is the point: Microsoft can rewrite the inside of a method without breaking anyone who attached at its edge.

IsHandled is a loophole, not a pattern. Microsoft’s own guidance is to limit it to a bare minimum, and the reasons are worth reading in full. The rule that only one subscriber may handle the event is a convention with nothing enforcing it — a second subscriber can set the flag back. And when you skip a block of base code you also stop the events inside it from being raised, which breaks extensions that had nothing to do with you. There are over 8,000 IsHandled events in the base application, so the loophole is always within reach.

Table extensions are cheap to write and expensive to change

A table extension used to be a second table. From 2023 release wave 2 all extensions on a base table shared one companion table, and version 29 (2026 release wave 2) stores all fields of an AL table in the same database table. The join is gone; the width isn’t: fields you hang off G/L Entry or Sales Line still load with the base record on every read that doesn’t use partial records. For anything not needed in lists or search, a related table with a FlowField costs the base table nothing.

Companion fields switch off bulk operations. ModifyAll and DeleteAll normally compile down to a single SQL statement. They fall back to a row-by-row loop when, on versions before 29, the table has fields added through companion tables — and also when there are subscribers to OnBeforeModify, OnAfterModify, OnBeforeDelete and friends. Two reasonable-looking additions, and a batch routine that finished in seconds now walks the table.

Fields are easy to add and nearly impossible to take back. Deleting a published field is not a change the sync engine accepts. Shrinking a field’s length is refused (AS0080, or AS0118 if it’s part of the primary key), and so is changing its type (AS0004). Even increasing a length is flagged (AS0086), because a dependent extension may be assigning that value into a Text[50]. The way out is always the same shape: mark the old field ObsoleteState = Pending with a reason and a tag, add the new field, move the data in an upgrade codeunit, and remove the old one a version later. Going straight from No to Removed is itself an error (AS0115).

Keys have their own rules. Since 2026 release wave 2 (runtime 18.0) a key in a table extension can mix base-table and extension fields — on earlier versions it can’t — but never fields from another table extension, and Unique isn’t supported there at all. Don’t touch the primary key either: adding, removing or reordering its fields is schema-breaking, as is flipping DataPerCompany in either direction.

Install code and upgrade code are different jobs

An upgrade codeunit is a codeunit with Subtype = Upgrade, and it gives you precondition, upgrade and validation triggers, in that order, each in a per-company and a per-database flavour. Per-company triggers run once for every company in the database, each in its own system session; per-database triggers run once with no company open. An error anywhere in that sequence cancels the extension upgrade.

The distinction that catches people is that install code does not run on upgrade. It runs on a first install and on reinstalling a version that was uninstalled — not when a new version replaces an existing one. Anything you add to the install codeunit in version 2 reaches only environments installing version 2 from scratch. Everyone moving from version 1 skips it, and the gap shows up when someone opens a page expecting a setup record that was never inserted. The sibling trap: OnInstallAppPerCompany only runs for companies that exist at install time, so a company created next year gets none of your setup. CodeCop flags it as AA0235; the fix is to subscribe to OnCompanyInitialize on codeunit Company-Initialize as well.

Which brings us to the file nobody writes. On the day you build version 2 there is no data anywhere that needs upgrading, so the upgrade codeunit feels like work for a hypothetical. Six months later there is data in half a dozen companies and the field you should have obsoleted is gone from the source. Write it while the old field still exists — that is the only window in which moving the data is a five-line procedure.

Upgrade code also has to know whether it already ran, either by comparing extension version data or with upgrade tags. Tags need registering in the install codeunit and via OnGetPerCompanyUpgradeTags, or your upgrade code runs on fresh installs and on every new company created afterwards. And if you use several upgrade codeunits, their relative order isn’t guaranteed; each has to stand alone.

What breaks at update time, and how it presents

A compiler error during validation. The good outcome. Microsoft marks base objects ObsoleteState = Pending long before removing them, and at least twelve months and two versions pass first. References to Pending elements are warnings; references to Removed ones are errors. The warnings you have been scrolling past for a year are the errors that block a customer’s update. Setting obsoleteTagMinAllowedMajorMinor in AppSourceCop turns that into a failing build instead.

A synchronisation failure. The schema in the app no longer maps onto the data in the database. The message is blunt and names the object — the field ‘X’ cannot be located; removing fields is not allowed — and the environment stays where it is until someone publishes a build that syncs.

A forced upgrade with your extension uninstalled. When a production environment can’t be upgraded because of a per-tenant extension, Microsoft contacts the reselling partner with guidance. If the extension still can’t be updated by the time the environment’s version reaches its enforced update period — after the five-month update period and a one-month grace period — Microsoft uninstalls it automatically so the update can succeed. The table data isn’t deleted, but the functionality is gone from the customer’s environment, and nobody at the customer decided that.

Data loss you asked for. syncMode = "ForceSync" applies breaking changes by force, typically deleting the data in the objects whose schema changed and potentially breaking other apps sitting on your objects. Legitimate for a planned upgrade where you know exactly what it drops; the most expensive shortcut on the platform when it’s used to shove a stuck deployment through.

Nothing, for a while. The failure mode with no error at all: an override that still compiles, still runs, and no longer skips what it skipped when you tested it, because the base code inside the block it bypasses was refactored. No exception, no telemetry signal, no failed update — just a number someone queries weeks later.

The code is the customer’s

Per-tenant extensions are scoped to one environment, and you control when they are published, installed, upgraded or uninstalled. Keep the app ID stable and increment the version: recompiling without bumping it produces a new package for an ID and version already deployed, and the upload is rejected.

We build PTEs so the source code becomes the customer’s own property — no vendor lock-in. That commitment is only worth something if the code underneath it is worth owning. An extension held together by IsHandled overrides and a table extension nobody dares touch is the customer’s property in the legal sense and nobody’s asset in the practical one. Portability isn’t a licence clause. It is whether the next developer can read the thing, publish it against next spring’s release, and roll it back.

All insights