[net11.0] Trimmable element handlers

docs/design/HandlerResolution.md

@@ -3,7 +3,20 @@ Handler Resolution
 
 # Introduction
 
-Handlers are the platform components used to render a cross platform `View` on the screen. Every platform registers a handler against a .NET Maui type.  
+Handlers are the platform components used to render a cross-platform `View` on the screen. Each view type is associated with a handler that knows how to create and manage the corresponding platform-native control.
+
+## Declaring a Handler with `[ElementHandler]`
+
+Most built-in .NET MAUI views declare their handler using the `[ElementHandler]` attribute directly on the view class:
+
+```csharp
+[ElementHandler(typeof(ButtonHandler))]
+public partial class Button : View, IButton { ... }
+```
+
+This is the primary mechanism for associating views with handlers. It is trimmer-safe and AOT-friendly because the handler type is statically referenced.
+
+The attribute is declared with `Inherited = false`, so each view type must explicitly declare it. However, `MauiHandlersFactory` walks the type's base class hierarchy (`Type.BaseType`) when looking for the attribute, so a base class attribute acts as a fallback for derived types that don't declare their own.
 
 ## Registering a Handler in Code
 
@@ -14,6 +27,31 @@ builder.ConfigureMauiHandlers(handlers =>
        }
 ```
 
+DI registration should only be used to override an existing `[ElementHandler]` declaration or when the element type is an interface (e.g., `IScrollView`). DI-registered handlers take priority over `[ElementHandler]` attributes when the registered type is assignable from the requested element type.
+
+## Resolution Order
+
+Both `MauiHandlersFactory.GetHandler(Type)` and `MauiHandlersFactory.GetHandlerType(Type)` follow the same resolution order:
+
+1. **Exact DI registration** — checks if a handler was registered for this exact type via `AddHandler`
+2. **Assignable DI registration** — uses `RegisteredHandlerServiceTypeSet` to find the best matching concrete or interface registration (e.g., a handler registered for `Button` matches a derived `FancyButton`, and a handler registered for `IScrollView` matches a `ScrollView` instance)
+3. **`[ElementHandler]` attribute** — walks the type's base class hierarchy looking for the attribute
+4. **`IContentView` fallback** — returns `ContentViewHandler` for any `IContentView` implementation
+5. **`GetHandlerType` returns `null`** / **`GetHandler` throws `HandlerNotFoundException`** — if none of the above matched
+
+### Handler Instantiation
+
+How a handler instance is created depends on how it was resolved:
+
+- **DI-registered handlers** (steps 1 & 2): Instantiated through `MauiFactory.GetService()`, which uses `Activator.CreateInstance` on the registered `ImplementationType`, or invokes the `ImplementationFactory` delegate if one was provided.
+- **`[ElementHandler]` attribute** (step 3): Instantiated directly via `Activator.CreateInstance` — no DI involvement.
+- **Fallback in `ElementExtensions.ToHandler()`**: When `Activator.CreateInstance` fails with a `MissingMethodException` (e.g., the handler requires constructor parameters), `ActivatorUtilities.CreateInstance` is used instead, which supports constructor injection from the DI container.
+
+> **Note:** Handlers registered via `[ElementHandler]` must have a public parameterless constructor.
+> They are instantiated with `Activator.CreateInstance()`, not through the DI container.
+> The `ActivatorUtilities.CreateInstance()` fallback only applies to DI-registered handlers
+> resolved through `ElementExtensions.ToHandler()`.
+
 ## Types used in the resolution of Handlers to Views
 
 ### `MauiFactory`
@@ -34,8 +72,7 @@ public class MauiHandlersFactory : MauiFactory, IMauiHandlersFactory
 - `MauiFactory` has support for `ctor` resolution but we currently have it disabled in all cases.
   - Handlers will currently attempt to instantiate through [Extensions.DependencyInjection.ActivatorUtilities.CreateInstance](https://github.com/dotnet/maui/blob/cc53f0979baf5d6bb8a5d6bf84b64f3cf591c56f/src/Core/src/Platform/ElementExtensions.cs#L34 ) if a default constructor hasn't been created. So the ctor resolution feature of `MauiFactory` probably doesn't have any currently useful purpose.
 - `MauiFactory` currently doesn't support Scoped Services which is the main reason why we switched to `Ms.Ext.DI` for our main implementation. .NET MAUI Blazor requires Scoped Services and we've started using Scoped Services as well for multi-window.
-- `MauiFactory` retrieves all base types from the requested type and all implemented interfaces. It first iterates over base types and then if nothing is found it loops through the interfaces. The interface behavior currently leads to some odd behavior because everything implements `IView`. This means that if a handler isn't registered then `MauiFactory` just returns a random handler because technically every single handler is registered against a cross platform view that implements`IView`. https://github.com/dotnet/maui/issues/1298
-  - We should probably remove the interface matching part of `MauiFactory` 
+- `MauiFactory` retrieves the handler type registered for the requested type. Interface-based registration matching is now handled by `RegisteredHandlerServiceTypeSet`, which finds the most specific matching interface to avoid ambiguity (the old behavior of matching any `IView`-implementing interface has been fixed — see https://github.com/dotnet/maui/issues/1298).
 
 ### IMauiHandlersFactory
 
@@ -54,7 +91,6 @@ public interface IMauiHandlersFactory : IMauiFactory
     Type? GetHandlerType(Type iview);
     IElementHandler? GetHandler(Type type);
     IElementHandler? GetHandler<T>() where T : IElement;
-    IMauiHandlersCollection GetCollection();
 }
 ```
 

