{"title":"Attach and debug next","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-attach-debug-next/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-attach-debug-next, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-attach-debug-next","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Attach the AL debugger to an existing or next session in Business Central. Configure web client, web service, background, and agent session debugging.","date":"2026-10-15","meta":{"topic":"how-to"},"outline":[{"level":2,"title":"Prepare to attach the debugger","slug":"prepare-to-attach-the-debugger","at":310,"chars":747},{"level":2,"title":"Supported attach configurations","slug":"supported-attach-configurations","at":1057,"chars":745},{"level":2,"title":"Configure the target session","slug":"configure-the-target-session","at":1802,"chars":1018},{"level":2,"title":"Start an attach debugging session","slug":"start-an-attach-debugging-session","at":2820,"chars":983},{"level":2,"title":"Example: Attach to a web client session","slug":"example-attach-to-a-web-client-session","at":3803,"chars":779},{"level":2,"title":"Example: Attach to a sandbox web service session","slug":"example-attach-to-a-sandbox-web-service-session","at":4582,"chars":629},{"level":2,"title":"Example: Attach to an agent session in a sandbox","slug":"example-attach-to-an-agent-session-in-a-sandbox","at":5211,"chars":824},{"level":2,"title":"Example: Attach to an agent session on your own server","slug":"example-attach-to-an-agent-session-on-your-own-server","at":6035,"chars":1005},{"level":2,"title":"Related information","slug":"related-information","at":7040,"chars":225}],"text":"> APPLIES TO: Business Central 2019 release wave 2 and later\nAttach 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.\n## Prepare to attach the debugger\nMake 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 devenv-rad-publishing, press Ctrl+Alt+F5.\nTo debug code in another extension, that extension must allow debugging. See Debug AL code<devenv-debugging>.\nBy 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.\n## Supported attach configurations\nIn sandbox and on-premises environments, you can attach to web client, web service client, background, and agent sessions.\nBusiness Central environment|Web client|Web service client|Background session|Agent session\nOn-premises|Supported|Supported|Supported|Supported\nSandbox|Supported|Supported|Supported|Supported\nLive attach debugging isn't supported in Business Central online production environments. To record and debug code in a production environment, use devenv-snapshot-debugging.\n> NOTE\n> Use `breakOnNext: \"Background\"` for a background session. A page background task runs in a child session and isn't a separate Background attach target. To debug a page background task, debug its parent session.\n## Configure the target session\nAdd 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. See devenv-json-launch-file.\nThe commonly used breakOnNext values are WebServiceClient, WebClient, Background, and Agent. Specify one value to select the session type.\nSet 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.\nIf 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.\n> NOTE\n> Starting in Business Central 2023 release wave 1, the sessionId and userId properties let you attach to an ongoing session or debug on behalf of another user.\n## Start an attach debugging session\n1. In Visual Studio Code, go to Run > Add Configuration.\n2. Select an AL attach configuration for a cloud sandbox or your own server.\n3. In launch.json, update the connection settings for your target environment.\n4. 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.\n5. Set a breakpoint in the code you want to debug.\n6. Select the attach configuration and press F5.\n7. 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.\n8. When execution reaches a breakpoint, inspect the code. You can add more breakpoints while debugging.\n9. To stop debugging, select Detach in the Visual Studio Code debug toolbar.\n> IMPORTANT\n> If you change the app code, republish it so that the source matches the published app before you continue debugging.\n## Example: Attach to a web client session\nThis 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.\n```json\n{\n    \"name\": \"Attach to web client on own server\",\n    \"type\": \"al\",\n    \"request\": \"attach\",\n    \"environmentType\": \"OnPrem\",\n    \"server\": \"https://localhost\",\n    \"serverInstance\": \"<ServerInstance>\",\n    \"authentication\": \"Windows\",\n    \"breakOnError\": \"All\",\n    \"breakOnRecordWrite\": \"None\",\n    \"enableSqlInformationDebugger\": true,\n    \"enableLongRunningSqlStatements\": true,\n    \"longRunningSqlStatementsThreshold\": 500,\n    \"numberOfSqlStatements\": 10,\n    \"breakOnNext\": \"WebClient\"\n}\n```\n## Example: Attach to a sandbox web service session\nThis configuration attaches to the next web service session in an online sandbox. Replace \\<EnvironmentName\\> with your sandbox's name.\n```json\n{\n    \"name\": \"Attach to online sandbox\",\n    \"type\": \"al\",\n    \"request\": \"attach\",\n    \"environmentType\": \"Sandbox\",\n    \"environmentName\": \"<EnvironmentName>\",\n    \"breakOnError\": \"All\",\n    \"breakOnRecordWrite\": \"None\",\n    \"enableSqlInformationDebugger\": true,\n    \"enableLongRunningSqlStatements\": true,\n    \"longRunningSqlStatementsThreshold\": 500,\n    \"numberOfSqlStatements\": 10,\n    \"breakOnNext\": \"WebServiceClient\"\n}\n```\n## Example: Attach to an agent session in a sandbox\nThis 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.\n```json\n{\n    \"name\": \"Attach to agent on cloud sandbox\",\n    \"type\": \"al\",\n    \"request\": \"attach\",\n    \"environmentType\": \"Sandbox\",\n    \"environmentName\": \"<EnvironmentName>\",\n    \"breakOnError\": \"All\",\n    \"breakOnRecordWrite\": \"None\",\n    \"enableSqlInformationDebugger\": true,\n    \"enableLongRunningSqlStatements\": true,\n    \"longRunningSqlStatementsThreshold\": 500,\n    \"numberOfSqlStatements\": 10,\n    \"breakOnNext\": \"Agent\",\n    \"userId\": \"<AgentUserSecurityId>\"\n}\n```\n## Example: Attach to an agent session on your own server\nThis 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.\n```json\n{\n    \"name\": \"Attach to agent on own server\",\n    \"type\": \"al\",\n    \"request\": \"attach\",\n    \"environmentType\": \"OnPrem\",\n    \"server\": \"https://localhost\",\n    \"serverInstance\": \"<ServerInstance>\",\n    \"authentication\": \"Windows\",\n    \"breakOnError\": \"All\",\n    \"breakOnRecordWrite\": \"None\",\n    \"enableSqlInformationDebugger\": true,\n    \"enableLongRunningSqlStatements\": true,\n    \"longRunningSqlStatementsThreshold\": 500,\n    \"numberOfSqlStatements\": 10,\n    \"breakOnNext\": \"Agent\",\n    \"userId\": \"<AgentUserSecurityId>\"\n}\n```\n## Related information\nAL development environment<devenv-reference-overview>\nDeveloping extensions in AL<devenv-dev-overview>\nDebug AL code<devenv-debugging>\ndevenv-snapshot-debugging\ndevenv-json-launch-file\ndevenv-json-files"}