IsHandled Extensibility Pattern

[Štěpán Dvořák (stedvo-kmits)]

Working title: IsHandled Extensibility Pattern

IsHandled Pattern: Missing Extensibility Preservation Rule

Context

The IsHandled pattern is a fundamental extensibility mechanism in Dynamics 365 Business Central.

It is:

• widely used in the base application
• consistently used in localization layers
• formally documented by Microsoft

This clearly indicates:

The IsHandled pattern is not going away.

---

Problem Statement

Current guidance around IsHandled focuses on correct usage and avoiding unintended overrides.

However, one critical aspect is missing:

What happens to extensibility after a subscriber sets IsHandled := true?

---

Observation

Across multiple real-world solutions, three recurring patterns appear:

1. Competing overrides → non-deterministic behavior
2. Monolithic override → no extensibility remains
3. Controlled override → correct behavior, but extensibility is terminated

All three share the same root problem:

The extensibility chain is terminated without replacement.

---

Root Cause

The IsHandled pattern introduces a hard execution boundary:

if IsHandled then
    exit;

When a subscriber sets:

IsHandled := true;

it prevents:

• base logic
• other subscribers
• further extension

---

Proposal: Extensibility Preservation Rule

New Rule

If a subscriber sets IsHandled := true, it must preserve extensibility by re-exposing alternative integration events.

---

Correct Implementation Pattern

Original

if InputRecordRef.Number() = Database::"Custom Table" then begin
    // custom logic
    IsHandled := true;
end;

Improved

if InputRecordRef.Number() = Database::"Custom Table" then begin
    OnBeforeCustomX(InputRecordRef);

    // custom logic

    OnAfterCustomX(InputRecordRef);

    IsHandled := true;
end;

---

Important Constraint

Extensibility must be added without changing the original execution boundary.

This means:

• Events MUST stay inside the same condition
• Original behavior MUST remain unchanged

---

Relation to Method Pattern

This proposal is inspired by the Method Pattern, but intentionally simplified.

Approach	Extensibility	Orchestration
Raw IsHandled	No	No
IsHandled + hooks	Yes	No
Method Pattern	Yes	Yes

This makes it a transitional pattern.

---

Why Not Replace IsHandled?

In real systems:

• IsHandled is deeply embedded
• Full refactoring is unrealistic

Therefore:

A minimal, compatible improvement is more effective than a full redesign.

---

Key Insight

The problem is not overriding behavior.

The problem is terminating extensibility without replacement.

---

Final Rule

Override is allowed.

Closing the system is not.

---

Conclusion

This is not a new pattern.

It is a minimal extraction of principles from the Method Pattern,
applied to the most widely used extensibility mechanism in Business Central.

The goal is simple:

Prevent creation of non-extensible code in an extensible platform.

[Chris (KOTRET)]

Why don't you just ignore the isHandled-parameter when subscribing to the event, if you want to extend the functionality?
The event-chain does not stop suddenly, just because one subscriber set the value of isHandled to true.

