Restrict Global Symbol Downloads to a Minor Version in Business Central 2026 Release Wave 2

Hi Readers,

Business Central 2026 release wave 2 (BC29) adds a useful AL development option for controlling which symbols are downloaded from global sources. 

You can now keep global symbol resolution within the major and minor version specified in app.json, while still allowing the tooling to select the newest available patch/hotfix for that minor version.

Why does global symbol versioning matter?

AL developers need symbol packages to compile extensions and resolve references to objects exposed by the base application and other dependencies.

Since Business Central 2026 release wave 1 (BC28), AL developers can download symbols directly from global Microsoft NuGet sources instead of relying exclusively on a connected Business Central development environment. This makes symbol acquisition much more convenient, particularly for projects where a running sandbox or development container isn't available.

The challenge is version selection.

An application version in app.json identifies the Business Central application version the project is built against. With global symbol downloads, the tooling can resolve a newer available version within the same major version unless minor-version enforcement is enabled.

For some development and CI scenarios, that can be broader than intended.

What is Global Sources Enforce Minor Version?

BC29 introduces Global Sources Enforce Minor Version.

When this setting is enabled, global symbol downloads are constrained to the major and minor version specified in the application property of app.json.

For example, if the project contains:

{
  "application": "28.3.0.0"
}

and minor-version enforcement is enabled, global symbol resolution stays within 28.3.x.x rather than moving to a later 28.x minor version.

The latest available patch/hotfix within that minor version can still be selected.

This gives developers a useful combination:

• Major version is controlled.

• Minor version is controlled.

• Latest available patch within that minor version can still be selected.

Microsoft's BC29 preview documentation describes the capability as configuring global symbol downloads to remain within the major and minor version in app.json while selecting the newest available patch for dependencies.

What happens when the setting is disabled?

Minor-version enforcement is disabled by default.

With the setting disabled, global symbol resolution can select the latest available version within the same major version, regardless of the minor version specified in app.json.

For example, a project targeting:

{
  "application": "28.3.0.0"
}

can resolve a later 28.x version when downloading from global sources.

That behavior can be convenient when the goal is simply to work with the newest symbols available for a major release.

However, it can also introduce a difference between the version you intended to develop against and the version actually downloaded.

How do you configure the target minor version?

The first part is the application property in app.json.

For example:

{
  "application": "28.3.0.0"
}

The second part is enabling Global Sources Enforce Minor Version in the AL/Visual Studio Code settings.

Once enabled, use:

AL: Download symbols from global sources

The tooling then resolves symbols within the specified major/minor version and selects the newest available patch that satisfies that version.

A practical example

Imagine a project that is intended to compile against Business Central 28.3.

The project specifies:

{
  "application": "28.3.0.0"
}

Assume the global repository contains multiple 28.x versions, including later minor versions.

With minor-version enforcement disabled, the global download can resolve a later 28.x version.

With minor-version enforcement enabled, the resolution is restricted to 28.3.x.x.

If several 28.3 patch versions are available, the newest applicable patch is selected.

This is especially useful when you want reproducible development boundaries without manually pinning an individual patch release.

Why is this useful for AL developers?

1. Better control over development targets

Your app.json can express the intended application minor version, and global symbol resolution can respect that boundary.

2. More predictable symbol downloads

Developers working on the same target minor version can avoid unexpectedly resolving symbols from a later minor release of the same major version.

3. Latest patch without manually changing the project

You don't have to pin the project to a specific patch just to avoid crossing a minor-version boundary. The tooling can still select the newest patch available within the requested minor version.

4. Useful for CI/CD and repeatable development

When symbol downloads happen from global sources, controlling the minor version can make the development environment's symbol target more explicit.

How does this relate to global symbol downloads?

Global symbol downloads were introduced in BC28, allowing AL developers to retrieve symbols from Microsoft's global sources without first connecting to a Business Central environment.

The workflow is straightforward:

1. Define the application version in app.json.

2. Configure the required symbol source/localization settings.

3. Run AL: Download symbols from global sources.

4. AL downloads the matching symbol packages into the project's .alpackages folder.

BC29 adds more control over how that global version is resolved.

What should you demonstrate in a video?

A simple demonstration makes this feature much easier to understand.

Start with an AL project and show the application property in app.json.

For example:

"application": "28.3.0.0"

Then show the Global Sources Enforce Minor Version setting.

First, demonstrate symbol download with the setting disabled and explain that global resolution can move to a later minor version within the same major release.

Then enable the setting and run:

AL: Download symbols from global sources

Show that the downloaded symbols remain within the 28.3 minor version while the newest available patch is selected.

Finally, change the application value to another minor version and repeat the download to demonstrate that the resolution boundary follows the project configuration.

FAQ

What does Global Sources Enforce Minor Version do?

It restricts global symbol downloads to the major and minor version specified in the application property of app.json, while allowing the newest available patch within that minor version.

Is minor-version enforcement enabled by default?

No. Microsoft documents the setting as disabled by default.

Does this pin symbols to one exact patch version?

No. The purpose is to constrain the major and minor version while still allowing the latest applicable patch/hotfix to be selected.

What property defines the target Business Central application version?

The application property in app.json defines the application version the extension is built against.

Can I still download symbols from global sources without this setting?

Yes. Global symbol downloads are available from BC28 onward. The BC29 change adds control over whether global resolution must stay within the specified minor version.

Conclusion

BC29's Global Sources Enforce Minor Version setting gives AL developers finer control over global symbol resolution.

Instead of choosing between completely open major-version resolution and manually pinning a specific patch, you can target a minor version such as 28.3.0.0 and let the tooling select the newest available 28.3.x.x symbols.

For teams using global symbol downloads, this provides a practical way to keep development aligned with a specific Business Central minor release while continuing to benefit from the latest patch available within that release.

Subscribe to the Saurav Dhyani YouTube channel for Business Central technical tutorials, AL development, APIs, extensions, new features, and practical implementation guidance.

You can also connect with me on: 

LinkedIn

YouTube 

Regards,

Saurav Dhyani