BC Observatoryunofficial, made by waldo
community postAL Developmentcommunity - not Microsoftreviewed - checked by Opus

Quick Tip: Runtime Version and Business Central Version Are Not the Same Thing

Explains that Business Central has three different version numbers: the platform/internal build, the release wave name and the app.json runtime version. Only the runtime version decides which AL features compile, and it sets the minimum platform an extension can be published to. Gives the runtime-to-wave mapping and advises setting the lowest runtime you need explicitly.

Open in Claude8037.md

post think about IT

Steven Renders · 2026-07-24 · 646 words · about 3 min

"An extension publishes only to environments running the same runtime or a later one, never an earlier one."
Show the post hereRead on think about IT

Key points

  • Runtime version in app.json controls which AL language features and compiler behaviors are available; the platform build and release wave name are separate numbers
  • An extension can only be published to environments whose runtime is the same as or newer than its own
  • A runtime set too low breaks newer features; set too high, it requires a platform customers may not have yet
  • If runtime is omitted, the compiler uses the latest major it supports, which changes as the tooling updates
  • Runtime 15.0, 16.0 and 17.0 map to internal versions 26.0, 27.0 and 28.0, so the offset is not constant; partners on staggered updates should target the lowest runtime that meets their needs

Quotes

  • “An extension publishes only to environments running the same runtime or a later one, never an earlier one.” (Establishes the core compatibility rule that runtime version is a forward-only contract between extensions and platforms)
  • “Treat runtime version as a compatibility contract you actively manage, not a field VS Code fills in for you.” (Emphasizes that developers must consciously choose runtime based on business requirements, not rely on tooling defaults)

Context

  • Features: AL compilation, runtime versioning, extension publishing, platform compatibility
  • Versions: 15.0, 16.0, 17.0, 2025 release wave 1, 2025 release wave 2, 2026 release wave 1

Source: think about IT - Steven Renders, community blog. Summary, key points and quotes are derived (CONTENT-NOTICE.md); read the original for the full text.