Attach and Debug Next

APPLIES TO: Business Central 2019 release wave 2 and later

If you don't want to publish and invoke functionality to debug it, you can instead attach a session to a specified server, and await a process to trigger the breakpoint you've set. Then debugging starts when the code that the breakpoint is set on is hit.


To use the attach functionality, you must make sure that your app is published with Ctrl+F5 first, or with Alt+Ctrl+F5 for RAD publishing, before you start the debugging session with F5. To debug using attach, you must make sure to debug on a new session. Creating a new server session from the client can be achieved for example by launching a new client session. Pressing F5 (Refresh) in a browser may not create a new server session, because it is cached, but if a session is expired and refreshed that will create a new session.


Only the user who starts a Visual Studio Code attach session can issue the Web request on the server.

Attach configuration

You can activate the attach functionality by creating a new configuration in the launch.json file. The configuration has two flavors; Attach to the next client on the cloud sandbox and Attach to the next client on your server. Use the first option to attach to a cloud session, and the second option to attach to a local server.

In the attach configuration, the breakOnNext setting specifies the next client to break on when the debugging session starts and allows only one option. The available options are: WebServiceClient, WebClient, and Background. The example below illustrates a configuration for a local server.

            "name": "My attach to local server",
            "type": "al",
            "request": "attach",
            "server": "https://localhost",
            "serverInstance": "BC200",
            "authentication": "Windows",
            "breakOnError": true,
            "breakOnRecordWrite": false,
            "enableSqlInformationDebugger": true,
            "enableLongRunningSqlStatements": true,
            "longRunningSqlStatementsThreshold": 500,
            "numberOfSqlStatements": 10,
            "breakOnNext": "WebClient"

Attach support

The following configurations for attach are supported:

Business Central Web client Web service client Background session
On-premises Supported Supported Supported
Sandbox Not supported Supported Not supported

To start an attach session

  1. In Visual Studio Code, under Run, choose Add configuration.
  2. Choose whether to attach to a cloud or a local session.
    The launch.json file is now populated with the correct attach configuration settings. If you've selected a local session, change the default settings to point to your local server in the server and serverInstance settings.
  3. Set breakOnNext to specify the client type on which to break.
  4. In your code, set at least one breakpoint using Run from the toolbar, choose New breakpoint, and then choose which type of breakpoint to add. You can always add more breakpoints while debugging.
  5. If your most recent app is not yet published, it's important to make sure you publish it pressing Ctrl+F5, alternatively Alt+Ctrl+F5 for RAD publishing. Then, use F5 to start the attach session.


    If you modify the app code during the debugging session, make sure to re-publish the app using Ctrl+F5.

  6. After publishing the app, press F5 to start a debugging session.


    If you have more attach configuration settings, you must first select which configuration to start.

  7. Debug and inspect the code. You can add more breakpoints while debugging.
  8. Stop the attach debugging session by selecting Detach in the Visual Studio Code toolbar.

See Also

AL Development Environment
Developing Extensions in AL
Snapshot Debugging
JSON Files
EnableLongRunningSQLStatements Property
EnableSQLInformationDebugger Property
LongrunningSQLStatementsThreshold Property
NumberOfSQLStatements Property