An improvement would be, if Microsoft would trigger an additional event before leaving the base function (whether or not there was a subscriber or the function was left executing base-apps' code).
This pattern would only work for the base-app (because otherwise you would be forced to add a dependency to the app, whose subscriber is called first - so no guarantee for success waiting for the app's event).

[Štěpán Dvořák (stedvo-kmits)]

I think this is actually highlighting a limitation of the IsHandled pattern itself, not of the proposal. The problematic scenarios are typically not in base app code,but in places where IsHandled is already used in external extensions:

• localizations
• utility apps
• third-party solutions

In those cases, the situation today is:
Extension A → IsHandled := true
Extension B → no entry point at all

What this proposal does is not introducing a new limitation, but reducing that one:

Extension A → IsHandled := true + exposes events
Extension B:
→ can depend → has an entry point
→ doesn't depend → same as today

So yes, it does not solve cross-extension extensibility completely.

But neither does the current pattern.
The key difference is:

Today → extensibility is always lost
With this approach → extensibility becomes possible when both sides agree

So I would not see this as creating a dead-end, but as avoiding one in cases where it would otherwise be inevitable.

[Chris (KOTRET)]

Extension B → no entry point at all

Repeating false claims often enough will not make this more true. This is just wrong.

Of course your subscriber will still get fired. And if you want to do extension-things, then do it!
One more time: isHandled set to true won't stop you from executing your code. You can check the value to determine if someone has reacted on that event and skip some code-paths.
You can even do your extension and still just not update isHandled to extend but do not stop the base-app-Code.

Problems only arise if you just want to add some functionality and then rely on the base-app-Code and there are some other subscribers that will prevent the base-app-Code from running.

[Chris (KOTRET)]

Maybe you can provide a real-world-scenario to work on? This could help when talking about a solution.

[Štěpán Dvořák (stedvo-kmits)]

I’m definitely open to the possibility that I’m missing something here — that’s exactly why I’m trying to break this down on concrete scenarios.

Let’s take a very simple case:

An extension intentionally bypasses validation using:
IsHandled := true;

Another extension wants to add additional validation or logging.

Even if the second extension respects IsHandled, the behavior still depends on execution order and on whether the flag was already set.

Deliberately ignoring IsHandled only works if you know the execution order and where the flag comes from — which you don’t.

So my question is:
how would you make this scenario deterministic and composable without introducing some form of explicit orchestration or re-exposed extensibility?

[Štěpán Dvořák (stedvo-kmits)]

This is not a theoretical scenario — it can be observed directly in Microsoft’s own localization code.

Please take a look at the extension “Fixed Asset Localization for Czech”, codeunit 31235 "FA Disposal Handler CZF", subscriber to
Codeunit::"FA Jnl.-Post Line", OnBeforePostDisposalEntry.

This is a full override using IsHandled := true, where the entire disposal logic (including posting and side effects) is executed inside the subscriber.

In this scenario, attaching another extension to the same original event does not provide a usable entry point.

Not because the event is not fired, but because the original execution path is no longer relevant, and the replacement logic does not expose any new integration points.

[Peter Conijn (PeterConijn)]

I fully agree. The if IsHandled then exit pattern is an inherently risky pattern. Microsoft have turned away from it and are also recommending avoiding the pattern (source) and they are absolutely right in that.

[Yahya Touil (yahyatouil-dev)]

Microsoft’s guidance on the IsHandled pattern makes a similar point: the main concern is that IsHandled can skip large parts of the original code path, meaning events inside that code may not be raised and other extensions can be affected.

For new code, positive/regular events are generally a better approach because they add extensibility without skipping existing logic. IsHandled should be kept to cases where there isn't a better option.

[Štěpán Dvořák (stedvo-kmits)]

Thanks for the reference and for taking the time to comment.
 
I fully agree with Microsoft's guidance and I am aware that IsHandled should generally be avoided when better extensibility mechanisms are available.
 
The aspect I was trying to explore is slightly different.
Most guidance focuses on the publisher side: how to design extensibility points. My focus was on the subscriber side. In many real-world scenarios, especially when extending existing Base App, localization, or other Microsoft applications, IsHandled is already the only available extensibility mechanism.
 
After the discussion, I would probably soften my original proposal to:
"If an extension replaces standard logic using IsHandled := true, it should consider exposing its own integration events."
 
The question I find interesting is not whether IsHandled should exist, but how to use it as responsibly as possible when it is already the only available extension point.

[Peter Conijn (PeterConijn)]

From that point of view, I do agree with you Štěpán Dvořák (@stedvo-kmits), and it is not necessarily limited to IsHandled patterns. If you subscribe to an event, you have no way of knowing which other apps might also be subscribed to it and we have control over the order in which subscribers are called. Adding your own publisher allows for slightly more predictable routing paths.