Architecture & modules

ALbuild is a single PowerShell package, businessdev.ALbuild, composed internally of use-case nested modules that ship and version together as one package. The Azure DevOps extension, the VS Code extension, the CLI and the MCP server are thin shells on top of it.

Code
┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Azure DevOps   │ │ VS Code        │ │ albuild CLI    │ │ MCP server     │
│ tasks          │ │ extension      │ │ (cross-platf.) │ │ (AI agents)    │
└───────┬────────┘ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘
        │                  │                  │                  │
        └──────────────────┴─────────┬────────┴──────────────────┘
                                     ▼
        ┌─────────────────────────────────────────────────────────┐
        │            businessdev.ALbuild  (PowerShell)            │
        │  Core · Containers · Apps · Feeds · RuntimePackages ·   │
        │      Marketplace · OnPrem · Environments · Pipeline     │
        └─────────────────────────────────────────────────────────┘

All four surfaces are thin shells over the same module. The CLI and the MCP server added the cross-platform and AI-agent entry points, but none of them re-implement container, compile or coverage logic. The behaviour is identical wherever you drive it from.

The one deliberate exception: AL Probe

albuild probe is not a shell over the PowerShell module. It is an AL interpreter written in C# and hosted inside the CLI: a lexer, parser and tree-walking evaluator that reads your .al source directly and evaluates expressions and procedure calls in-process.

That is the whole point of it. Every other surface answers "what does Business Central do?" by asking Business Central, which costs a container and minutes. Probe answers a narrow slice of the same question in well under a second, with no Docker and no server, so an agent can check a piece of logic as often as it likes.

The cost of a second engine is the risk of the two disagreeing, so probe is built to refuse rather than guess: anything it cannot model exactly (Commit, Random, unsupported CalcFormula kinds, Format format strings) returns a refusal, not an approximation. A differential harness runs the same AL through both engines and turns any disagreement into a failing test. Probe is a fast pre-check, never a replacement for running the real tests.

The nested modules

Licensing tiers are enforced at runtime (via Assert-ALbuildLicensed), independent of packaging, every cmdlet ships in the one package, and the licensed ones check on entry. See Licensing & tiers.

Naming conventions

• Cmdlet nouns use the Bc prefix for Business Central operations (New-BcContainer, Invoke-BcCompiler) and ALbuild for ALbuild's own tooling, configuration, logging and licensing (Get-ALbuildConfig, Write-ALbuildLog, Assert-ALbuildLicensed).
• Every public cmdlet ships comment-based help; the cmdlet reference pages are generated from it.

Two kinds of configuration

ALbuild deliberately separates per-repository settings from per-machine settings:

The machine configuration file (config.json)

The per-machine settings live in a JSON file the module reads automatically (so the CLI, the Azure DevOps tasks and the MCP server all honour it). You normally manage it with cmdlets rather than editing it by hand:

Code
Get-ALbuildConfig                                    # the effective configuration
Get-ALbuildConfig -Name BcArtifactCacheFolder        # a single setting
Set-ALbuildConfig -Settings @{ BcArtifactCacheFolder = 'D:\bcartifacts.cache' } -Persist

-Persist writes the file; without it the change lasts only for the current session.

These are machine settings, so they are stored machine-wide by default, in two layers:

Writing the machine file requires an elevated session on Windows, which is deliberate: a build agent's cache location should not be something one account can change out from under another. Without elevation you get an explicit message naming the scope, and can fall back to -Scope User for a developer box.

ALBUILD_CONFIG still names one explicit file and then replaces the layering entirely. It is meant for tests and for pinning a configuration in an isolated run, not as the normal way to configure an agent:

Code
$env:ALBUILD_CONFIG = 'C:\ProgramData\ALbuild\config.json'   # replaces both layers
Set-ALbuildConfig -Settings @{ BcArtifactCacheFolder = 'D:\bcartifacts.cache' } -Persist

It is plain JSON, so you can also drop the file in place directly:

Code
{
  "BcArtifactCacheFolder": "D:\\bcartifacts.cache",
  "ArtifactCacheFolder": "D:\\ALbuild\\artifacts"
}

Settings and their defaults:

Code
ALBUILD_BCARTIFACT_CACHE = D:\bcartifacts.cache

Platform support

• Container operations (*-BcContainer, test toolkit, in-container compile/test) require a Windows host with a running Docker engine. They fail fast with a clear message on other platforms, enforced by Test-BcPlatform and Test-BcDocker.
• Container-less operations: compilation via Microsoft's cross-platform al dotnet tool, dependency resolution, signing, Marketplace/SaaS REST and XLIFF, run on any platform with PowerShell 7.
• albuild probe needs neither Docker nor PowerShell nor a Business Central installation. It is pure .NET inside the CLI and runs anywhere the CLI runs.