Copy page

Azure DevOps Extension

Build tasks

Build tasks compose a Business Central build pipeline: resolve the artifact, version the app, create the container, restore dependencies, compile, sign, publish, test and clean up. Every build task is free of license. Each task is a thin wrapper over exactly one businessdev.ALbuild cmdlet, so the behaviour is identical locally and in CI.

Tasks in this category

---

Check Translations

Reference name: CheckTranslations@0

Checks AL XLIFF files for missing and needs-work translations (CI gate).

Note: Wraps Test-BcTranslation from the businessdev.ALbuild module.

Underlying cmdlet: Test-BcTranslation

Example

Code
- task: CheckTranslations@0
  displayName: 'Check translations'
  inputs:
    path: ''                # empty = all AL projects in the repo
    skipNeedsWork: false
    failOnIssue: true

Inputs

Note: Validates the .xlf translation files (missing or untranslated entries). failOnIssue (default true) fails the build when problems are found; skipNeedsWork (default false) ignores units flagged as needing work. This task sets no output variables.

---

Cleanup ALbuild Caches

Reference name: CleanupCaches@0

Prunes old, unused ALbuild artifact/package/BC-artifact caches (and optionally Docker) to reclaim agent disk space.

Note: Wraps Clear-ALbuildCache from the businessdev.ALbuild module. Removes cache entries not written within the retention window (default 30 days), keeping recent ones, from the cache folders configured via Get-ALbuildConfig. Runs non-interactively (no confirmation prompt); use 'What-if' to preview.

Example

Code
- task: CleanupCaches@0
  displayName: 'Prune ALbuild caches'
  condition: always()          # keep the agent lean even when the build failed
  inputs:
    keepDays: '3'              # remove cache entries not written in the last 3 days
    keepLatest: '1'            # ...but always keep the newest per cache (the version in use)
    cache: 'All'              # All | Artifacts | Packages | BcArtifacts
    includeDocker: true        # also prune dangling BC images + stopped containers

Inputs

Note: Reclaims disk on long-lived self-hosted agents. ALbuild's caches grow unbounded - a multi-GB entry per BC version in the BC artifact cache (C:\bcartifacts.cache -> C:\dl), the host artifact/symbol cache and the dependency package cache - and nothing trims them automatically; repeated 'docker pull' also orphans old images. Add this as a first or scheduled step so every build self-maintains. keepLatest is a safety floor (never empties a cache); keepDays sets the retention window. includeDocker runs docker image/container prune filtered to the same window. Use whatIf: true to preview what would be removed without deleting. Reads the cache locations from Get-ALbuildConfig, so it prunes exactly the folders the tasks use (including any relocated to a roomier drive). This task sets no output variables. As of module 2.17.0, New-BcContainer also auto-prunes as a last resort when the drive is below its disk floor - but a scheduled CleanupCaches step is the intended retention mechanism.

---

Compile AL App

Reference name: CompileApp@0

Compiles an AL project into an .app package using the AL tool or a container.

Note: Wraps Invoke-BcCompiler from the businessdev.ALbuild module.

Underlying cmdlet: Invoke-BcCompiler

Example

Code
- task: CompileApp@0
  displayName: 'Compile AL app'
  inputs:
    projectFolder: ''            # empty = all AL projects in the repo, in dependency order
    engine: 'AlTool'            # container-less compile with the AL tool
    artifactUrl: '$(bcArtifactUrl)'
    # analyzers: 'CodeCop,UICop' # empty = use albuild.json / .vscode settings
    # updateManifest: true       # rewrite app.json to the target BC version (runtime-package builds)
    # alToolPrerelease: 'Auto'   # NextMajor: use the prerelease compiler when the runtime has no stable one
  # -> sets $(bcAppFile) (first app) and $(bcAppFiles) (all, ';'-joined)

Inputs

Option values

engine

alToolPrerelease

Output variables

Note: The analyzers input is free text, not a pickList: the built-in names are CodeCop, UICop, AppSourceCop, PerTenantExtensionCop (with or without the ${...} wrapper), or explicit analyzer DLL paths. It overrides albuild.json analyzers and .vscode/settings.json al.codeAnalyzers; blank everywhere = no analyzers.

