Edit

Build AL project - al_build

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

Parameter Type Default Description
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

Parameter Type Default Required Description
scope "current" | "all" "current" No "current" builds the active project; "all" builds the full workspace in dependency order.
projectPath string First project in workspace No Absolute 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.
outputPath string Project output folder No Destination directory for the generated .app file. If omitted, the default output directory configured in app.json is used.
onlyErrors boolean false No When true, only error-severity diagnostics are returned. Warnings, informational messages, and hints are suppressed.
maxDiagnostics integer 100 No Maximum number of diagnostics to return. Use a higher value if you expect a large number of issues.
enableCodeAnalysis boolean (server default) No Enable AL code analyzers during the build. When enabled, the analyzers specified in codeAnalyzers are run.
codeAnalyzers string[] (server default) No List 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

Outcome Suggested action
Build succeeded Call al_publish to deploy the extension to Business Central.
Build failed with diagnostics Call al_getdiagnostics for the full diagnostic list, fix the reported issues, and rebuild.
Symbols not found Call al_downloadsymbols and then retry.

AI agent tools overview
AL MCP Server reference

  • Last updated on