{"title":"Build AL project - albuild","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/al-agent-tools/al-tool-build/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/al-agent-tools/al-tool-build, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/al-agent-tools/al-tool-build","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn about the al_build tool available for AL development, including how to use it in Visual Studio Code with GitHub Copilot and through the AL MCP Server for headless environments and CI/CD pipelines.","date":"2026-10-02","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Build AL project - al_build","slug":"build-al-project---al_build","at":0,"chars":4072},{"level":2,"title":"Parameters","slug":"parameters","at":575,"chars":1418},{"level":3,"title":"Visual Studio Code","slug":"visual-studio-code","at":589,"chars":234},{"level":3,"title":"AL MCP Server","slug":"al-mcp-server","at":823,"chars":1170},{"level":2,"title":"Return value","slug":"return-value","at":1993,"chars":467},{"level":2,"title":"Prerequisites","slug":"prerequisites","at":2460,"chars":225},{"level":2,"title":"Examples","slug":"examples","at":2685,"chars":538},{"level":3,"title":"Build the active project (Visual Studio Code or AL MCP)","slug":"build-the-active-project-visual-studio-code-or-al-mcp","at":2697,"chars":97},{"level":3,"title":"Build all projects in the workspace","slug":"build-all-projects-in-the-workspace","at":2794,"chars":73},{"level":3,"title":"Build with code analysis and error-only output (AL MCP)","slug":"build-with-code-analysis-and-error-only-output-al-mcp","at":2867,"chars":203},{"level":3,"title":"Build a specific project to a custom output path (AL MCP)","slug":"build-a-specific-project-to-a-custom-output-path-al-mcp","at":3070,"chars":153},{"level":2,"title":"Suggested next steps","slug":"suggested-next-steps","at":3223,"chars":373},{"level":2,"title":"Related tools","slug":"related-tools","at":3596,"chars":366},{"level":2,"title":"Related information","slug":"related-information","at":3962,"chars":110}],"text":"# Build AL project - al_build\nApplies to: AL Language extension 17.0 and later | Available in: Visual Studio Code, AL MCP Server\nThe 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.\nUse 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-tool-compile> (AL MCP only), which is faster.\n## Parameters\n### Visual Studio Code\nParameter|Type|Default|Description\nscope|`\"current\"` \\| `\"all\"`|`\"current\"`|`\"current\"` builds the active project only. `\"all\"` builds the entire workspace in dependency order, producing one `.app` per project.\n### AL MCP Server\nParameter|Type|Default|Required|Description\nscope|`\"current\"` \\| `\"all\"`|`\"current\"`|No|`\"current\"` builds the active project; `\"all\"` builds the full workspace in dependency order.\nprojectPath|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.\noutputPath|string|Project output folder|No|Destination directory for the generated `.app` file. If omitted, the default output directory configured in app.json is used.\nonlyErrors|boolean|false|No|When true, only error-severity diagnostics are returned. Warnings, informational messages, and hints are suppressed.\nmaxDiagnostics|integer|`100`|No|Maximum number of diagnostics to return. Use a higher value if you expect a large number of issues.\nenableCodeAnalysis|boolean|(server default)|No|Enable AL code analyzers during the build. When enabled, the analyzers specified in codeAnalyzers are run.\ncodeAnalyzers|string[]|(server default)|No|List of code analyzers to run. Supported values: `${CodeCop}`, `${AppSourceCop}`, `${PerTenantExtensionCop}`, `${UICop}`.\n## Return value\nOn success, the tool creates the `.app` file in the output directory and returns a result that includes:\n A success indicator.\n A list of diagnostics (errors, warnings, and so on) up to maxDiagnostics.\nOn failure, the tool returns a list of diagnostics describing what prevented the build from completing.\n> NOTE\n> The `.app` file is only created when the build succeeds with no errors. A build that produces warnings still generates the `.app` file.\n## Prerequisites\n The AL project folder must contain a valid app.json file.\n Required symbol packages must be available in the `.alpackages` folder. If they're missing, run al_downloadsymbols<al-tool-download-symbols> first.\n## Examples\n### Build the active project (Visual Studio Code or AL MCP)\n```json\n{\n  \"scope\": \"current\"\n}\n```\n### Build all projects in the workspace\n```json\n{\n  \"scope\": \"all\"\n}\n```\n### Build with code analysis and error-only output (AL MCP)\n```json\n{\n  \"scope\": \"current\",\n  \"onlyErrors\": true,\n  \"enableCodeAnalysis\": true,\n  \"codeAnalyzers\": [\"${CodeCop}\", \"${AppSourceCop}\"]\n}\n```\n### Build a specific project to a custom output path (AL MCP)\n```json\n{\n  \"projectPath\": \"C:/repos/MyExtension\",\n  \"outputPath\": \"C:/build/output\"\n}\n```\n## Suggested next steps\nOutcome|Suggested action\nBuild succeeded|Call al_publish<al-tool-publish> to deploy the extension to Business Central.\nBuild failed with diagnostics|Call al_getdiagnostics<al-tool-get-diagnostics> for the full diagnostic list, fix the reported issues, and rebuild.\nSymbols not found|Call al_downloadsymbols<al-tool-download-symbols> and then retry.\n## Related tools\n al_compile<al-tool-compile> - Validate code without generating an `.app` (AL MCP only, faster).\n al_downloadsymbols<al-tool-download-symbols> - Download symbol packages before building.\n al_getdiagnostics<al-tool-get-diagnostics> - Read errors and warnings after a build.\n al_publish<al-tool-publish> - Deploy the built `.app` to Business Central.\n## Related information\nAI agent tools overview<al-agent-tools-overview>\nAL MCP Server reference<al-mcp-server>"}