The AL compiler is matched to the BC version you build against: the AL Tool's major version IS the AL runtime it supports (BC28 = runtime 17 = AL Tool 17.x, BC29 = 18 = 18.x), and a compiler older than the app's runtime fails with AL1043. The task derives that from artifactUrl and installs the matching AL Tool into its own per-version folder rather than the machine-wide global tool, so parallel stages building different BC majors on one agent keep their own compiler. Pin an exact version with alToolVersion, or change the prerelease policy with alToolPrerelease.

---

Create BC Container

Reference name: CreateBcContainer@0

Creates a Business Central container from an artifact URL and waits for it to be ready.

Note: Wraps New-BcContainer from the businessdev.ALbuild module. Sets the 'containerName', 'containerUsername' and 'containerPassword' pipeline variables for downstream tasks.

Underlying cmdlet: New-BcContainer

Example

Code
- task: CreateBcContainer@0
  displayName: 'Create BC container'
  inputs:
    artifactUrl: '$(bcArtifactUrl)'
    containerName: 'albuild-$(Build.BuildId)'
    auth: 'UserPassword'
    userName: 'admin'
    # password: '$(BcContainerPassword)'   # empty = a random password is generated
    # licenseFile: '$(BcLicensePath)'
    # isolation: ''                         # empty = auto (Docker decides process/hyperv)
  # -> sets $(containerName), $(containerUsername), $(containerPassword) (secret)

Inputs

Option values

auth

isolation

Output variables

Note: If password is blank a random password is generated and exposed (secret) as $(containerPassword). memoryLimit (e.g. 8G) caps container memory. Requires a Docker engine on the agent.

---

Create BC Container User

Reference name: CreateBcContainerUser@0

Creates a Business Central user inside a container and assigns a permission set.

Note: Wraps New-BcContainerUser from the businessdev.ALbuild module.

Underlying cmdlet: New-BcContainerUser

Example

Code
- task: CreateBcContainerUser@0
  displayName: 'Create BC container user'
  inputs:
    containerName: '$(containerName)'
    userName: 'testuser'
    password: '$(BcTestUserPassword)'
    permissionSetId: 'SUPER'

Inputs

Note: Creates a user inside the container and assigns a permission set. userName / password default to the container admin credentials set by Create BC Container; permissionSetId defaults to SUPER. This task sets no output variables.

---

Create NuGet Package

Reference name: CreateNuGetPackage@0

Creates a NuGet package (.nupkg) from a compiled Business Central .app.

Note: Wraps New-BcNuGetPackage from the businessdev.ALbuild module. Packages each matched .app - a single file, every .app under a folder, or a wildcard - into a .nupkg (*.runtime.app is skipped; use the runtime-package flow for those). Sets the output variable (default 'bcNuGetPackage') to the first package and 'bcNuGetPackages' to all of them; feed those to the 'Publish NuGet Package' task.

Example

Code
- task: CreateNuGetPackage@0
  displayName: 'Create NuGet package'
  inputs:
    path: '$(bcAppFile)'                 # a .app file or a folder of .app files
    idScheme: '{publisher}.{name}.{id}'
    # packageId: 'MyCompany.MyApp'       # overrides idScheme with an explicit id
    # version: '$(appVersion)'           # empty = version from app.json
    outputFolder: '$(Build.ArtifactStagingDirectory)'
    outputVariable: 'bcNuGetPackage'
  # -> sets $(bcNuGetPackage) (first package) and $(bcNuGetPackages) (all, ';'-joined)

Inputs

Option values

idScheme

Output variables

Note: Wraps one or more .app files into NuGet packages. The package id comes from packageId when set, otherwise from idScheme (a template of {publisher}, {name}, {id}). version defaults to the app.json version. The primary output variable name is chosen with outputVariable; the plural bcNuGetPackages is always emitted as well.

---

Get BC Artifact

Reference name: GetBcArtifact@0

Resolves a Business Central artifact URL and stores it in an output variable.

Note: Wraps Find-BcArtifactUrl from the businessdev.ALbuild module.

Underlying cmdlet: Find-BcArtifactUrl

Example

Code
- task: GetBcArtifact@0
  displayName: 'Get BC artifact'
  inputs:
    type: 'Sandbox'          # empty = from albuild.json (default Sandbox)
    country: 'w1'            # empty = from albuild.json (default w1)
    select: 'Latest'
    # version: '26'          # optional version / prefix filter
  # -> sets $(bcArtifactUrl) and $(bcArtifactVersion) for the downstream tasks

Inputs

