Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-07 18:06:53 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
bcquality/microsoft/knowledge/events/do-not-add-ishandled-to-an-existing-event.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

1.6 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
all
events
ishandled
semantic-change
event-contract
backward-compatibility
onbefore
integration-event
subscribers
al
w1
all

Do not add IsHandled to an existing event

Description

Adding a var IsHandled: Boolean parameter to an event that already shipped without one silently changes the event's purpose — from a plain notification into an overridable seam. Existing subscribers were written against a "notify" contract they never agreed to make skippable, so their behaviour can quietly become wrong or pointless. The safe move is to leave the existing event untouched and introduce a new OnBefore… event carrying IsHandled at the point you want to make overridable. Existing subscribers keep working against the original event; new subscribers opt into the override seam through the new one.

Best Practice

Keep the existing event as-is and add a separate OnBeforeX(…; var IsHandled: Boolean) before the logic you want to make overridable. Two events with distinct, stable contracts are safer than one event whose meaning and signature were changed under its subscribers.

See sample: do-not-add-ishandled-to-an-existing-event.good.al.

Anti Pattern

Mutating a shipped event — for example adding var IsHandled to OnAfterCalculateTotal — to retrofit override behaviour, which overloads the event's meaning and undermines existing subscribers. Detection: an IsHandled parameter added to a pre-existing event signature rather than introduced through a new dedicated OnBefore publisher.

See sample: do-not-add-ishandled-to-an-existing-event.bad.al.