Language

IElementHandler<TVirtualView,TPlatformView> Interface

Definition

Defines a strongly typed, platform-neutral element handler contract.

generic <typename TVirtualView, typename TPlatformView>
 where TVirtualView : IElement where TPlatformView : classpublic interface class IElementHandler : Microsoft::Maui::IElementHandler
public interface IElementHandler<out TVirtualView,out TPlatformView> : Microsoft.Maui.IElementHandler where TVirtualView : IElement where TPlatformView : class
type IElementHandler<'VirtualView, 'PlatformView (requires 'VirtualView :> IElement and 'PlatformView : null)> = interface
    interface IElementHandler
Public Interface IElementHandler(Of Out TVirtualView, Out TPlatformView)
Implements IElementHandler

Type Parameters

TVirtualView

The cross-platform (virtual view) type this handler manages.

This type parameter is covariant. That is, you can use either the type you specified or any type that is more derived. For more information about covariance and contravariance, see Covariance and Contravariance in Generics.
TPlatformView

The native type this handler creates.

This type parameter is covariant. That is, you can use either the type you specified or any type that is more derived. For more information about covariance and contravariance, see Covariance and Contravariance in Generics.
Derived
Implements

Examples

// In an external platform backend, with a native type MAUI knows nothing about:
public class MyWindowHandler : ElementHandler<IWindow, MyNativeWindow>
{
    public MyWindowHandler() : base(WindowHandler.Mapper) { }
    protected override MyNativeWindow CreatePlatformElement() => new MyNativeWindow();
}

// Consumers match it platform-neutrally. The typed members below throw once the handler is
// disconnected, so guard on the nullable IElementHandler.PlatformView first.
if (window.Handler is { PlatformView: not null } handler &&
    handler is IElementHandler<IWindow, object> windowHandler)
{
    IWindow virtualView = windowHandler.VirtualView;
    object nativeWindow = windowHandler.PlatformView;
}

Remarks

The per-control handler interfaces such as IWindowHandler declare PlatformView using a using PlatformView = ... alias that resolves to a different native type for every target framework. That makes them impossible to implement from an external platform backend whose native types are not the ones .NET MAUI ships in the box: the compiler reports CS0738 (or CS9333 on the platform-neutral target framework) because the implementing member's return type does not match the alias exactly.

This interface has no such alias. Both type parameters are covariant, so a handler can be matched platform-neutrally by testing for IElementHandler<IWindow, object> regardless of which native type it actually creates.

ElementHandler<TVirtualView,TPlatformView> implements this interface, so any handler derived from it — in the box or in an external backend — satisfies the contract without writing any additional members.

Lifecycle. VirtualView and PlatformView are non-nullable here, matching the non-nullable properties on ElementHandler<TVirtualView,TPlatformView> that satisfy them — and those properties throw InvalidOperationException rather than returning null once the handler is disconnected. DisconnectHandler() clears the platform view before invoking the disconnect callback, so a handler is only guaranteed to have one between SetVirtualView(IElement) and DisconnectHandler(). The inherited VirtualView and PlatformView return null in exactly that state and never throw, so code that can run outside a connected window — teardown paths, weak-reference caches, diagnostics — should read those instead. Property and command mappers always run while the handler is connected and can use the typed members freely.

Properties

Name Description
MauiContext

Gets the .NET MAUI context associated with the element.

(Inherited from IElementHandler)
PlatformView

Gets the native view associated with the handler.

VirtualView

Gets the cross-platform virtual view associated with the handler.

Methods

Name Description
DisconnectHandler()

Disconnects the element handler from the element for clean up.

(Inherited from IElementHandler)
Invoke(String, Object)

Invokes the specified command on the element with the given arguments.

(Inherited from IElementHandler)
SetMauiContext(IMauiContext)

Sets the .NET MAUI context for the element handler.

(Inherited from IElementHandler)
SetVirtualView(IElement)

Sets the cross-platform virtual view associated with the handler.

(Inherited from IElementHandler)
UpdateValue(String)

Updates the value of the specified property on the handler.

(Inherited from IElementHandler)

Extension Methods

Name Description
GetRequiredService<T>(IElementHandler, Type)
GetRequiredService<T>(IElementHandler)
GetService<T>(IElementHandler, Type)
GetService<T>(IElementHandler)
GetServiceProvider(IElementHandler)
IsConnected(IElementHandler)

Applies to