Option values

type

select

Output variables

Note: Set dependencyAware: true to down-select the artifact so the app's dependency closure stays resolvable; maxDowngradeSteps (visible only then) caps how many minor versions it may step down.

---

Get Universal Package

Reference name: GetUniversalPackage@0

Downloads a named package from an Azure DevOps Universal feed into a folder.

Note: Wraps Get-BcUniversalPackage from the businessdev.ALbuild module. Requires the Azure CLI with the azure-devops extension on the agent.

Underlying cmdlet: Get-BcUniversalPackage

Example

Code
- task: GetUniversalPackage@0
  displayName: 'Download universal package'
  inputs:
    feed: 'ALbuild'
    name: 'my-universal-package'
    version: '*'                 # '*' = latest version
    outputFolder: '$(Pipeline.Workspace)/pkg'
    # project: 'MyProject'       # for a project-scoped feed
    # organization / accessToken default to the current collection / $(System.AccessToken)

Inputs

Note: Downloads an Azure Artifacts Universal Package from the named feed into outputFolder. version accepts an exact version or * (latest). Set project for a project-scoped feed; organization and accessToken default to the running collection and the build service token. This task sets no output variables.

---

Import Configuration Package

Reference name: ImportConfigPackage@0

Imports a RapidStart (.rapidstart) configuration package into a Business Central container.

Note: Wraps Import-BcConfigurationPackage from the businessdev.ALbuild module.

Underlying cmdlet: Import-BcConfigurationPackage

Example

Code
- task: ImportConfigPackage@0
  displayName: 'Import configuration package'
  inputs:
    containerName: '$(containerName)'
    path: 'config/RapidStart.rapidstart'   # a .rapidstart configuration package

Inputs

Note: Imports and applies a RapidStart configuration package into the container (e.g. to seed setup/master data before tests). This task sets no output variables.

---

Install 365 App

Reference name: InstallBc365App@0

Installs one or more 365 business development apps into a Business Central container.

Note: Wraps Install-Bc365App from the businessdev.ALbuild module. Provide one app id per line.

Underlying cmdlet: Install-Bc365App

Example

Code
- task: InstallBc365App@0
  displayName: 'Install 365 business apps'
  inputs:
    containerName: '$(containerName)'
    appId: |                       # one app id per line
      63ca2fa4-4f03-4f2b-a480-172fef340d3f
      abcabc00-0000-0000-0000-000000000000
    # installerUrl: 'https://.../installer'   # optional custom installer source

Inputs

Note: Installs one or more 365 business development apps into the container by app id. The appId input is multi-line - provide one app id per line. installerUrl overrides the default installer source. This task sets no output variables.

---

Install Dependencies

Reference name: InstallDependencies@0

Installs an AL project's resolved dependency apps into the container, in dependency order.

Note: Wraps Install-BcContainerDependency from the businessdev.ALbuild module. Run after Resolve Dependencies and before publishing the built apps, so the app under test can be installed against its dependencies.

Example

Code
- task: InstallDependencies@0
  displayName: 'Install app dependencies into container'
  inputs:
    containerName: '$(containerName)'
    packageFolder: ''          # empty = the symbols cache resolved by Resolve Dependencies
    skipVerification: true

Inputs

Note: Publishes the resolved dependency .app files into the container so the app under test can be installed. packageFolder points at the folder holding the dependency packages (defaults to the resolved symbols cache); skipVerification (default true) skips app signature verification. This task sets no output variables.

---

Install Test Toolkit

Reference name: InstallTestToolkit@0

Publishes and installs the Business Central test toolkit apps into a container.

Note: Wraps Install-BcContainerTestToolkit from the businessdev.ALbuild module. Exports the installed toolkit .app symbols to a host folder and publishes it as the 'bcTestToolkitSymbols' pipeline variable, so a following AL Tool Compile AL App can resolve test-toolkit symbols (required for test apps on country 'w1').

Underlying cmdlet: Install-BcContainerTestToolkit

Example

Code
- task: InstallTestToolkit@0
  displayName: 'Install test toolkit'
  inputs:
    containerName: '$(containerName)'
    includeTestLibrariesOnly: true   # false = also install the full test framework apps
  # -> sets $(bcTestToolkitSymbols) with the exported test-symbol folder

Inputs

Output variables

