The AL debugger in Business Central — a deep dive

Writing AL code without good debugging tooling would be miserable. The AL debugger in VS Code provides step-through debugging, breakpoints, watch variables, snapshot debugging for production, and attach-to-session for live troubleshooting. Mastering it is a productivity multiplier for any BC developer.

The two debug modes.

• Live debugging — attach to your dev session, step through code as it runs.
• Snapshot debugging — record a session and replay; non-intrusive for production.

Each has its place.

Live debugging setup.

1. AL Language extension installed in VS Code.
2. launch.json configured with target server (sandbox URL, auth).
3. Press F5 to launch / attach.
4. VS Code connects to BC session.
5. Set breakpoints; trigger the code path; step through.

The experience is full VS Code debugger — step into, step over, step out, watch expressions, call stack, locals.

Breakpoints.

• Line breakpoint — fires when the line is reached.
• Conditional breakpoint — only when an expression evaluates true.
• Hit count breakpoint — every Nth time.
• Function breakpoint — by function name.

Conditional breakpoints save massive time — instead of stepping through hundreds of records, break only when Item No. = 'PROBLEM-ITEM'.

Watch expressions. Add expressions to the Watch panel:

• Current variable values.
• Computed expressions (SalesAmount * 1.21).
• Object properties.

Watch updates as you step; visualises state at each point.

Snapshot debugging. A different model:

1. Configure snapshot debugging in VS Code launch.json.
2. Trigger snapshot recording in BC (admin action).
3. User performs the action being debugged.
4. Stop recording; VS Code downloads the snapshot.
5. Replay locally with full debugger experience.

Crucially, snapshot debugging doesn't pause production — the user's action runs at full speed. The recording is replayed offline. Production-safe debugging.

Useful in production scenarios. Customer reports a bug in production. The partner can:

1. Configure snapshot debugging on the prod environment.
2. Have the user reproduce the issue.
3. Capture the snapshot.
4. Debug locally with full visibility into what happened.

Far better than "send me a screenshot."

Attach to current session vs another.

• Current session — your dev session; you're triggering and stepping.
• Another session — attach to a colleague's session or a background session (job queue).

Attaching to job queue for batch debugging is invaluable; otherwise debugging batch issues requires guesswork.

Source code mapping. The debugger maps compiled IL back to source AL:

• Set breakpoint in your AL file.
• BC executes IL.
• Breakpoint fires on the IL line that maps to your AL.

Mapping works for your own extension and Microsoft's base app (you don't have base app source by default, but can step into compiled views).

Performance counters. Beyond debugging, AL profiling:

• Performance Profile sessions in BC client.
• Identify hot paths.
• Compare options.

Profiling and debugging are complementary; profiling shows where time is spent, debugging shows why a specific path behaves as it does.

Common debugging scenarios.

• Posting fails — break on the error; inspect data state.
• Wrong field value — break before the line, inspect input; break after, inspect output.
• Performance issue — profile + targeted snapshot.
• External integration fails — break in the callback / event handler; inspect HTTP response.

Test debugging. AL tests can be debugged like regular code:

• Run test in debug mode.
• Step through.
• Inspect assertions.

Test development without debugging is slow; with debugging, tests get fixed quickly.

Common pitfalls.

• Wrong launch.json target. Connected to wrong environment; breakpoints don't fire.
• Source code mismatch. Extension compiled vs source out of sync; breakpoints in unreachable lines.
• Multi-session confusion. Stepping in one session while another is running; concurrency surprises.
• Snapshot too large. Long-running sessions produce big snapshots; trim recording windows.
• Forgetting to publish. Edit AL, hit F5; debugging old compiled version.

Best practices.

• Conditional breakpoints for high-volume code paths.
• Step over for known-good code; step into for new logic.
• Watch expressions rather than repeatedly inspecting variables.
• Snapshot for production — safer than attach to live prod.
• Logging supplement debugging — for issues that don't reproduce, telemetry to App Insights is the alternative.

Strategic positioning. The AL debugger has matured enormously. Modern BC development should not be done without it. For partners maintaining extensions across many customers, snapshot debugging in production is one of the most valuable features in the BC tooling — it transforms what was previously a guessing game into reproducible debugging. Investment in debugger fluency pays back daily.