Get started

This guide takes you from nothing to a compiled, tested Business Central app, locally, then in an Azure DevOps pipeline.

There are two ways in, and they share one engine (the businessdev.ALbuild module), so you can mix them freely:

• The albuild CLI: the fastest, cross-platform on-ramp. It installs as a .NET global tool and bootstraps everything else for you: albuild doctor checks the host, albuild module install installs the PowerShell module, albuild setup / init scaffold your config. Best on macOS/Linux and for a guided start. Full guide: CLI → Get started.
• The PowerShell module directly: for full scripting control and the richest cmdlet surface.

This page uses the module for the worked example; the CLI equivalents are linked alongside.

1. Prerequisites

2. Install ALbuild

Pick the on-ramp that fits how you work, both end up driving the same businessdev.ALbuild engine.

Option A: the CLI (fastest, cross-platform)

Install the albuild global tool, then let it check the host and install the PowerShell module for you:

Code
dotnet tool install --global businessdev.ALbuild.Cli   # provides the `albuild` command
albuild doctor                                         # PowerShell + module + Docker readiness
albuild module install                                 # installs the businessdev.ALbuild module
albuild module update                                  # (later) keep the module current

The CLI runs everything through the module. See CLI → Get started for the full inner loop, and CLI → Backends for the macOS "compile local, run on a remote host" flow.

Option B: the PowerShell module directly

The module is published to the PowerShell Gallery as a single package (businessdev.ALbuild) that contains all nine use-case areas.

Code
# install once: one package, all areas
Install-Module businessdev.ALbuild -Scope CurrentUser
Import-Module businessdev.ALbuild

Verify it loaded:

Code
Get-Command -Module businessdev.ALbuild | Measure-Object   # how many cmdlets are available

3. Build an app locally

The snippet below resolves the latest BC sandbox artifact, creates a container, restores dependencies, compiles, publishes and runs the tests, entirely from PowerShell.

Code
Import-Module businessdev.ALbuild

# 1. Resolve the BC artifact and create a container
$artifact = Find-BcArtifactUrl -Type Sandbox -Country w1 -Select Latest
$cred     = Get-Credential
New-BcContainer -Name bld -ArtifactUrl $artifact -Credential $cred

# 2. Restore dependencies into .alpackages (NuGet / Universal / local).
#    Target application and platform are read from app.json unless you override them.
Resolve-BcDependencies -ProjectFolder ./app

# 3. Compile (container-less via the AL tool; -Engine Container compiles inside the container)
Invoke-BcCompiler -ProjectFolder ./app -Engine AlTool

# 4. Publish, sync and install into the container
Publish-BcContainerApp -Name bld -AppFile ./app/output/MyApp.app -Sync -Install

# 5. Run the tests. The test toolkit has to be in the container once, and the test
#    app itself has to be published before its codeunits can be discovered.
Install-BcContainerTestToolkit -Name bld
Invoke-BcCompiler -ProjectFolder ./test -Engine AlTool
Publish-BcContainerApp -Name bld -AppFile ./test/output/MyApp.Tests.app -Sync -Install
Invoke-BcContainerTest -Name bld -ProjectFolder ./test -Credential $cred -ResultPath TestResults.xml

# 6. Tear the container down
Remove-BcContainer -Name bld

Every cmdlet above is documented in the PowerShell module reference.

Code
albuild init --country de --bc-version 28.2          # scaffold albuild.json
albuild feeds add https://pkgs.dev.azure.com/acme/_packaging/bc/nuget/v3/index.json
albuild container new --project ./app --workspace .  # provision the BC container
albuild run pipeline --workspace . --container bld   # build → publish → test

4. Configure your project (albuild.json)

Rather than repeat arguments on every command and pipeline step, commit an albuild.json at the root of your repository. ALbuild reads it automatically.

Code
{
  "country": "de",
  "artifactType": "Sandbox",
  "select": "Latest",
  "feeds": [
    "https://pkgs.domain.com/nuget/index.json"
  ]
}

See Project configuration for every setting.

5. Build in Azure DevOps

1. Open the Azure DevOps Marketplace and install ALbuild for Azure DevOps into your organization.
2. Add the tasks to your pipeline. A minimal build pipeline:

Code
trigger: [ main, master ]
pool:
  name: Self Hosted          # a Windows agent with Docker

steps:
  - checkout: self
    persistCredentials: true

  - task: GetBcArtifact@0
    inputs: { type: 'Sandbox', select: 'Latest', country: 'w1' }

  - task: StampBuildVersion@0
    inputs:
      schema: 'major.minor.increment.0'
      onlyUpdateOnChangedSource: true
    env: { AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) }

  - task: CreateBcContainer@0
  - task: ResolveDependencies@0
    env: { AZURE_DEVOPS_EXT_PAT: $(System.AccessToken) }
  - task: CompileApp@0
  - task: PublishApp@0
    inputs: { syncMode: 'Add', install: true }
  - task: RunBcTests@0
  - task: PublishTestResults@2
    inputs: { testResultsFormat: XUnit, testResultsFiles: TestResults.xml, failTaskOnFailedTests: true }
  - task: RemoveBcContainer@0
    condition: always()

Packaging is its own step: add CreateNuGetPackage@0 after the compile when you want a NuGet package, and PublishPackage@0 to push it.

All build, compile, test, sign and NuGet-publish tasks are free of license. Only the deployment tasks (PTE, on-prem, dev extension, Marketplace, runtime packages) require a subscription. See Licensing & tiers.

Ready-to-use templates ship in the templates/ folder of the repository.

6. Reproduce the pipeline locally

You can run the same Azure DevOps YAML template on your machine, step by step:

Code
Invoke-ALbuildPipeline -Path templates/yaml/ci-pipeline.yml `
    -Parameters @{ country = 'de'; projectFolder = 'app' } `
    -RepositoryRoot 'D:\Code\DevOps\Customer\D365BC-Core'

See the local pipeline runner for details.

Next steps

• CLI: the cross-platform command-line and the macOS remote-host flow.
• Probe: evaluate AL expressions and call procedures without a container, in under a second. The tightest feedback loop ALbuild offers, and the one built for AI agents.
• Architecture & modules: how the pieces fit together.
• Azure DevOps extension: every pipeline task.
• VS Code extension: the inner-loop tooling.
• MCP server: wire up an AI assistant for the runtime inner loop.