Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-06 09:26:52 +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 0ad92cad86 Refine events articles after review feedback 
Correct wording in five events articles to reflect that AL event
subscribers bind by parameter name, not position:

- add-new-event-parameters-at-the-end: drop the inaccurate claim that
  appending a parameter forces subscribers to be updated or causes wrong
  values; keep the append-at-end best practice.
- do-not-add-ishandled-to-an-existing-event: reframe from "breaking
  change" to the semantic/purpose shift that leaves existing subscribers
  pointless; rename the breaking-change keyword to semantic-change.
- name-events-by-publisher-position: extend the good sample with
  position-named publishers raised from table and report trigger
  contexts.
- initialize-ishandled-to-false-before-publishing: scope the detection
  and best practice to events that actually carry a var IsHandled, so an
  OnBefore with no IsHandled is not flagged.
- do-not-bypass-critical-operations-with-ishandled: add a litmus-test
  definition of a critical operation (code that cannot stand as an
  independent, self-contained unit).

Knowledge-only; no contract or wiring change.

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

2 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. A critical operation is one that cannot stand as an independent, self-contained unit — code whose partial execution or omission leaves the system inconsistent (imbalanced ledgers, orphaned documents, gaps in a number series, or skipped permission checks). 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.