How to: event handlers

Goal: react to a stock event without modifying the class that raises it — a SubscribesTo handler that builds clean.

Time: ~10 minutes · Requires: a D365 VM for the build step.

Prerequisites

• A custom model referencing the target class’s model.
• The delegate identified on the target class (that’s the hook you subscribe to — see the gotcha below before assuming it exists).

Steps

1. Find the target class/delegate; right-click → New X++ Object → event handler.
2. Review the scaffold — a SubscribesTo attribute wiring your handler method to the target delegate, in a new class.
3. Fill in the handler body.
4. Save, then Build Model (Ctrl+B).

EDITOR · EVENT HANDLER SCAFFOLDReal UI capture pendingxpp-event-scaffold

The honest gotcha (learn it once)

If the delegate you named doesn’t exist on the target class yet, the first build fails with the compiler’s own message — delegate '…' does not exist. That’s the real xppc talking, identical to Visual Studio, and it’s doing you a favor: the subscription and the delegate must both exist. Add the delegate declaration to the target class (via an extension class), rebuild — green.

BUILD · MISSING-DELEGATE DIAGNOSTICReal UI capture pendingxpp-event-build-error

Verify it worked

• After the delegate exists: build 0/0; raising the event runs your handler.
• The Problems panel shows no best-practice warnings on your handler class.

If it goes wrong

• Build says the delegate doesn’t exist — read the section above; this is the normal path, not a scaffolding bug.
• Handler never fires at runtime — the SubscribesTo arguments must name the class and delegate exactly; re-generate rather than hand-editing the attribute.

Next: CoC extension classes for method-level wrapping · the first customization tutorial for the full arc.