Publish AL extension to Business Central - alpublish

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

The 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.

Deployment modes

ModeDescription
Full publishBuilds the project and publishes the resulting .app file. This is the default mode.
Incremental (RAD) publishUses 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.
Full dependency treeBuilds and publishes the active project together with all its dependencies in the correct order.
Skip buildPublishes an existing .app file without rebuilding the project. Useful when the build has already been performed in a previous step.

Authentication

For cloud environments, the tool uses browser-based interactive authentication via Microsoft Authentication Library (MSAL). Tokens are cached and reused across calls.

  • In AL MCP, call al_auth_login before publishing to a cloud environment.
  • For on-premises environments using Windows authentication, no explicit sign in is required.
  • Pass noCache: true to force a new sign-in and bypass the token cache.

Parameters

Visual Studio Code

ParameterTypeDefaultDescription
debugbooleantrueWhen true, a debug session is started automatically after the publish completes.
type"full" | "incremental""full"The publish type. "incremental" uses RAD delta compilation for faster iterative publishing.
fulldependencytreebooleanfalseWhen true, all project dependencies are built and published in dependency order before the active project.
skipbuildbooleanfalseWhen true, the build step is skipped and the existing .app file is published directly.

AL MCP Server

App source — provide one of the following:

ParameterTypeDescription
appPathstringAbsolute path to an existing .app file to publish.
projectPathstringAbsolute path to an AL project folder. The tool builds the project and publishes the resulting .app. Defaults to the first project in the workspace.

Cloud environment options:

ParameterTypeDefaultDescription
environmentNamestring—The name of the cloud environment (for example, "sandbox" or "production").
environmentTypestring—"Sandbox" or "Production".
tenantstring—The Microsoft Entra tenant ID or domain (for example, "contoso.onmicrosoft.com").

On-premises options:

ParameterTypeDefaultDescription
serverUrlstring—The Business Central server URL (for example, "http://myserver").
serverInstancestring—The server instance name (for example, "BC").
portinteger—The development service port.
authenticationstring"AAD"Authentication method: "AAD", "Windows", or "UserPassword".

Deployment options:

ParameterTypeDefaultDescription
schemaUpdateModestring"Synchronize"How to handle database schema changes: "Synchronize", "ForceSync", or "Recreate".
forceUpgradebooleanfalseWhen true, skips the version compatibility check and forces the upgrade.
skipBuildbooleanfalseWhen true, publishes an existing .app without building.
buildDependenciesbooleanfalseWhen true, builds and publishes all project dependencies before the active project.
useInteractiveLoginbooleantrueWhen true, opens a browser window for Microsoft Entra ID sign-in if authentication is required.
noCachebooleanfalseWhen true, clears cached tokens and forces a new sign-in before publishing.

Examples

Publish the active project to a sandbox (Visual Studio Code)

In Copilot Chat, say: "Publish my extension to the sandbox."

Copilot calls al_publish with the default parameters. Connection details come from launch.json.

Publish with full dependency tree (Visual Studio Code)

{
  "fulldependencytree": true,
  "debug": false
}

Publish an existing .app to a cloud sandbox (AL MCP)

{
  "appPath": "C:/build/output/MyExtension_1.0.0.0.app",
  "environmentName": "sandbox",
  "environmentType": "Sandbox",
  "tenant": "contoso.onmicrosoft.com",
  "skipBuild": true
}

Publish to an on-premises server with Windows authentication (AL MCP)

{
  "projectPath": "C:/repos/MyExtension",
  "serverUrl": "http://myserver",
  "serverInstance": "BC",
  "port": 7049,
  "authentication": "Windows"
}

Force schema re-creation (AL MCP)

{
  "projectPath": "C:/repos/MyExtension",
  "environmentName": "sandbox",
  "schemaUpdateMode": "Recreate"
}

Suggested next steps

OutcomeSuggested action
Published successfullyIn Visual Studio Code, the debugger attaches automatically (when debug: true). In AL MCP, verify the deployment on the BC server.
Build error before publishRun al_getdiagnostics to review the errors, fix the code, and retry.
Authentication errorRun al_auth_login (AL MCP) and retry, or set noCache: true.
  • al_build — Build without publishing.
  • al_downloadsymbols — Download symbol packages needed before publishing.
  • al_auth_login — Authenticate to Microsoft Entra ID before publishing to the cloud.
  • al_debug — Attach the debugger without republishing (Visual Studio Code only).

AI agent tools overview
AL MCP Server reference