Build AL project - albuild

Applies to: AL Language extension 17.0 and later | Available in: Visual Studio Code, AL MCP Server

The al_build tool compiles AL source code and generates a deployable .app package. It supports building a single project or the entire workspace including the full dependency tree, and returns detailed diagnostics on completion.

Use al_build when you need the .app file—for example, before publishing. If you only need to validate your code without producing an output package, use al_compile (AL MCP only), which is faster.

Parameters

Visual Studio Code

ParameterTypeDefaultDescription
scope"current" | "all""current""current" builds the active project only. "all" builds the entire workspace in dependency order, producing one .app per project.

AL MCP Server

ParameterTypeDefaultRequiredDescription
scope"current" | "all""current"No"current" builds the active project; "all" builds the full workspace in dependency order.
projectPathstringFirst project in workspaceNoAbsolute path to the AL project folder that contains app.json. Required when the workspace contains multiple projects and you want to build a specific one.
outputPathstringProject output folderNoDestination directory for the generated .app file. If omitted, the default output directory configured in app.json is used.
onlyErrorsbooleanfalseNoWhen true, only error-severity diagnostics are returned. Warnings, informational messages, and hints are suppressed.
maxDiagnosticsinteger100NoMaximum number of diagnostics to return. Use a higher value if you expect a large number of issues.
enableCodeAnalysisboolean(server default)NoEnable AL code analyzers during the build. When enabled, the analyzers specified in codeAnalyzers are run.
codeAnalyzersstring[](server default)NoList of code analyzers to run. Supported values: ${CodeCop}, ${AppSourceCop}, ${PerTenantExtensionCop}, ${UICop}.

Return value

On success, the tool creates the .app file in the output directory and returns a result that includes:

  • A success indicator.
  • A list of diagnostics (errors, warnings, and so on) up to maxDiagnostics.

On failure, the tool returns a list of diagnostics describing what prevented the build from completing.

Note

The .app file is only created when the build succeeds with no errors. A build that produces warnings still generates the .app file.

Prerequisites

  • The AL project folder must contain a valid app.json file.
  • Required symbol packages must be available in the .alpackages folder. If they're missing, run al_downloadsymbols first.

Examples

Build the active project (Visual Studio Code or AL MCP)

{
  "scope": "current"
}

Build all projects in the workspace

{
  "scope": "all"
}

Build with code analysis and error-only output (AL MCP)

{
  "scope": "current",
  "onlyErrors": true,
  "enableCodeAnalysis": true,
  "codeAnalyzers": ["${CodeCop}", "${AppSourceCop}"]
}

Build a specific project to a custom output path (AL MCP)

{
  "projectPath": "C:/repos/MyExtension",
  "outputPath": "C:/build/output"
}

Suggested next steps

OutcomeSuggested action
Build succeededCall al_publish to deploy the extension to Business Central.
Build failed with diagnosticsCall al_getdiagnostics for the full diagnostic list, fix the reported issues, and rebuild.
Symbols not foundCall al_downloadsymbols and then retry.

AI agent tools overview
AL MCP Server reference