Events
Mar 31, 11 PM - Apr 2, 11 PM
The ultimate Microsoft Fabric, Power BI, SQL, and AI community-led event. March 31 to April 2, 2025.
Register todayThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
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.
Note
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 is cached, but if a session is expired and refreshed that will create a new session.
Important
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 and 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. For an overview of configuration options, see Launch JSON file.
Note
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
, and Background
. On a sandbox environment, you can only attach to and break on the next WebServiceClient
session.
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 will be attached to the next session of the type specified in breakOnNext
for the given user.
Important
In case of userId
being 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.
Note
The debugger is able to connect to background sessions, and not background tasks.
The following example illustrates a configuration for a local server, where you want to debug a web client session.
...
{
"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"
}
...
The following example illustrates a configuration for an online sandbox, where you want to debug a web service endpoint.
...
{
"name": "Attach to online sandbox",
"type": "al",
"request": "attach",
"environmentType": "Sandbox",
"environmentName": "MyEnvironment",
"breakOnError": true,
"breakOnRecordWrite": false,
"enableSqlInformationDebugger": true,
"enableLongRunningSqlStatements": true,
"longRunningSqlStatementsThreshold": 500,
"numberOfSqlStatements": 10,
"breakOnNext": "WebServiceClient"
}
...
The following configurations for attach are supported:
Business Central | Web client | Web service client | Background session |
---|---|---|---|
On-premises | Supported | Supported | Supported |
Sandbox | Supported | Supported | Supported |
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.breakOnNext
to specify the client type on which to break.Important
If you modify the app code during the debugging session, make sure to re-publish the app using Ctrl+F5 .
Note
If you have more attach configuration settings, you must first select which configuration to start.
AL Development Environment
Developing Extensions in AL
Debugging
Snapshot Debugging
JSON Files
Events
Mar 31, 11 PM - Apr 2, 11 PM
The ultimate Microsoft Fabric, Power BI, SQL, and AI community-led event. March 31 to April 2, 2025.
Register todayTraining
Module
Debug and deploy your extension in Dynamics 365 Business Central - Training
Discover how to debug with Visual Studio Code and deploy your extension using RAD feature in Dynamics 365 Business Central.
Certification
Microsoft Certified: Dynamics 365 Business Central Developer Associate - Certifications
Demonstrate you have the skills to design, develop, test, and maintain solutions based on Dynamics 365 Business Central.
Documentation
Snapshot debugging - Business Central
Overview of how snapshot debugging allows recording running AL code for Business Central
Debugging in AL - Business Central
Debugging in AL with Visual Studio Code and the AL Language extension.
Attach AL debugger to active session or next session
Attach to user or session ID in the standard AL debugger.