Launch.json, the gatekeeper to Business Central Development

Another installment in the Beginning AL series. This time I take a closer look at the launch.json file and explain what’s going on in that. If you’re new to BC development this is for you, check it out:

https://youtu.be/EqPFRx85fxs

In this video, Erik walks through the launch.json file — the essential configuration file that controls how your Visual Studio Code AL project connects to Business Central. Whether you’re targeting a cloud sandbox, an on-premises server, or even a production environment for snapshot debugging, launch.json is your gateway. Erik breaks down each field, demonstrates multiple configurations, and explains the different request types: launch, attach, and snapshot debugging.

What is launch.json?

launch.json is the file that describes how you connect to any type of Business Central environment. It defines your connection to the world — it defines how you see Business Central. Every time you create a new AL project in Visual Studio Code, this file is generated for you, but understanding what’s inside it is critical for productive development.

Creating a New Project

It all starts with an empty Visual Studio Code window. Using the command palette, you execute the AL: Go! command, specify a folder (which will be created if it doesn’t exist), and choose a target platform — in this case, version 19. The compiler then asks you to choose your server type, with two options:

  • Microsoft cloud sandbox
  • Your own server (on-premises)

This choice populates your launch.json with an initial configuration profile. The project also generates an app.json that defines your extension’s metadata:

{
  "id": "6d4fa577-709c-42fd-943d-c3373277dd3d",
  "name": "LaunchJson",
  "publisher": "Default publisher",
  "version": "1.0.0.0",
  "brief": "",
  "description": "",
  "privacyStatement": "",
  "EULA": "",
  "help": "",
  "url": "",
  "logo": "",
  "dependencies": [],
  "screenshots": [],
  "platform": "1.0.0.0",
  "application": "19.0.0.0",
  "idRanges": [
    {
      "from": 50100,
      "to": 50149
    }
  ],
  "resourceExposurePolicy": {
    "allowDebugging": true,
    "allowDownloadingSource": false,
    "includeSourceInSymbolFile": false
  },
  "runtime": "8.0"
}

And a simple AL file to get you started:

pageextension 50102 CustomerListExt extends "Customer List"
{
    trigger OnOpenPage();
    begin
        Message('App published: Hello world');
    end;
}

Anatomy of a Cloud Sandbox Configuration

When you choose “Microsoft cloud sandbox,” you get a JSON file with a version number (which has no real impact — just ignore it) and an array of configurations. Let’s walk through the key fields:

The “type” Field

The most important field to start with is type. Since Visual Studio Code can handle C#/.NET projects, Node projects, PHP projects, and all sorts of other things, the launch configuration needs to know that this one is actually an AL launch. This is set to "al".

The “name” Field

The name field is displayed on your screen whenever you interact with configurations — when downloading symbols, publishing, or selecting a debug target. The default “Microsoft cloud sandbox” isn’t very descriptive, especially when you have multiple configurations. Erik recommends using meaningful names that identify the specific environment, such as including the tenant and sandbox name.

The “environmentType” Field

This tells VS Code what kind of environment you’re connecting to. The options are:

  • Sandbox — for cloud sandbox environments
  • OnPrem — for on-premises servers
  • Production — for production environments (but you cannot deploy to production — this is only used for snapshot debugging)

The “environmentName” and “tenant” Fields

For cloud sandbox connections, you specify the environmentName (the name of your sandbox as it appears in Business Central) and the tenant. Erik strongly recommends always including the tenant ID, especially if you’re a partner with delegated admin access to multiple customer systems. You can use either the GUID or the .onmicrosoft.com domain format.

A cloud sandbox configuration looks something like this:

{
    "type": "al",
    "request": "launch",
    "name": "Sandbox ACS",
    "environmentType": "Sandbox",
    "environmentName": "acs",
    "tenant": "your-tenant-id-here",
    "startupObjectId": 22,
    "startupObjectType": "Page",
    "breakOnError": "All",
    "launchBrowser": true,
    "enableLongRunningSqlStatements": true,
    "enableSqlInformationDebugger": true
}

Adding an On-Premises Configuration

You can have more than one configuration in your launch.json. Using the Add Configuration button, you can select from various templates — including AL-specific ones for cloud sandbox and on-premises servers. The available templates depend on which extensions you have installed.

