skill-debug
AL debugging and diagnostics for Business Central. Use when performing snapshot debugging, CPU profiling, analyzing telemetry, or troubleshooting runtime issues.
javiarmesto · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add javiarmesto/ALDC-AL-Development-Collection --skill skill-debug技能说明
name: skill-debug description: AL debugging and diagnostics for Business Central. Use when performing snapshot debugging, CPU profiling, analyzing telemetry, or troubleshooting runtime issues.
Skill: AL Debugging & Diagnostics
Purpose
For BC29 AL0926 section-order errors or new isolation behavior, read the relevant sections of AL18 capability checks. Use actual compiler/runtime evidence and keep compilation distinct from execution.
Systematic diagnosis and root cause analysis for AL Business Central issues: runtime errors, logic bugs, intermittent failures, performance bottlenecks, and configuration problems.
When to Load
This skill should be loaded when:
- A runtime error, exception, or unexpected behavior is reported
- A logic bug needs root cause analysis (not just a symptom fix)
- An intermittent issue needs snapshot capture
- A performance bottleneck needs CPU profiling
- Configuration issues (auth, symbols, build, publishing) block development
- An event subscriber is not firing as expected
Core Patterns
Pattern 1: Choose Debugging Strategy
Select the right tool before starting:
| Issue Type | Strategy | Tool |
|---|---|---|
| Consistent runtime error | Standard debugger | al_debug |
| Already deployed code | Debug without publish | al_debug |
| Rapid dev cycle | Incremental publish | al_publish (incremental) |
| Intermittent / hard-to-reproduce | Snapshot debugging | al_snapshotdebugging |
| Slow performance | CPU profiling | VS Code command (not an agent tool) |
| Auth / symbols / build | Configuration troubleshoot | See Workflow Step 2b |
| Copilot AI feature | Agent session debug | launch.json with clientType: Agent |
Pattern 2: Data Flow Tracing
Scenario: "Value is wrong after posting"
1. Set breakpoint at final location (where value is wrong)
2. Work backwards to find where value is set
3. Use `usages` tool to find all assignments
4. Set breakpoints at each assignment point
5. Step through to find which execution path is taken
6. Inspect conditions and variable states at each point
Pattern 3: Event Subscriber Not Firing
Scenario: "My event subscriber doesn't execute"
1. Verify subscriber signature exactly matches publisher (name, parameters, types)
2. Check SkipOnMissingLicense and SkipOnMissingPermission attributes
3. Confirm the extension containing the publisher is active and published
4. Set breakpoint inside subscriber body
5. Verify the publisher event is actually being raised (breakpoint in publisher)
6. Check if IsHandled = true is set before your subscriber runs
7. Inspect subscriber execution order (EventPriority)
Pattern 4: Performance Bottleneck
// ❌ N+1 pattern — common cause of slow pages
repeat
Item.Get(SalesLine."No."); // DB call inside loop
SalesLine.Amount := Item.Price * SalesLine.Quantity;
until SalesLine.Next() = 0;
// ✅ Use SetLoadFields + single pass
SalesLine.SetLoadFields("No.", Quantity, Amount);
if SalesLine.FindSet() then
repeat
// ...
until SalesLine.Next() = 0;
CPU profile analysis focus:
- Top time-consuming procedures (hotspots)
- Frequently called procedures in loops
- Expensive database operations
- FlowField CalcFormula complexity
Pattern 5: Snapshot Debugging for Intermittent Issues
⚠️ HUMAN GATE: Snapshots may capture sensitive runtime data.
Before initializing:
1. Confirm what data will be captured
2. Security review for sensitive information
3. Obtain explicit user approval
Commands (one tool — `al_snapshotdebugging` — covers initialize / finish / view):
al_snapshotdebugging (initialize) ← start capture session
[reproduce scenario 10-20 times]
al_snapshotdebugging (finish) ← end capture
al_snapshotdebugging (view) ← view and compare
Compare snapshots between success and failure cases:
- Variable values at failure point
- Timing differences
- Execution paths taken
- Data state variations
Workflow
Step 1: Context Gathering (MANDATORY before any debugging)
Read existing plans context first:
.claude/plans/memory.md ← project state and recent decisions
.claude/plans/*-diagnosis.md ← previous debug sessions (similar issues)
Gather issue information:
- What is the expected behavior vs actual behavior?
- When does it happen: always / sometimes / specific conditions?
- Exact error message and stack trace
- Recent code changes (potential regression source)
- User/permission set and environment where it occurs
Stop criterion: can reproduce the issue consistently (≥80% success rate).
Step 2a: Isolate the Problem (Runtime / Logic)
- Narrow down scope with
searchandusagestools - Identify suspect objects (tables, pages, codeunits, event subscribers)
- Attach debugger with selected strategy (Pattern 1)
- Set strategic breakpoints:
- Just before the error occurs
- At data modification points
- In event subscribers and validation triggers
- Inspect: variable values, record filters, call stack, parameter values
- Step execution: F10 (step over), F11 (step into), Shift+F11 (step out)
Step 2b: Configuration Troubleshooting
Authentication failures (401/403, cannot download symbols):
⚠️ HUMAN GATE: Clearing credentials disconnects active sessions.
Confirm impact and obtain approval before clearing the credentials cache
(a VS Code command, not an agent tool).
Then re-authenticate and verify launch.json authentication method.
Missing symbols (unresolved references, red squiggles):
al_downloadsymbols ← first attempt
al_downloadsymbols (globalSourcesOnly) ← if no BC server connection is available
al_build ← verify compilation
Check app.json dependencies version alignment.
Build errors — common codes:
AL0896— Recursive FlowField: map dependency graph, break circular chain- `AL018