Note: Installs Microsoft's test toolkit into the container. includeTestLibrariesOnly (default true) installs only the test libraries needed to compile/run tests; set false to install the complete test framework. symbolExportFolder overrides where the test symbols are exported.

---

Publish App

Reference name: PublishApp@0

Publishes, synchronises and installs an .app into a Business Central container.

Note: Wraps Publish-BcContainerApp from the businessdev.ALbuild module.

Underlying cmdlet: Publish-BcContainerApp

Example

Code
- task: PublishApp@0
  displayName: 'Publish AL app to container'
  inputs:
    containerName: '$(containerName)'
    appFile: '$(bcAppFile)'          # empty = publish every .app under appFolder
    syncMode: 'Add'
    install: true
    skipVerification: true

Inputs

Option values

syncMode

Note: Publishes into the container named by containerName (defaults to the $(containerName) set by Create BC Container). skipVerification (default true) skips app signature verification; install (default true) installs the app after publishing. This task sets no output variables.

---

Publish Testiny Results

Reference name: PublishTestinyResults@0

Publishes a JUnit test result file to Testiny.

Note: Wraps Publish-BcTestinyResult from the businessdev.ALbuild module. For standard pipeline reporting use the built-in PublishTestResults task.

Underlying cmdlet: Publish-BcTestinyResult

Example

Code
- task: PublishTestinyResults@0
  displayName: 'Publish results to Testiny'
  inputs:
    resultsFile: '$(bcTestResults)'    # defaults to TestResults.xml
    apiKey: '$(TestinyApiKey)'
    projectId: '$(TestinyProjectId)'
    # runId: '123'                     # optional: append to an existing run

Inputs

Note: Uploads the test results (JUnit XML, e.g. the $(bcTestResults) from Run Tests) to the Testiny test-management service for the given projectId. apiKey, resultsFile and projectId are required. runId targets an existing run; when omitted a new run is created. This task sets no output variables.

---

Remove BC Container

Reference name: RemoveBcContainer@0

Removes a Business Central build container.

Note: Wraps Remove-BcContainer from the businessdev.ALbuild module.

Underlying cmdlet: Remove-BcContainer

Example

Code
- task: RemoveBcContainer@0
  displayName: 'Remove BC container'
  condition: always()          # tear down even when earlier steps failed
  inputs:
    containerName: '$(containerName)'

Inputs

Note: Removes the BC container. Put this in a cleanup step with condition: always() so the container is torn down even when the build fails. This task sets no output variables.

---

Resolve Dependencies

Reference name: ResolveDependencies@0

Resolves an AL project's dependencies from NuGet feeds and writes them to .alpackages.

Note: Wraps Register-BcFeed + Resolve-BcDependencies from the businessdev.ALbuild module. NuGet feeds take precedence over the albuild.json Universal/local/URL packages: a dependency a registered feed offers is resolved from the feed, and those external packages are used only as a fallback for apps no feed provides.

Underlying cmdlet: Resolve-BcDependencies

Example

Code
- task: ResolveDependencies@0
  displayName: 'Resolve AL dependencies'
  inputs:
    feedUrl: 'https://pkgs.dev.azure.com/365businessdev/_packaging/ALbuild/nuget/v3/index.json'
    feedToken: '$(System.AccessToken)'
    feedKind: 'symbols'
    select: 'Latest'
    targetVersion: '$(bcArtifactVersion)'
    includeMicrosoftDefaults: true

Inputs

Option values

feedKind

select

Note: Restores dependencies from a NuGet feed into the symbols cache. targetVersion (default $(bcArtifactVersion) from Get BC Artifact) pins the BC platform the dependencies must match; includeMicrosoftDefaults (default true) also pulls the Microsoft first-party symbol packages. This task sets no output variables.

---

Run AL Tests

Reference name: RunBcTests@0

Runs AL tests in a Business Central container using ALbuild's built-in test runner and publishes a JUnit result file.

