maui-custom-handlers

MAUI Custom Handlers

Use this skill when a MAUI visual element needs native platform behavior. Keep handlers focused on views. Route non-visual APIs to platform services and route large native SDK surfaces to slim bindings.

Response Checklist

• Use handler language explicitly: AppendToMapping, PropertyMapper, CommandMapper, and ViewHandler.
• For renderer migration, map subscription/setup to ConnectHandler and cleanup to DisconnectHandler.
• Keep mapper changes scoped to the intended control type, not all controls.

Decision Tree

Workflow

1. Inspect the target frameworks and existing UI architecture.

2. Define the cross-platform view API first: bindable properties, commands, and events that make sense to app code.

3. Choose global mapper customization, subclass-scoped mapper customization, or a full custom handler.

4. Put native implementation in partial handler files or #if guarded blocks for the exact platforms supported by the project.

5. Register handlers in MauiProgram.cs:

   builder.ConfigureMauiHandlers(handlers =>
   {
       handlers.AddHandler<CameraPreview, CameraPreviewHandler>();
   });
   

6. Use ConnectHandler to subscribe native events and allocate native resources.

7. Use DisconnectHandler to unsubscribe, stop timers, clear delegates, and dispose only native objects owned by the handler. Call base.DisconnectHandler(platformView) as the final statement so the base handler clears its own state.

8. Build each targeted platform and verify the behavior with UI automation or DevFlow when available.