Upgrading AL code across Business Central versions

Business Central updates twice a year, and the platform underneath an AL extension changes with each wave. Most extensions survive without intervention, but the ones that don't fail spectacularly — sometimes silently. The strategy is to test early, fix deprecations as they're announced, and never skip a wave on production code.

What can break

Microsoft does not change its own database table fields, IDs, or method signatures lightly, but it does:

• Mark fields and methods as obsolete with the [Obsolete(...)] attribute, ahead of removing them. Obsolete code still compiles but emits warnings.
• Remove fields and methods that have been obsolete for at least two waves.
• Change the default implementation of a method (signature stays the same, behaviour changes).
• Add fields to standard tables — usually safe, unless your extension assumed a fixed schema.
• Change the runtime version required by the platform, forcing extensions to bump their runtime in app.json.

The compatibility commitment

Microsoft documents breaking changes per wave in the Application BreakingChanges.md file in the BC GitHub repo. Any field, method, or behaviour deprecation goes through a published warning period before removal — extensions that act on the warnings stay safe.

The upgrade workflow.

1. Six weeks before GA, install the preview build into a sandbox.
2. Pull the new symbols in VS Code (AL: Download symbols). The compiler now sees the new platform.
3. Build. Warnings flag deprecated symbols; errors flag genuinely broken code.
4. Fix and refactor — replace obsolete APIs with current ones, adjust to behavioural changes.
5. Run tests (you do have an automated AL test suite; see the test framework guide).
6. Republish to the sandbox, then to UAT, then to production along with the platform update.

Data upgrade codeunits

Schema-changing extensions need upgrade codeunits that migrate stored data when the new version installs — e.g. moving values from a removed field to a replacement. Microsoft's documentation has the boilerplate.

Per-tenant extensions (PTEs)

PTEs are the most upgrade-fragile because Microsoft does not pre-test them. Treat every wave as a maintenance task on every PTE.

AppSource apps

Microsoft runs your AppSource app against preview builds and notifies you if it fails. You still have to fix it, but the surface signal is automatic.

Don't skip waves

Skipping makes the next upgrade worse, not better.

Where to go next

The cadence you are upgrading against is release waves; the diagnostics you will read are in AL compiler errors. Tests that catch behavioural change are the AL test framework, automation is AL-Go CI/CD, and the safety net AppSource adds is in per-tenant extensions vs AppSource.