{"title":"Publish AL extension to Business Central - alpublish","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/al-agent-tools/al-tool-publish/","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-publish, 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-publish","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_publish 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":"Publish AL extension to Business Central - al_publish","slug":"publish-al-extension-to-business-central---al_publish","at":0,"chars":5650},{"level":2,"title":"Deployment modes","slug":"deployment-modes","at":381,"chars":614},{"level":2,"title":"Authentication","slug":"authentication","at":995,"chars":452},{"level":2,"title":"Parameters","slug":"parameters","at":1447,"chars":2274},{"level":3,"title":"Visual Studio Code","slug":"visual-studio-code","at":1461,"chars":547},{"level":3,"title":"AL MCP Server","slug":"al-mcp-server","at":2008,"chars":1713},{"level":2,"title":"Examples","slug":"examples","at":3721,"chars":1007},{"level":3,"title":"Publish the active project to a sandbox (Visual Studio Code)","slug":"publish-the-active-project-to-a-sandbox-visual-studio-code","at":3733,"chars":222},{"level":3,"title":"Publish with full dependency tree (Visual Studio Code)","slug":"publish-with-full-dependency-tree-visual-studio-code","at":3955,"chars":122},{"level":3,"title":"Publish an existing `.app` to a cloud sandbox (AL MCP)","slug":"publish-an-existing-app-to-a-cloud-sandbox-al-mcp","at":4077,"chars":254},{"level":3,"title":"Publish to an on-premises server with Windows authentication (AL MCP)","slug":"publish-to-an-on-premises-server-with-windows-authentication-al-mcp","at":4331,"chars":237},{"level":3,"title":"Force schema re-creation (AL MCP)","slug":"force-schema-re-creation-al-mcp","at":4568,"chars":160},{"level":2,"title":"Suggested next steps","slug":"suggested-next-steps","at":4728,"chars":436},{"level":2,"title":"Related tools","slug":"related-tools","at":5164,"chars":376},{"level":2,"title":"Related information","slug":"related-information","at":5540,"chars":110}],"text":"# Publish AL extension to Business Central - al_publish\nApplies to: AL Language extension 17.0 and later | Available in: Visual Studio Code, AL MCP Server\nThe al_publish tool deploys an AL extension to a Business Central environment-either a cloud (SaaS) sandbox or production environment, or an on-premises server. It supports several deployment modes depending on your workflow.\n## Deployment modes\nMode|Description\nFull publish|Builds the project and publishes the resulting `.app` file. This is the default mode.\nIncremental (RAD) publish|Uses Rapid Application Development (RAD) delta compilation to publish only the changes since the last full publish. Faster for iterative development. Available in Visual Studio Code only.\nFull dependency tree|Builds and publishes the active project together with all its dependencies in the correct order.\nSkip build|Publishes an existing `.app` file without rebuilding the project. Useful when the build has already been performed in a previous step.\n## Authentication\nFor cloud environments, the tool uses browser-based interactive authentication via Microsoft Authentication Library (MSAL). Tokens are cached and reused across calls.\n In AL MCP, call al_auth_login<al-tool-auth#al_auth_login> before publishing to a cloud environment.\n For on-premises environments using Windows authentication, no explicit sign in is required.\n Pass `noCache: true` to force a new sign-in and bypass the token cache.\n## Parameters\n### Visual Studio Code\nParameter|Type|Default|Description\ndebug|boolean|true|When true, a debug session is started automatically after the publish completes.\ntype|`\"full\"` \\| `\"incremental\"`|`\"full\"`|The publish type. `\"incremental\"` uses RAD delta compilation for faster iterative publishing.\nfulldependencytree|boolean|false|When true, all project dependencies are built and published in dependency order before the active project.\nskipbuild|boolean|false|When true, the build step is skipped and the existing `.app` file is published directly.\n### AL MCP Server\nApp source - provide one of the following:\nParameter|Type|Description\nappPath|string|Absolute path to an existing `.app` file to publish.\nprojectPath|string|Absolute path to an AL project folder. The tool builds the project and publishes the resulting `.app`. Defaults to the first project in the workspace.\nCloud environment options:\nParameter|Type|Default|Description\nenvironmentName|string|-|The name of the cloud environment (for example, `\"sandbox\"` or `\"production\"`).\nenvironmentType|string|-|`\"Sandbox\"` or `\"Production\"`.\ntenant|string|-|The Microsoft Entra tenant ID or domain (for example, `\"contoso.onmicrosoft.com\"`).\nOn-premises options:\nParameter|Type|Default|Description\nserverUrl|string|-|The Business Central server URL (for example, `\"http://myserver\"`).\nserverInstance|string|-|The server instance name (for example, `\"BC\"`).\nport|integer|-|The development service port.\nauthentication|string|`\"AAD\"`|Authentication method: `\"AAD\"`, `\"Windows\"`, or `\"UserPassword\"`.\nDeployment options:\nParameter|Type|Default|Description\nschemaUpdateMode|string|`\"Synchronize\"`|How to handle database schema changes: `\"Synchronize\"`, `\"ForceSync\"`, or `\"Recreate\"`.\nforceUpgrade|boolean|false|When true, skips the version compatibility check and forces the upgrade.\nskipBuild|boolean|false|When true, publishes an existing `.app` without building.\nbuildDependencies|boolean|false|When true, builds and publishes all project dependencies before the active project.\nuseInteractiveLogin|boolean|true|When true, opens a browser window for Microsoft Entra ID sign-in if authentication is required.\nnoCache|boolean|false|When true, clears cached tokens and forces a new sign-in before publishing.\n## Examples\n### Publish the active project to a sandbox (Visual Studio Code)\nIn Copilot Chat, say: \"Publish my extension to the sandbox.\"\nCopilot calls al_publish with the default parameters. Connection details come from launch.json.\n### Publish with full dependency tree (Visual Studio Code)\n```json\n{\n  \"fulldependencytree\": true,\n  \"debug\": false\n}\n```\n### Publish an existing `.app` to a cloud sandbox (AL MCP)\n```json\n{\n  \"appPath\": \"C:/build/output/MyExtension_1.0.0.0.app\",\n  \"environmentName\": \"sandbox\",\n  \"environmentType\": \"Sandbox\",\n  \"tenant\": \"contoso.onmicrosoft.com\",\n  \"skipBuild\": true\n}\n```\n### Publish to an on-premises server with Windows authentication (AL MCP)\n```json\n{\n  \"projectPath\": \"C:/repos/MyExtension\",\n  \"serverUrl\": \"http://myserver\",\n  \"serverInstance\": \"BC\",\n  \"port\": 7049,\n  \"authentication\": \"Windows\"\n}\n```\n### Force schema re-creation (AL MCP)\n```json\n{\n  \"projectPath\": \"C:/repos/MyExtension\",\n  \"environmentName\": \"sandbox\",\n  \"schemaUpdateMode\": \"Recreate\"\n}\n```\n## Suggested next steps\nOutcome|Suggested action\nPublished successfully|In Visual Studio Code, the debugger attaches automatically (when `debug: true`). In AL MCP, verify the deployment on the BC server.\nBuild error before publish|Run al_getdiagnostics<al-tool-get-diagnostics> to review the errors, fix the code, and retry.\nAuthentication error|Run al_auth_login<al-tool-auth#al_auth_login> (AL MCP) and retry, or set `noCache: true`.\n## Related tools\n al_build<al-tool-build> - Build without publishing.\n al_downloadsymbols<al-tool-download-symbols> - Download symbol packages needed before publishing.\n al_auth_login<al-tool-auth#al_auth_login> - Authenticate to Microsoft Entra ID before publishing to the cloud.\n al_debug<al-tool-debug> - Attach the debugger without republishing (Visual Studio Code only).\n## Related information\nAI agent tools overview<al-agent-tools-overview>\nAL MCP Server reference<al-mcp-server>"}