src/Controls/samples/Controls.Sample/Controls/BordelessEntry/BordelessEntryServiceBuilder.cs

@@ -57,7 +57,9 @@ public void Initialize(IServiceProvider services)
 				}
 			}
 
+#pragma warning disable CS0618 // Obsolete
 			BordelessEntryServiceBuilder.HandlersCollection ??= services.GetRequiredService<IMauiHandlersFactory>().GetCollection();
+#pragma warning restore CS0618
 
 			if (BordelessEntryServiceBuilder.PendingHandlers.Count > 0)
 			{

src/Controls/src/Core/ActivityIndicator/ActivityIndicator.cs

@@ -1,8 +1,10 @@
 #nullable disable
 using System;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 
 using Microsoft.Maui.Graphics;
+using Microsoft.Maui.Handlers;
 
 namespace Microsoft.Maui.Controls
 {
@@ -13,8 +15,27 @@ namespace Microsoft.Maui.Controls
 	/// This control gives a visual clue to the user that something is happening, without information about its progress.
 	/// </remarks>
 	[DebuggerDisplay("{GetDebuggerDisplay(), nq}")]
+#if ANDROID
+	[ActivityIndicatorHandler]
+#else
+	[ElementHandler(typeof(ActivityIndicatorHandler))]
+#endif
 	public partial class ActivityIndicator : View, IColorElement, IElementConfiguration<ActivityIndicator>, IActivityIndicator
 	{
+#if ANDROID
+		internal sealed class ActivityIndicatorHandlerAttribute : ElementHandlerAttribute
+		{
+			[return: DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)]
+			public override Type GetHandlerType()
+			{
+				if (RuntimeFeature.IsMaterial3Enabled)
+					return typeof(ActivityIndicatorHandler2);
+
+				return typeof(ActivityIndicatorHandler);
+			}
+		}
+#endif
+
 		/// <summary>Bindable property for <see cref="IsRunning"/>.</summary>
 		public static readonly BindableProperty IsRunningProperty = BindableProperty.Create(nameof(IsRunning), typeof(bool), typeof(ActivityIndicator), default(bool));
 
@@ -63,4 +84,4 @@ private protected override string GetDebuggerDisplay()
 			return $"{base.GetDebuggerDisplay()}, {debugText}";
 		}
 	}
-}
+}

src/Controls/src/Core/Application/Application.Mapper.cs

@@ -1,13 +1,20 @@
 #nullable disable
 using System;
