Previous

Next

Use attach and debug with attach configurations

Completed

As with the snapshot debugger, attach the AL debugger to either an existing running session or to the next session for the specific user. In both cases, it's set up by specifying a session ID or a user ID in the launch.json attach configuration.

In addition, a new Attach Debugging PermissionSet is available to allow cross-user debugging.

If you don't want to publish and invoke functionality to debug it, you can instead attach a session to a specified server. Then 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. 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's cached, but if a session is expired and refreshed, that creates a new session.

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

You can activate the attach functionality by creating a new configuration in the launch.json file. The configuration has two flavors:

• Attach to the client on the cloud sandbox

• Attach to the client on your server

Use the first option to attach to a cloud session, and the second option to attach to a local server.

With Business Central 2023 release wave 1, two new properties are added to the launch configuration: sessionId and userId, which allow attaching to an ongoing session and also debugging on behalf of another user.

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

• Background

Two other important properties are sessionId and userId. sessionId specifies an ongoing session of the specified type in breakOnNext. This session should belong to the user in userId property if specified.

If sessionId isn't specified, but userId is, then the debugger attaches to the next session of the type specified in breakOnNext for the given user.

If userId is a different user than the user logged into Visual Studio Code, then the user logged into Visual Studio Code must be part of D365 ATTACH DEBUG permission set.

The debugger can connect to background sessions, and not background tasks.

This example 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"
        }

Start an attach session

To start an attach session, follow these steps:

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 the breakOnNext property 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 add more breakpoints while debugging.

5. If your most recent app isn't yet published, it's important to make sure you publish it by pressing Ctrl+F5 or 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 republish 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.

Continue