Note: Wraps Invoke-BcContainerTest from the businessdev.ALbuild module. Discovers AL test apps under the project folder (honouring each app's pipeline.config alTestRunnerId) or runs an explicit extension id.

Underlying cmdlet: Invoke-BcContainerTest

Example

Code
- task: RunBcTests@0
  displayName: 'Run AL tests'
  inputs:
    containerName: '$(containerName)'
    testSuite: 'DEFAULT'
    failOnTestFailure: true
    codeCoverage: 'PerRun'
    coverageFormats: 'Cobertura,Markdown'
    publishCoverage: true
    minLineCoverage: '80'          # fail the build below 80% line coverage
    failOnCoverageBelow: true
  # -> sets $(bcTestResults), $(bcCoverageLineRate), $(bcCoverageCobertura), $(bcTestQualityScore)

Inputs

Option values

codeCoverage

codeCoverageMap

coverageFormats

Output variables

Note: The coverageFormats input is a comma-separated list; valid entries are Cobertura, Markdown and ALbuildJson. minLineCoverage / minObjectLineCoverage set coverage thresholds; combined with failOnCoverageBelow (default true) they fail the build when coverage is below target. checkTestQuality additionally warns about tests without assertions.

---

Sign AL App

Reference name: SignBcApp@0

Signs .app files with an Azure Key Vault certificate (AzureSignTool).

Note: Wraps Invoke-BcAppSigning from the businessdev.ALbuild module. AzureSignTool must be available on the agent. NOTE: Azure DevOps does not pass secret pipeline variables into task inputs. If your Key Vault credentials are secret variables, map them via the task 'env:' block instead of inputs: ALBUILD_SIGN_KEYVAULTURL, ALBUILD_SIGN_TENANTID, ALBUILD_SIGN_CLIENTID, ALBUILD_SIGN_CLIENTSECRET, ALBUILD_SIGN_CERTNAME.

Underlying cmdlet: Invoke-BcAppSigning

Example

Code
- task: SignBcApp@0
  displayName: 'Sign AL app'
  inputs:
    path: '$(bcAppFile)'                 # a .app file or a folder of .app files
    certificateName: '$(SigningCertName)'
  env:
    # Secret pipeline variables do not reach task inputs, so map them via env (SignBcApp reads ALBUILD_SIGN_*):
    ALBUILD_SIGN_KEYVAULTURL: $(SigningAzureKeyVaultUrl)
    ALBUILD_SIGN_TENANTID:    $(SigningAzureKeyVaultTenantId)
    ALBUILD_SIGN_CLIENTID:    $(SigningAzureKeyVaultClientId)
    ALBUILD_SIGN_CLIENTSECRET: $(SigningAzureKeyVaultClientSecret)
    ALBUILD_SIGN_CERTNAME:    $(SigningCertName)

Inputs

Note: Azure DevOps does not pass secret variables to task inputs, so the Key Vault credentials are read from the ALBUILD_SIGN_KEYVAULTURL / _TENANTID / _CLIENTID / _CLIENTSECRET / _CERTNAME environment variables when the matching inputs are blank. Signs via Azure Key Vault (AzureSignTool); the certificate must be a code-signing cert. timestampUrl defaults to http://timestamp.digicert.com.

---

Stamp Build Version

Reference name: StampBuildVersion@0

Stamps the app version into app.json and atomically claims a build/<version> branch (parallel-safe).

Note: Wraps Invoke-BcBuildVersionStamp from the businessdev.ALbuild module. Uses a branch-push compare-and-swap so concurrent builds never share a version.

Underlying cmdlet: Invoke-BcBuildVersionStamp

Example

Code
# CI: version app.json from its current Major.Minor, Build+1, Revision 0, and claim a build/<version>
# branch so the CD build can seed the exact validated version later.
- task: StampBuildVersion@0
  displayName: 'Stamp build version'
  inputs:
    schema: 'major.minor.increment.0'
    # version: '1.2.3.0'          # an explicit version overrides schema entirely
    # onlyUpdateOnChangedSource: true
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)   # required to push the build/<version> branch

# CD: inherit Major.Minor.Build from the latest CI build branch, set Revision = build id.
- task: StampBuildVersion@0
  inputs:
    schema: 'latest.latest.latest.build-id'       # 'latest' auto-enables Seed from build branch
    noBuildBranch: true
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)

Inputs

Option values

schema

Output variables

Note: A schema with fewer than four positions keeps the remaining lower components unchanged (implicit latest). Any token other than those above fails the build. When the schema contains a latest token, or when seedFromBuildBranch is set, the task reads the highest existing build/<Major>.<Minor>.* branch on the remote as the base before applying the schema; the build/<version> branch push is a compare-and-swap (Build is incremented on conflict). Pushing the branch needs the build service to have Contribute on the repo (map $(System.AccessToken) to AZURE_DEVOPS_EXT_PAT).

---