Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-05 06:36:55 +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 2b5550c346
Some checks failed
Validate knowledge index / validate-index (push) Has been cancelled
Details
Validate AL review fixtures / validate-review-fixtures (push) Has been cancelled
Details
Validate frontmatter and structure / validate (push) Has been cancelled
Details
Improve partner onboarding and documentation navigation (#174) 
Lead with a complete plugin quick start and add task-oriented usage, troubleshooting, customization, and contribution guides. Preserve the broader plugin framing, correct conflicting contract guidance, support Agents folder reviews, and align repository validation. Convert existing sample references to clickable links without changing knowledge rules.

Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
2026-09-09 17:31:03 +02:00

1.8 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.