Attach and debug next

APPLIES TO: Business Central 2019 release wave 2 and later

Attach the AL debugger to an existing session or wait for the next session to troubleshoot code without launching it from Visual Studio Code. When the session runs code that reaches a breakpoint, the debugger stops so that you can inspect the code.

Prepare to attach the debugger

Make sure the app version you want to debug is published to the target environment and matches your source. Attaching doesn't publish the app. To publish local changes without debugging, select a launch configuration and press Ctrl+F5. For RAD publishing, press Ctrl+Alt+F5.

To debug code in another extension, that extension must allow debugging. Learn more in Debug AL code.

By default, the debugger targets a session that belongs to the user signed in to Visual Studio Code. To debug another user's session, specify userId or that user's sessionId. The user starting the debugger needs permission to attach to another user's session. The D365 ATTACH DEBUG permission set grants this permission.

Supported attach configurations

In sandbox and on-premises environments, you can attach to web client, web service client, background, and agent sessions.

Live attach debugging isn't supported in Business Central online production environments. To record and debug code in a production environment, use Snapshot debugging.

Configure the target session

Add an attach configuration in the launch.json file for a cloud sandbox or your own server. The AL extension also provides Agent-specific attach configurations for both environments. Learn more in Launch JSON file.

The commonly used breakOnNext values are WebServiceClient, WebClient, Background, and Agent. Specify one value to select the session type.

Set sessionId to attach to an existing session. Set breakOnNext to match its client type. If you also specify userId, that user must own the session. If you omit userId, the debugger uses the session's owner and checks whether you have permission to debug that user's session.

If you omit sessionId, the debugger waits for the next session of the type specified by breakOnNext. It targets userId when specified, or the user signed in to Visual Studio Code otherwise.

Start an attach debugging session

1. In Visual Studio Code, go to Run > Add Configuration.
2. Select an AL attach configuration for a cloud sandbox or your own server.
3. In launch.json, update the connection settings for your target environment.
4. Set breakOnNext to the session type. To attach to an existing session, set sessionId. To target another user, set userId or that user's sessionId.
5. Set a breakpoint in the code you want to debug.
6. Select the attach configuration and press F5.
7. If you're waiting for the next session, first create a new session of the type specified by breakOnNext. Run the functionality you want to debug in the target session.
8. When execution reaches a breakpoint, inspect the code. You can add more breakpoints while debugging.
9. To stop debugging, select Detach in the Visual Studio Code debug toolbar.

Example: Attach to a web client session

This configuration attaches to the next web client session on an on-premises server. Replace <ServerInstance> with the name of your Business Central Server instance, and update server and authentication for your environment.

{
    "name": "Attach to web client on own server",
    "type": "al",
    "request": "attach",
    "environmentType": "OnPrem",
    "server": "https://localhost",
    "serverInstance": "<ServerInstance>",
    "authentication": "Windows",
    "breakOnError": "All",
    "breakOnRecordWrite": "None",
    "enableSqlInformationDebugger": true,
    "enableLongRunningSqlStatements": true,
    "longRunningSqlStatementsThreshold": 500,
    "numberOfSqlStatements": 10,
    "breakOnNext": "WebClient"
}

Example: Attach to a sandbox web service session

This configuration attaches to the next web service session in an online sandbox. Replace <EnvironmentName> with your sandbox's name.

{
    "name": "Attach to online sandbox",
    "type": "al",
    "request": "attach",
    "environmentType": "Sandbox",
    "environmentName": "<EnvironmentName>",
    "breakOnError": "All",
    "breakOnRecordWrite": "None",
    "enableSqlInformationDebugger": true,
    "enableLongRunningSqlStatements": true,
    "longRunningSqlStatementsThreshold": 500,
    "numberOfSqlStatements": 10,
    "breakOnNext": "WebServiceClient"
}

Example: Attach to an agent session in a sandbox

This configuration attaches to the next session for the specified agent in an online sandbox. Replace <EnvironmentName> with your sandbox's name and <AgentUserSecurityId> with the agent's user security ID. The user starting the debugger needs permission to attach to another user's session.

{
    "name": "Attach to agent on cloud sandbox",
    "type": "al",
    "request": "attach",
    "environmentType": "Sandbox",
    "environmentName": "<EnvironmentName>",
    "breakOnError": "All",
    "breakOnRecordWrite": "None",
    "enableSqlInformationDebugger": true,
    "enableLongRunningSqlStatements": true,
    "longRunningSqlStatementsThreshold": 500,
    "numberOfSqlStatements": 10,
    "breakOnNext": "Agent",
    "userId": "<AgentUserSecurityId>"
}

Example: Attach to an agent session on your own server

This configuration connects to the next session for the specified agent on an on-premises server. Replace <ServerInstance> and <AgentUserSecurityId> with your server instance name and the agent's user security ID. Update server and authentication for your environment. The environment must provide agent sessions, and the user starting the debugger needs permission to connect to another user's session.

{
    "name": "Attach to agent on own server",
    "type": "al",
    "request": "attach",
    "environmentType": "OnPrem",
    "server": "https://localhost",
    "serverInstance": "<ServerInstance>",
    "authentication": "Windows",
    "breakOnError": "All",
    "breakOnRecordWrite": "None",
    "enableSqlInformationDebugger": true,
    "enableLongRunningSqlStatements": true,
    "longRunningSqlStatementsThreshold": 500,
    "numberOfSqlStatements": 10,
    "breakOnNext": "Agent",
    "userId": "<AgentUserSecurityId>"
}

Related information

AL development environment
Developing extensions in AL
Debug AL code
Snapshot debugging
Launch JSON file
JSON files