3.1 Debugging & Snapshot Debugging in Visual Studio Code

3.1 Debugging & Snapshot Debugging in Visual Studio Code

Debugging in Microsoft Dynamics 365 Business Central is divided into two distinct paradigms: Interactive Debugging and Snapshot Debugging. Interactive debugging provides real-time, synchronous execution control (stepping, variable modification, and thread pausing) and is strictly limited to non-production environments. Snapshot debugging provides an asynchronous, non-intrusive recording mechanism engineered specifically to diagnose faults in cloud production environments without impacting active business operations.

---

1. Interactive Debugging Architecture & VS Code Controls

Interactive debugging attaches the Visual Studio Code debugger directly to the Business Central Server instance. When a breakpoint is reached, the server suspends the executing thread, locks the associated SQL transaction, and transfers execution control to VS Code.

Debugger Launch Configurations (launch.json)

There are two primary interactive debug request types:

• "request": "launch": Deploys the current extension project to the target environment, starts a new Web Client session, and attaches the debugger immediately.
• "request": "attach": Attaches the debugger to an existing running session or waits for the next incoming session on the server without redeploying the extension package.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Sandbox Session",
      "type": "al",
      "request": "attach",
      "environmentType": "Sandbox",
      "environmentName": "DevelopmentSandbox",
      "breakOnError": true,
      "breakOnRecordWrite": false,
      "enableLongRunningSqlStatements": true,
      "longRunningSqlStatementThreshold": 500
    }
  ]
}

Advanced Debugging Flags in launch.json

• breakOnError: When set to true, the debugger automatically breaks when a runtime error occurs (e.g., Error('...') or TestField failure), pausing execution at the exact line that threw the exception before the transaction rolls back.
• breakOnRecordWrite: Breaks whenever a database write operation occurs (Insert, Modify, Delete, ModifyAll, DeleteAll).
• enableLongRunningSqlStatements: Emits diagnostic debug console messages when an executed SQL statement exceeds the longRunningSqlStatementThreshold (in milliseconds).

Breakpoint Capabilities in AL

• Standard Breakpoint (F9): Pauses execution every time the statement is reached.
• Conditional Breakpoint: Evaluates an AL expression (e.g., Customer."No." = '10000' or LineAmount > 5000); pauses execution only when the expression evaluates to true.
• Hit Count Breakpoint: Pauses execution after the line has executed a specified number of times (e.g., >= 50), invaluable for looping constructs.

VS Code Debug Inspection Panes

• Variables Pane: Displays Globals (object-level global variables, single-instance state) and Locals (procedure parameters, local variables, and Rec/xRec buffers).
• Watch Pane: Allows continuous evaluation of custom AL expressions across execution steps.
• Call Stack Pane: Displays the active procedure call hierarchy, including event publisher and subscriber invocations across different extensions.

---

2. Why Interactive Debugging is Blocked in Production

In Business Central SaaS production environments, interactive debugging is permanently disabled by the platform architecture for three critical reasons:

1. Database Lock Escalation: Pausing an active AL thread inside an open transaction holds row and table locks in Azure SQL. If a developer pauses on a breakpoint during posting, all other users attempting to access those tables are blocked, causing severe transactional deadlocks.
2. HTTP Request Timeouts: Cloud web clients and API endpoints enforce strict execution timeouts. Pausing a thread exceeds timeout thresholds, resulting in dropped sessions.
3. Tenant Resource Isolation: Interactive debugging consumes disproportionate server worker threads, compromising the multi-tenant resource governance model.

3. Snapshot Debugging Architecture & Workflow

Snapshot debugging allows developers to record the execution of AL code on a production or sandbox environment. When code executes past a configured Snappoint, the server captures the call stack, source code positions, and local/global variable states into an in-memory buffer without halting the user's execution thread or holding database locks.

Required Permissions

To initialize or download a snapshot session, the user must have:

• The D365 SNAPSHOT DEBUG permission set assigned in Business Central.
• Delegated Admin or internal user credentials with permissions to access the target environment.

launch.json Snapshot Configuration

To establish a snapshot debugging session, add a configuration entry with "request": "snapshot":

{
  "name": "Capture Production Incident Snapshot",
  "type": "al",
  "request": "snapshot",
  "environmentType": "Production",
  "environmentName": "Production",
  "snapshotConfiguration": {
    "userId": "jane.doe@contoso.com",
    "sessionId": 0,
    "executionContext": "WebClient",
    "captureFault": "All"
  }
}

Configuration Attributes Explained

---

4. End-to-End Snapshot Lifecycle: Capture, Download & Replay

The snapshot workflow follows five distinct sequential phases:

1. Initialize Snapshot  ──>  2. Set Snappoints  ──>  3. User Executes Scenario  ──>  4. Finish Snapshot  ──>  5. Replay Offline
   (Alt+F5 / Palette)        (F9 in Snapshot)        (Live Production Work)          (Alt+F5 / Palette)       (Alt+R in VS Code)

Step 1: Initialize Snapshot Session

Press Alt+F5 or open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and execute AL: Initialize Snapshot Debugging. The status bar in VS Code turns orange, indicating that the server is actively listening for matching sessions.

Step 2: Set Snappoints

With the snapshot session initialized, place snappoints in your AL source files using F9 or by clicking the margin. Snappoints appear with a distinct icon. You can set:

• Standard Snappoint: Captures execution state every time execution passes through the line.
• Conditional Snappoint: Evaluates an AL condition; captures only when true.
• Log Message Snappoint: Emits formatted variable output to the snapshot log without capturing full memory dumps.

Step 3: Trigger the Scenario in Business Central

The target user (or background job) performs the business operation in the Web Client or API. As execution hits snappoints or encounters errors, the server writes execution frames to an internal snapshot archive file on the Business Central server.

Step 4: Finish and Download Snapshot

Press Alt+F5 or execute AL: Finish Snapshot Debugging. Visual Studio Code instructs the server to close the recording session. VS Code automatically downloads the resulting .zip snapshot archive into the local project's .snapshots folder (e.g., .snapshots/snapshot_20260829_103045.zip).

If multiple snapshots exist or if you need to download a previous recording, execute AL: List Snapshots to view all available server-side recordings, then select AL: Download Snapshot.

Step 5: Replay Snapshot Debugging

Open the Command Palette and select AL: Replay Snapshot Debugging (or press Alt+R), then select the downloaded .zip file from the list. VS Code launches an offline replay debug session:

• You can use standard stepping keys: Step Over (F10), Step Into (F11), and Step Out (Shift+F11) to navigate forward and backward through the recorded execution trace.
• Inspect the Variables Pane to see exact global and local variable states at every captured execution frame.
• View the full Call Stack at each snappoint.

Exam Tip: Snapshot files are standalone .zip archives containing the execution trace and symbol references. You do not need an active connection to the Business Central server while replaying a downloaded snapshot.