An on-premises configuration requires different connection details:

{
    "type": "al",
    "request": "launch",
    "name": "Docker BC19",
    "environmentType": "OnPrem",
    "server": "http://bc19",
    "serverInstance": "BC",
    "authentication": "UserPassword",
    "startupObjectId": 22,
    "startupObjectType": "Page",
    "breakOnError": "All"
}

Instead of environmentName and tenant, you now specify:

  • server — the hostname of your on-premises server
  • serverInstance — the Business Central server instance name
  • authentication — the authentication method (UserPassword, Windows, or AAD)

Working with Multiple Configurations

Once you have more than one configuration, VS Code will prompt you to choose which one to use whenever you download symbols, publish, or start debugging. The configuration names you set become very important here — they appear in:

  • The symbol download dialog
  • The publish/deploy dialog
  • The debugger dropdown in the Run and Debug panel
  • The status bar at the bottom of VS Code

One quirk Erik points out: when you hit F5 to publish, you may get the configuration choice dialog twice — once when it checks for the latest symbols and again when it actually deploys. This is a known oddity in the workflow.

Also note that when you download symbols from multiple configurations, you may end up with duplicate symbol files (since environments might be on slightly different versions). The AL compiler will grab the newest one, but you should clean up old symbol files periodically.

Startup Object Settings

Three fields control what happens when you launch the browser:

  • startupObjectType — the type of object to open (Page, Query, Report, or Table)
  • startupObjectId — the object number to load
  • launchBrowser — whether to open the browser at all (only works with Ctrl+F5; during debugging, the browser always launches to establish the debugging session)

It’s important to understand that the debugging session is tied to the specific browser session that opens. If you navigate away or reload into a new session, you lose the debugging connection because VS Code is no longer attached to that session.

Debugger Settings

The launch configuration also includes several fields for controlling debugger behavior:

  • breakOnError — whether to break on errors
  • breakOnRecordWrite — whether to break when records are written
  • enableLongRunningSqlStatements — show long-running SQL statements in the debug window
  • longRunningSqlStatementsThreshold — the threshold for what counts as “long running”
  • numberOfSqlStatements — number of SQL statements to track
  • enableSqlInformationDebugger — show SQL information in the debugger

There are slight differences between what’s available for on-premises versus cloud configurations, likely because some settings cannot be controlled in cloud environments.

Request Types: Launch, Attach, and Snapshot

Launch

The "request": "launch" type compiles and deploys your code, then opens a browser session. This is the standard development workflow.

Attach

The "request": "attach" type connects the debugger without deploying code. It includes the same connection fields as launch, but adds a key setting:

  • breakOnNext — specifies what kind of session to attach to (e.g., "WebServiceClient", "WebClient")

When you start an attach session, the debugger waits for the next matching session to begin. For example, with "WebServiceClient", it will intercept the next web service call made into Business Central. No browser opens since there’s nothing to launch — the debugger simply waits. If the call completes without hitting any breakpoints or errors, the debugger session ends.

Snapshot Initialize

The "request": "snapshotInitialize" type is used for snapshot debugging sessions. This is the only scenario where you can specify "environmentType": "Production", since snapshot debugging is a non-intrusive way to capture execution data without deploying code to production. Erik has a separate dedicated video on snapshot debugging for those who want to dive deeper.

Best Practices

  • Always include the tenant ID — especially as a partner working with multiple customers. You don’t want to accidentally deploy your app to the wrong customer’s sandbox.
  • Use descriptive names — when working with multiple configurations, clear names help you quickly identify which environment you’re targeting.
  • Clean up symbol files — when working with multiple configurations at different versions, duplicate symbols can accumulate. Clean them out periodically.
  • Be careful with production — the production environment type is only available for snapshot debugging. You cannot deploy extensions to production through launch.json.

Conclusion

launch.json is a vital file in any AL project — it’s the interface between your code and the Business Central environment you’re working with. While it’s mostly self-explanatory, understanding the nuances of multiple configurations, request types, and debugger settings will save you time and prevent costly mistakes like deploying to the wrong environment. Take the time to set up your configurations properly with meaningful names, correct tenant IDs, and appropriate startup objects, and your development workflow will be much smoother.

Picture of hougaard

hougaard