How to Publish and Install Extensions in Business Central

Getting an AL extension from your local machine into a Business Central environment involves several distinct steps: compiling the code, publishing to a target environment, and then installing the extension for the tenant. Understanding the difference between these steps, and where things can go wrong, will save you time during development and deployment.

Prerequisites

Visual Studio Code with the AL Language extension installed
An AL extension project with a valid app.json
A Business Central sandbox or on-premises environment to publish to
launch.json configured with correct server details (covered in step 2)

Steps

1. Configure app.json

Before publishing, confirm that app.json contains the required fields. The id must be a unique GUID that identifies your extension permanently, do not regenerate it after initial creation.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Extension",
  "publisher": "My Company",
  "version": "1.0.0.0",
  "brief": "Short description of the extension",
  "description": "",
  "privacyStatement": "",
  "EULA": "",
  "help": "",
  "url": "",
  "logo": "",
  "dependencies": [
    {
      "id": "63ca2fa4-4f03-4f2b-a480-172fef2d5b05",
      "name": "System Application",
      "publisher": "Microsoft",
      "version": "24.0.0.0"
    }
  ],
  "screenshots": [],
  "platform": "24.0.0.0",
  "application": "24.0.0.0",
  "idRanges": [
    {
      "from": 50000,
      "to": 50099
    }
  ],
  "runtime": "13.0"
}

The version field follows a four-part format: major.minor.build.revision. Increment the version before each publish when deploying to production.

2. Configure launch.json

launch.json tells VS Code which environment to publish to when you press F5. It lives in the .vscode folder of your project.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "My Sandbox",
      "request": "launch",
      "type": "al",
      "environmentType": "Sandbox",
      "environmentName": "MySandbox",
      "startupObjectId": 22,
      "startupObjectType": "Page",
      "breakOnError": "All",
      "launchBrowser": true,
      "authentication": "UserPassword",
      "tenant": "mytenant.onmicrosoft.com"
    }
  ]
}

For a local Business Central Docker container or on-premises server, use "environmentType": "OnPrem" and add a "server" and "serverInstance" field:

{
  "name": "Local BC",
  "request": "launch",
  "type": "al",
  "environmentType": "OnPrem",
  "server": "http://localhost",
  "serverInstance": "BC",
  "authentication": "Windows",
  "startupObjectId": 22,
  "startupObjectType": "Page",
  "breakOnError": "All"
}

3. Compile the extension

Press Ctrl + Shift + B to compile (build) the extension. This produces a .app file in your project root.

If compilation fails, the Problems panel at the bottom of VS Code will list the errors with file names and line numbers. Fix all errors before proceeding.

You can also run the compiler from the command line:

alc.exe /project:"C:\MyExtension" /packagecachepath:"C:\MyExtension\.alpackages"

The path to alc.exe is inside the AL Language extension folder under your VS Code extensions directory.

4. Publish to a sandbox with F5

Press F5 to publish and launch. VS Code will:

Compile the extension if not already compiled
Upload the .app file to the target environment defined in launch.json
Install the extension for your user
Open a browser to the startupObjectId page

Use Ctrl + F5 (Publish without debugging) if you do not need the AL debugger attached. This is faster for quick iterations.

Publish (via F5) installs the extension for your development user only in the sandbox. It does not make the extension available to all users in the tenant.

5. Understand the difference between Publish and Deploy

Action	What it does	Who can use it
Publish (F5 / Ctrl+F5)	Uploads and installs for dev user in sandbox	Dev user only
Deploy (via Admin Center or Extension Management)	Installs for all users in the tenant	All tenant users
Upload .app (Extension Management)	Installs a per-tenant extension from a file	All tenant users

For production deployments you never use F5. You build the .app file, then either upload it through Extension Management or deploy it via the Business Central Admin Center.

6. Install an extension via Extension Management

To install an extension for all users in a tenant from a .app file:

Search for Extension Management using Alt + Q.
Select Manage → Upload Extension.
Choose the .app file and select Deploy.
Set the Language and confirm.

Business Central will validate the extension (dependency checks, ID range conflicts) before installing. If validation fails, you will see an error with a reason code.

7. Understand per-tenant extensions vs AppSource apps

Per-tenant extensions (PTE) are .app files you upload directly to a specific tenant. They are not reviewed by Microsoft and are tied to that tenant.

AppSource apps go through Microsoft’s validation process and can be installed by any tenant from the marketplace.

For most internal or customer-specific development, per-tenant extensions are the standard approach. AppSource is relevant when you are building a product to sell to multiple customers.

8. Uninstall and undeploy an extension

Search for Extension Management using Alt + Q.
Find your extension in the list.
Select the three-dot menu (More Options) next to the extension.
Choose Uninstall to remove it from the tenant but keep the data.
Choose Unpublish to fully remove the extension and its schema.

Uninstalling does not delete table data by default. Unpublishing removes the extension’s tables from the schema, which means data in those tables is lost unless you back it up first.

Common Mistakes

Regenerating the id GUID in app.json after the extension is already published, Business Central treats this as a new extension and will not upgrade the old one.
Forgetting to increment the version before uploading, Business Central rejects an upload if the version matches an already-installed version.
Using F5 for production deployments, always use Extension Management or the Admin Center for production.

Next Steps

With your extension deployed, writing automated tests is the next step to keeping your code reliable. See How to Write and Run AL Unit Tests in Business Central for a practical introduction to AL unit testing.