+using System.Threading;
 using Microsoft.Maui.Controls.Compatibility;
 
 namespace Microsoft.Maui.Controls
 {
 	public partial class Application
 	{
-		internal static new void RemapForControls()
+		static int s_remappedForControls;
+		internal override void RemapForControls()
 		{
+			if (Interlocked.CompareExchange(ref s_remappedForControls, 1, 0) != 0)
+				return;
+
+			base.RemapForControls();
+
 			// Adjust the mappings to preserve Controls.Application legacy behaviors
 #if ANDROID
 			// There is also a mapper on Window for this property since this property is relevant at the window level for

src/Controls/src/Core/Application/Application.cs

@@ -18,6 +18,7 @@ namespace Microsoft.Maui.Controls
 	/// <summary>
 	/// Represents the main application class that provides lifecycle management, resources, and theming.
 	/// </summary>
+	[ElementHandler(typeof(ApplicationHandler))]
 	public partial class Application : Element, IResourcesProvider, IApplicationController, IElementConfiguration<Application>, IVisualTreeElement, IApplication
 	{
 		readonly WeakEventManager _weakEventManager = new WeakEventManager();

src/Controls/src/Core/Border/Border.cs

@@ -6,6 +6,7 @@
 using Microsoft.Maui.Controls.Shapes;
 using Microsoft.Maui.Graphics;
 using Microsoft.Maui.Layouts;
+using Microsoft.Maui.Handlers;
 
 namespace Microsoft.Maui.Controls
 {
@@ -17,6 +18,7 @@ namespace Microsoft.Maui.Controls
 	/// background, shape, padding, and more to create visually rich containers.
 	/// </remarks>
 	[ContentProperty(nameof(Content))]
+	[ElementHandler(typeof(BorderHandler))]
 	public class Border : View, IContentView, IBorderView, IPaddingElement, ISafeAreaElement, ISafeAreaView2
 	{
 		float[]? _strokeDashPattern;

src/Controls/src/Core/BoxView/BoxView.cs

@@ -2,12 +2,14 @@
 using System;
 using System.Runtime.CompilerServices;
 using Microsoft.Maui.Graphics;
+using Microsoft.Maui.Controls.Handlers;
 
 namespace Microsoft.Maui.Controls
 {
 	/// <summary>
 	/// A <see cref="View" /> used to draw a solid colored rectangle.
 	/// </summary>
+	[ElementHandler(typeof(BoxViewHandler))]
 	public partial class BoxView : View, IColorElement, ICornerElement, IElementConfiguration<BoxView>, IShapeView, IShape
 	{
 		WeakBrushChangedProxy _fillProxy = null;

src/Controls/src/Core/Button/Button.Mapper.cs

@@ -1,6 +1,6 @@
 #nullable disable
 using System;
-using System.Collections.Generic;
+using System.Threading;
 using System.Text;
 using Microsoft.Maui.Controls.Compatibility;
 using Microsoft.Maui.Controls.Platform;
@@ -11,9 +11,14 @@ namespace Microsoft.Maui.Controls
 	public partial class Button
 	{
 		// IButton does not include the ContentType property, so we map it here to handle Image Positioning
-
-		internal new static void RemapForControls()
+		static int s_remappedForControls;
+		internal override void RemapForControls()
 		{
+			if (Interlocked.CompareExchange(ref s_remappedForControls, 1, 0) != 0)
+				return;
+
+			base.RemapForControls();
+
 			ButtonHandler.Mapper.ReplaceMapping<Button, IButtonHandler>(nameof(ContentLayout), MapContentLayout);
 #if IOS
 			ButtonHandler.Mapper.ReplaceMapping<Button, IButtonHandler>(nameof(Padding), MapPadding);

src/Controls/src/Core/Button/Button.cs

@@ -6,6 +6,7 @@
 using System.Runtime.CompilerServices;
 using System.Windows.Input;
 using Microsoft.Maui.Controls.Internals;
+using Microsoft.Maui.Handlers;
 
 using Microsoft.Maui.Graphics;
 
@@ -15,6 +16,7 @@ namespace Microsoft.Maui.Controls
 	/// A button <see cref="View" /> that reacts to touch events.
 	/// </summary>
 	[DebuggerDisplay("{GetDebuggerDisplay(), nq}")]
+	[ElementHandler(typeof(ButtonHandler))]
 	public partial class Button : View, IFontElement, ITextElement, IBorderElement, IButtonController, IElementConfiguration<Button>, IPaddingElement, IImageController, IViewController, IButtonElement, ICommandElement, IImageElement, IButton, ITextButton, IImageButton
 	{
 		const double DefaultSpacing = 10;

src/Controls/src/Core/Cells/Cell.cs

@@ -12,6 +12,11 @@ namespace Microsoft.Maui.Controls
 {
 	// Don't add IElementConfiguration<Cell> because it kills performance on UWP structures that use Cells
 	/// <summary>Provides base class and capabilities for all Microsoft.Maui.Controls cells. Cells are elements meant to be added to <see cref="Microsoft.Maui.Controls.ListView"/> or <see cref="Microsoft.Maui.Controls.TableView"/>.</summary>
+#if WINDOWS || ANDROID || IOS || MACCATALYST
+#pragma warning disable CS0618 // Type or member is obsolete
+	[ElementHandler(typeof(Handlers.Compatibility.CellRenderer))]
+#pragma warning restore CS0618 // Type or member is obsolete
+#endif
 	public abstract class Cell : Element, ICellController, IFlowDirectionController, IPropertyPropagationController, IVisualController, IWindowController, IVisualTreeElement
 	{
 		/// <summary>The default height of cells.</summary>

src/Controls/src/Core/Cells/EntryCell.cs

@@ -7,6 +7,11 @@ namespace Microsoft.Maui.Controls
 {
 	/// <summary>A <see cref="Microsoft.Maui.Controls.Cell"/> with a label and a single line text entry field.</summary>
 	[Obsolete("The controls which use EntryCell (ListView and TableView) are obsolete. Please use CollectionView instead.")]
+#if WINDOWS || ANDROID || IOS || MACCATALYST
+#pragma warning disable CS0618 // Type or member is obsolete
+	[ElementHandler(typeof(Handlers.Compatibility.EntryCellRenderer))]
+#pragma warning restore CS0618 // Type or member is obsolete
+#endif
 	public class EntryCell : Cell, ITextAlignmentElement, IEntryCellController, ITextAlignment
 	{
 		/// <summary>Bindable property for <see cref="Text"/>.</summary>

src/Controls/src/Core/Cells/ImageCell.cs

@@ -5,6 +5,9 @@ namespace Microsoft.Maui.Controls
 {
 	/// <summary>A <see cref="Microsoft.Maui.Controls.TextCell"/> that has an image.</summary>
 	[Obsolete("The controls which use ImageCell (ListView and TableView) are obsolete. Please use CollectionView instead.")]
+#if WINDOWS || ANDROID || IOS || MACCATALYST
+	[ElementHandler(typeof(Handlers.Compatibility.ImageCellRenderer))]
+#endif
 	public class ImageCell : TextCell
 	{
 		/// <summary>Bindable property for <see cref="ImageSource"/>.</summary>

src/Controls/src/Core/Cells/SwitchCell.cs

@@ -6,6 +6,11 @@ namespace Microsoft.Maui.Controls
 {
 	/// <summary>A <see cref="Microsoft.Maui.Controls.Cell"/> with a label and an on/off switch.</summary>
 	[Obsolete("The controls which use SwitchCell (ListView and TableView) are obsolete. Please use CollectionView instead.")]
+#if WINDOWS || ANDROID || IOS || MACCATALYST
+#pragma warning disable CS0618 // Type or member is obsolete
+	[ElementHandler(typeof(Handlers.Compatibility.SwitchCellRenderer))]
+#pragma warning restore CS0618 // Type or member is obsolete
+#endif
 	public class SwitchCell : Cell
 	{
 		/// <summary>Bindable property for <see cref="On"/>.</summary>

src/Controls/src/Core/Cells/TextCell.cs

@@ -8,6 +8,11 @@ namespace Microsoft.Maui.Controls
 {
 	/// <summary>A <see cref="Microsoft.Maui.Controls.Cell"/> with primary <see cref="Microsoft.Maui.Controls.TextCell.Text"/>  and <see cref="Microsoft.Maui.Controls.TextCell.Detail"/> text.</summary>
 	[Obsolete("The controls which use TextCell (ListView and TableView) are obsolete. Please use CollectionView instead.")]
+#if WINDOWS || ANDROID || IOS || MACCATALYST
+#pragma warning disable CS0618 // Type or member is obsolete
+	[ElementHandler(typeof(Handlers.Compatibility.TextCellRenderer))]
+#pragma warning restore CS0618 // Type or member is obsolete
+#endif
 	public class TextCell : Cell, ICommandElement
 	{
 		/// <summary>Bindable property for <see cref="Command"/>.</summary>

src/Controls/src/Core/Cells/ViewCell.cs

@@ -8,6 +8,11 @@ namespace Microsoft.Maui.Controls
 	/// <summary>A <see cref="Microsoft.Maui.Controls.Cell"/> containing a developer-defined <see cref="Microsoft.Maui.Controls.View"/>.</summary>
 	[Obsolete("The controls which use ViewCell (ListView and TableView) are obsolete. Please use CollectionView instead.")]
 	[ContentProperty("View")]
+#if WINDOWS || IOS || MACCATALYST || ANDROID
+#pragma warning disable CS0618 // Type or member is obsolete
+	[ElementHandler(typeof(Handlers.Compatibility.ViewCellRenderer))]
+#pragma warning restore CS0618 // Type or member is obsolete
+#endif
 	public class ViewCell : Cell
 	{
 		View _view;

src/Controls/src/Core/CheckBox/CheckBox.Mapper.cs

@@ -1,6 +1,6 @@
 #nullable disable
 using System;
-using System.Collections.Generic;
+using System.Threading;
 using System.Text;
 using Microsoft.Maui.Controls.Platform;
 using Microsoft.Maui.Handlers;
@@ -14,12 +14,15 @@ static CheckBox()
 			// Register dependency: Command depends on CommandParameter for CanExecute evaluation
 			// See https://github.com/dotnet/maui/issues/31939
 			CommandProperty.DependsOn(CommandParameterProperty);
-			RemapForControls();
 		}
 
-		private new static void RemapForControls()
+		static int s_remappedForControls;
+		internal override void RemapForControls()
 		{
-			VisualElement.RemapForControls();
+			if (Interlocked.CompareExchange(ref s_remappedForControls, 1, 0) != 0)
+				return;
+
+			base.RemapForControls();
 
 			CheckBoxHandler.Mapper.ReplaceMapping<ICheckBox, ICheckBoxHandler>(nameof(Color), MapColor);
 		}

src/Controls/src/Core/CheckBox/CheckBox.cs

@@ -16,6 +16,7 @@ namespace Microsoft.Maui.Controls
 	/// Use the <see cref="IsChecked"/> property to determine or set the state.
 	/// </remarks>
 	[DebuggerDisplay("{GetDebuggerDisplay(), nq}")]
+	[ElementHandler(typeof(CheckBoxHandler))]
 	public partial class CheckBox : View, IElementConfiguration<CheckBox>, IBorderElement, IColorElement, ICheckBox, ICommandElement
 	{
 		readonly Lazy<PlatformConfigurationRegistry<CheckBox>> _platformConfigurationRegistry;

src/Controls/src/Core/ContentPage/ContentPage.Mapper.cs

@@ -1,6 +1,6 @@
 #nullable disable
 using System;
-using System.Collections.Generic;
+using System.Threading;
 using System.Text;
 using Microsoft.Maui.Controls.Platform;
 using Microsoft.Maui.Handlers;
@@ -9,8 +9,14 @@ namespace Microsoft.Maui.Controls
 {
 	public partial class ContentPage
 	{
-		internal new static void RemapForControls()
+		static int s_remappedForControls;
+		internal override void RemapForControls()
 		{
+			if (Interlocked.CompareExchange(ref s_remappedForControls, 1, 0) != 0)
+				return;
+
+			base.RemapForControls();
+
 			PageHandler.Mapper.ReplaceMapping<ContentPage, IPageHandler>(nameof(ContentPage.HideSoftInputOnTapped), MapHideSoftInputOnTapped);
 #if IOS
 			PageHandler.Mapper.ReplaceMapping<ContentPage, IPageHandler>(PlatformConfiguration.iOSSpecific.Page.PrefersHomeIndicatorAutoHiddenProperty.PropertyName, MapPrefersHomeIndicatorAutoHidden);

src/Controls/src/Core/ContentView/ContentView.cs

@@ -2,6 +2,7 @@
 using System.Diagnostics;
 using Microsoft.Maui;
 using Microsoft.Maui.Graphics;
+using Microsoft.Maui.Handlers;
 using Microsoft.Maui.Layouts;
 
 namespace Microsoft.Maui.Controls
@@ -15,6 +16,7 @@ namespace Microsoft.Maui.Controls
 	/// </remarks>
 	[ContentProperty("Content")]
 	[DebuggerDisplay("{GetDebuggerDisplay(), nq}")]
+	[ElementHandler(typeof(ContentViewHandler))]
 	public partial class ContentView : TemplatedView, IContentView, ISafeAreaView2, ISafeAreaElement
 	{
 		/// <summary>Bindable property for <see cref="Content"/>.</summary>

src/Controls/src/Core/DatePicker/DatePicker.Mapper.cs

@@ -1,13 +1,20 @@
 #nullable disable
 using System;
+using System.Threading;
 using Microsoft.Maui.Controls.Compatibility;
 
 namespace Microsoft.Maui.Controls
 {
 	public partial class DatePicker
 	{
-		internal static new void RemapForControls()
+		static int s_remappedForControls;
+		internal override void RemapForControls()
 		{
+			if (Interlocked.CompareExchange(ref s_remappedForControls, 1, 0) != 0)
+				return;
+
+			base.RemapForControls();
+
 			// Adjust the mappings to preserve Controls.DatePicker legacy behaviors
 #if IOS
 			DatePickerHandler.Mapper.ReplaceMapping<DatePicker, IDatePickerHandler>(PlatformConfiguration.iOSSpecific.DatePicker.UpdateModeProperty.PropertyName, MapUpdateMode);