Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-06 17:36:53 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
bcquality/microsoft/knowledge/error-handling/prefer-errorinfo-for-actionable-errors.md
Copilot 65f6f22157 Add open-ended bc-version range shorthand [N..] 
A closed range like [23..28] wrongly implies guidance stops applying after
BC28, so a reviewer targeting BC29+ would not match the file. Introduce an
open-ended shorthand [N..] meaning ''version N and every later version''.

- validate_frontmatter.py: RANGE_SHORTHAND allows an optional upper bound;
  expand_bc_version returns the normalized string ''N..'' for open-ended.
- read.md: document the fourth bc-version form and its matching rule
  (matches target >= N; not enumerable).
- write.md: prefer [N..] over a closed range for a feature introduced in N
  and not expected to be removed.
- Apply [23..] to the actionable-errors article (actionable errors shipped
  in BC23 and are not version-bounded above).
- README: mention [N..] in the frontmatter example.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-06-23 11:20:11 +02:00

2.4 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
23..
error-handling
errorinfo
actionable-errors
fix-it
show-it
addaction
addnavigationaction
error-dialog
al
w1
all

Prefer ErrorInfo with recommended actions over a plain Error for recoverable failures

Description

A plain Error('text') ends the operation with a dead-end dialog: the user reads the message but the system offers no way forward. The ErrorInfo data type, combined with the actionable-errors framework added in 2023 release wave 2, lets an error carry a recommended action the user can take to unblock themselves without leaving their task. Two kinds exist: a Fix-it action (AddAction), used when the code already knows the correct value and can apply it in one step, and a Show-it action (AddNavigationAction together with PageNo), used when the correction lives on a related record the user should be taken to. An error dialog renders at most two recommended actions. LLMs trained on older AL almost always emit a bare Error(...) and rarely reach for ErrorInfo, so this guidance is remedial.

Best Practice

Build an ErrorInfo, set Title, Message, and DetailedMessage, then attach the action that matches the situation. For a Fix-it, call AddAction(Caption, Codeunit::Handler, 'MethodName') where the handler method (which receives the ErrorInfo) applies the known-good value; phrase the caption as "Set value to …". For a Show-it, set PageNo := Page::"…", set RecordId so navigation opens the right record, and call AddNavigationAction('Show …'). Raise it with Error(ErrorInfo). Reserve recommended actions for cases where the solution is genuinely known and the user has permission to apply it.

See sample: prefer-errorinfo-for-actionable-errors.good.al.

Anti Pattern

Surfacing a recoverable validation failure with Error('You cannot invoice more than %1 units.', MaxQty) and nothing else. The user is blocked with no offered remedy even though the code knows the maximum and could set it. The detection signal: an Error call in a validation or posting path whose message names a specific correct value or a specific related page, with no surrounding ErrorInfo, AddAction, or AddNavigationAction. Replace it with an ErrorInfo that carries the corresponding Fix-it or Show-it action.

See sample: prefer-errorinfo-for-actionable-errors.bad.al.