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/events/do-not-bypass-critical-operations-with-ishandled.md
Jesper Schulz-Wedde faeacb2484 Add 12 general AL event-design articles to events domain 
Add 12 atomic knowledge articles under microsoft/knowledge/events covering
general AL event-design best practices: IsHandled initialization and OnAfter
preservation, appending new event parameters, position-based event naming,
reusing/extending events, avoiding per-iteration publishing, Temp-prefixing
temporary record parameters, unabbreviated parameter names, preferring the
this keyword over IncludeSender, avoiding loosely typed parameters, not
mutating existing event contracts, and not bypassing critical operations
with IsHandled. Each article ships a .good.al and .bad.al demonstration
sample (object IDs 50240-50296; not compiled by CI). Extend the
al-events-review leaf Worklist with one targeted check per new rule.

Additive only; no contract or wiring change (events leaf already wired).

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

1.8 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
all
events
ishandled
critical-operations
posting
data-integrity
ledger
integration-event
safety
al
w1
all

Do not bypass critical operations with IsHandled

Description

The IsHandled override pattern lets a subscriber skip the guarded code entirely. That is acceptable around a pure, side-effect-free calculation, but dangerous around critical operations — posting, ledger-entry creation, number-series consumption, and referential-integrity or permission validation. Wrapping those in OnBeforeX(…; var IsHandled); if IsHandled then exit; lets any subscriber silently suppress them, risking imbalanced ledgers, orphaned documents, skipped permission checks, or duplicated numbers — corruption that surfaces far from the subscriber that caused it. Make the calculation overridable, not the commit: expose the value computation through IsHandled, or offer a regular OnAfter… event to adjust results, while the critical work runs unconditionally.

Best Practice

Scope IsHandled to a safe value-calculation block and run the critical operations unconditionally afterwards; or expose a positive OnAfter… event for subscribers to adjust results, rather than a bypass around the commit.

See sample: do-not-bypass-critical-operations-with-ishandled.good.al.

Anti Pattern

An OnBefore… IsHandled guard wrapping a posting or ledger routine — if IsHandled then exit; around the code that creates ledger entries and updates document status — letting subscribers skip the commit. Detection: an if IsHandled then exit; whose skipped body performs posting, ledger writes, number-series consumption, or integrity and permission validation.

See sample: do-not-bypass-critical-operations-with-ishandled.bad.al.