[net11.0] Trimmable element handlers by simonrozsival · Pull Request #29952 · dotnet/maui

simonrozsival · 2025-06-12T07:43:43Z

This is a follow-up to #28357

Summary

All built-in controls now use [ElementHandler] attributes instead of DI registration for handler resolution. This removes the need for AppHostBuilderExtensions.AddControlsHandlers() and makes handler associations visible at the type level, improving trimmability.

Key changes

`[ElementHandler]` attribute

New public ElementHandlerAttribute on view types (e.g., [ElementHandler(typeof(ButtonHandler))]) declaratively associates a view with its handler
Inherited = false — each concrete type that needs a different handler must declare its own attribute
The attribute walks the BaseType chain at resolution time, so derived types without their own attribute inherit the nearest ancestor's handler

Handler resolution in `MauiHandlersFactory`

Both GetHandler(Type) and GetHandlerType(Type) follow the same 4-step resolution order:

Exact DI registration — if the concrete type (e.g., typeof(Button)) is registered via AddHandler<Button, MyButtonHandler>(), that wins. DI-registered handlers are instantiated through MauiFactory.GetService().
[ElementHandler] attribute — walk the type's BaseType chain looking for the attribute. Attribute-based handlers are instantiated via Activator.CreateInstance().
Interface-based DI registration — map the concrete type to its virtual view interface (e.g., Button → IButton) using RegisteredHandlerServiceTypeSet, then look up the interface in DI. This is the path for third-party/custom handler overrides registered via AddHandler<IButton, ...>().
IContentView fallback — if the type implements IContentView, return ContentViewHandler.

GetHandler() is the primary API — it returns an instantiated IElementHandler. GetHandlerType() returns only the Type and is used by code that needs to compare handler types without instantiating them (e.g., Compatibility layer cell renderers).

`ElementExtensions.ToHandler()` / `SetHandler()`

These methods call GetHandler() directly. When a handler requires constructor parameters (no parameterless constructor), ToHandler() catches the MissingMethodException and falls back to ActivatorUtilities.CreateInstance() with DI injection. This fallback path is cached per-type in a HashSet<Type> to avoid repeated exception throwing.

Mapper remapping via static constructors

Controls-layer types override Core-layer mapper entries in their static constructors
Base-class static constructor ordering is enforced via RemappingHelper.EnsureBaseTypeRemapped(), which accesses a s_forceStaticConstructor field on the parent type to force the runtime to run the parent's static constructor first
RemappingDebugHelper.AssertBaseClassForRemapping (DEBUG-only) validates that no intermediate type in the hierarchy is accidentally skipped

Cleanup

Removed IElementHandlerWithAndroidContext interface and ElementHandlerWithAndroidContextAttribute
Removed dead RemapForControls(this MauiAppBuilder) extension method and old RemapForControls()/RemapIfNeeded() pattern
Fixed Slider not having a static constructor (was only called explicitly from the removed extension method)
Restored IMauiHandlersFactory.GetHandler() to its original signature (GetHandler(Type) / GetHandler<T>()) — no longer requires IMauiContext parameter
Removed unused MauiContext/HandlersContextStub declarations from tests and benchmarks

Copilot

Pull Request Overview

This PR transitions built-in controls from DI registration to using [ElementHandler] attributes, introduces IElementHandlerWithAndroidContext<T> for Android renderers, and adds a new MSBuild property to toggle CSS support.

Apply [ElementHandler] to core controls and cells instead of DI
Introduce IElementHandlerWithAndroidContext<T> and CreateHandler(Context) on Android renderers
Add MauiCssEnabled MSBuild property and corresponding runtime host configuration

Reviewed Changes

Copilot reviewed 120 out of 120 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Controls/src/Core/ContentPage/ContentPage.Mapper.cs	Added static ctor calling `RemapForControls` and `VisualElement.RemapIfNeeded`
src/Controls/src/Core/Compatibility/Handlers/TableView/Android/TableViewRenderer.cs	Implemented `IElementHandlerWithAndroidContext<TableViewRenderer>` and `CreateHandler`
src/Controls/src/Core/Compatibility/Handlers/ListView/Android/ListViewRenderer.cs	Implemented `IElementHandlerWithAndroidContext<ListViewRenderer>` and `CreateHandler`
src/Controls/src/Core/Compatibility/Handlers/Android/FrameRenderer.cs	Implemented `IElementHandlerWithAndroidContext<FrameRenderer>` and `CreateHandler`
src/Controls/src/Core/Cells/*.cs	Added `[ElementHandler<...>]` attributes for compatibility cell renderers
src/Controls/src/Core/Button/Button.cs	Added `[ElementHandler<ButtonHandler>]`
src/Controls/src/Core//.Mapper.cs	Added static ctors calling `RemapForControls` / `RemapIfNeeded`
src/Controls/src/Build.Tasks/nuget/.../Microsoft.Maui.Controls.targets	Added `MauiCssEnabled` property and runtime host configuration option
src/Compatibility/Core/src/{iOS,Android}/Platform.cs	Updated `GetHandler` calls to pass `MauiContext`

Comments suppressed due to low confidence (1)

src/Controls/src/Build.Tasks/nuget/buildTransitive/netstandard2.0/Microsoft.Maui.Controls.targets:240

Added the MauiCssEnabled build property but no corresponding public documentation under /docs/; please update the XML docs to describe this new feature.

<MauiCssEnabled Condition="'$(MauiCssEnabled)' == '' and '@(MauiCss->Count())' == '0'">false</MauiCssEnabled>

src/Controls/src/Core/Compatibility/Handlers/TableView/Android/TableViewRenderer.cs

src/Controls/src/Core/Compatibility/Handlers/ListView/Android/ListViewRenderer.cs

src/Controls/src/Core/Compatibility/Handlers/Android/FrameRenderer.cs

src/Core/src/RuntimeFeature.cs

mattleibow · 2025-06-17T15:11:42Z

/azp run

azure-pipelines · 2025-06-17T15:11:49Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

simonrozsival · 2025-11-25T16:24:08Z

@copilot there are merge conflicts in this branch. please resolve them. When you're done, write summary of what this PR does and what functionality is missing to fully convert the "old" way of implementing handlers to the "new" way.

Copilot · 2025-11-25T16:24:20Z

@simonrozsival I've opened a new pull request, #32861, to work on those changes. Once the pull request is ready, I'll request review from you.

simonrozsival · 2025-11-25T16:25:08Z

@copilot oops, try now!

Copilot · 2025-11-25T16:25:24Z

@simonrozsival I've opened a new pull request, #32862, to work on those changes. Once the pull request is ready, I'll request review from you.

simonrozsival · 2025-12-01T10:54:02Z

@copilot there are several errors popping up:

src\Controls\src\Core\Shell\Shell.cs(29,25): Error CS0246: The type or namespace name 'ShellHandler' could not be found (are you missing a using directive or an assembly reference?)
src\Controls\src\Core\Shell\ShellItem.cs(18,25): Error CS0246: The type or namespace name 'ShellItemHandler' could not be found (are you missing a using directive or an assembly reference?)
buildtasks/Microsoft.Maui.Controls.Build.Tasks.After.targets(15,3): error MSB4024: The imported project file "/mnt/vss/_work/1/s/.buildtasks/Microsoft.Maui.Controls.targets" could not be loaded. Name cannot begin with the '<' character, hexadecimal value 0x3C. Line 325, position 2. [/mnt/vss/_work/1/s/src/BlazorWebView/tests/DeviceTests/MauiBlazorWebView.DeviceTests.csproj]

Fix them and make sure the product can be built.

Copilot · 2025-12-01T10:54:15Z

@simonrozsival I've opened a new pull request, #32933, to work on those changes. Once the pull request is ready, I'll request review from you.

albyrock87 · 2026-02-20T21:54:45Z

It's not clear to me @simonrozsival how one can create their own Button handler.
Would they still use the DI?
If not, how can the system know which one to use? (The MAUI one or the custom one)

Edit: yes it seems DI win, thanks!

So this is basically a feature for library authors to make their handlers trimmable.

simonrozsival · 2026-02-20T22:18:56Z

@albyrock87 exactly. If you don't use webview in your app, there should be no webview related code in the app.

This change should be as transparent as possible. Any custom handler registered via DI should still work.

github-actions · 2026-02-27T15:29:01Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 29952

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 29952"

simonrozsival · 2026-03-18T09:35:41Z

/azp run maui-pr-devicetests,maui-pr-uitests

azure-pipelines · 2026-03-18T09:36:00Z

Azure Pipelines successfully started running 2 pipeline(s).

simonrozsival · 2026-03-18T12:14:38Z

/azp run maui-pr-devicetests,maui-pr-uitests

azure-pipelines · 2026-03-18T12:14:54Z

Azure Pipelines successfully started running 2 pipeline(s).

simonrozsival · 2026-03-18T13:25:33Z

/azp run maui-pr,maui-pr-devicetests,maui-pr-uitests

azure-pipelines · 2026-03-18T13:26:04Z

Azure Pipelines successfully started running 3 pipeline(s).

simonrozsival · 2026-03-20T08:27:33Z

/azp run maui-pr-devicetests,maui-pr-uitests

azure-pipelines · 2026-03-20T08:27:52Z

Azure Pipelines successfully started running 2 pipeline(s).

simonrozsival · 2026-03-20T10:37:50Z

@jfversluis @mattleibow could you please have a look at this PR and let me know what you think about it? could we merge this into net11.0 soon?

### Description of Change This PR will allow trimming CSS-related code and default styles when there are no CSS stylesheets used in the MAUI app. - When `@(MauiCss)` item is added, the CSS feature is enabled - When the app does not have any `@(MauiCss)` but devs want to use `Style.Parse` to parse styles at runtime, they must enable `$(MauiCssEnabled)=true` Most of the changes in this PR are around moving assembly-level attributes into a local list. This will allow us to shave of some unnecessary code from most apps: ```c# // before [assembly: StyleProperty("background-color", typeof(VisualElement), nameof(VisualElement.BackgroundColorProperty))] // after new StylePropertyAttribute("background-color", typeof(VisualElement), nameof(VisualElement.BackgroundColorProperty)), ``` Related to #29952 --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

simonrozsival · 2026-03-31T07:11:17Z

/azp run maui-pr-devicetests,maui-pr-uitests

azure-pipelines · 2026-03-31T07:11:25Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

Squashed for clean rebase onto net11.0.

Handlers resolved via [ElementHandler] attribute use Activator.CreateInstance(), not ActivatorUtilities. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add [DynamicallyAccessedMembers(PublicConstructors)] to the 'handlerType' out parameter so it satisfies the return annotation on GetHandlerType(). This fixes NETSDK1144 build failures in RunOniOS_MauiReleaseTrimFull. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The method is now a no-op, and warnings-as-errors (CS0618) breaks the device test build on CI. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Two root cause bugs in [ElementHandler] attribute placement: 1. TabbedPage on iOS/MacCatalyst incorrectly used NavigationRenderer instead of TabbedRenderer. This caused TabbedPage to be treated as a NavigationPage, leading to crashes on iOS/Mac. 2. ShellItem's [ElementHandler] attribute was placed on FlyoutItem (a derived class) instead of ShellItem (the base class). Since TryGetElementHandlerAttribute walks the base type chain, TabBar (which also inherits from ShellItem but not from FlyoutItem) could not resolve its handler on Windows/Tizen, causing Shell test crashes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

simonrozsival · 2026-03-31T07:53:23Z

/azp run maui-pr,maui-pr-devicetests,maui-pr-uitests

azure-pipelines · 2026-03-31T07:53:40Z

Azure Pipelines successfully started running 3 pipeline(s).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

HybridWebViewHandler is marked [RequiresDynamicCode] because it uses dynamic System.Text.Json serialization. Placing [ElementHandler(typeof( HybridWebViewHandler))] on HybridWebView creates a hard compile-time type reference that ILC cannot eliminate via feature switches, causing NativeAOT compilation failures. Restore the conditional DI registration pattern behind RuntimeFeature.IsHybridWebViewSupported, which has [FeatureSwitchDefinition] and [FeatureGuard(typeof(RequiresDynamicCodeAttribute))] attributes that allow ILC to eliminate the entire code path (including the typeof reference) when NativeAOT is used. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 12, 2025 07:43

simonrozsival requested a review from a team as a code owner June 12, 2025 07:43

simonrozsival requested review from jfversluis and mattleibow June 12, 2025 07:43

Copilot AI reviewed Jun 12, 2025

View reviewed changes

simonrozsival commented Jun 12, 2025

View reviewed changes

src/Core/src/RuntimeFeature.cs Show resolved Hide resolved

simonrozsival marked this pull request as draft June 12, 2025 08:06

PureWeen added this to the .NET 10.0-preview6 milestone Jun 17, 2025

PureWeen added this to MAUI SDK Ongoing Jun 17, 2025

github-project-automation bot moved this to Todo in MAUI SDK Ongoing Jun 17, 2025

PureWeen moved this from Todo to In Progress in MAUI SDK Ongoing Jun 17, 2025

simonrozsival force-pushed the dev/simonrozsival/net10.0-use-element-handler-attributes branch from 33afe18 to c49e57e Compare June 18, 2025 11:53

PureWeen modified the milestones: .NET 10.0-preview6, .NET 11 Planning Jul 2, 2025

PureWeen added platform/macos macOS / Mac Catalyst platform/windows platform/android platform/ios area-architecture Issues with code structure, SDK structure, implementation details labels Aug 7, 2025

Copilot AI mentioned this pull request Nov 25, 2025

[WIP] Use ElementHandlerAttribute for built-in visual elements #32861

Closed

Copilot AI mentioned this pull request Nov 25, 2025

[net11.0] Use ElementHandlerAttribute instead of DI for built-in visual elements #32862

Merged

Copilot AI mentioned this pull request Dec 1, 2025

[net11.0] Fix build errors: qualify handler types and resolve merge conflicts #32933

Merged

simonrozsival added the copilot label Feb 19, 2026

simonrozsival force-pushed the dev/simonrozsival/net10.0-use-element-handler-attributes branch from f5c8447 to f097792 Compare February 19, 2026 14:21

StephaneDelcroix force-pushed the dev/simonrozsival/net10.0-use-element-handler-attributes branch from f097792 to 6695f72 Compare February 27, 2026 15:28

simonrozsival force-pushed the dev/simonrozsival/net10.0-use-element-handler-attributes branch from 6695f72 to d3fb530 Compare March 11, 2026 09:52

build-analysis bot mentioned this pull request Mar 18, 2026

slow macOS - "##[error]The job running on agent Azure Pipelines 9 ran longer than the maximum time of 60 minutes." dotnet/dnceng#1883

Open

3 tasks

simonrozsival and others added 5 commits March 31, 2026 09:52

[net11.0] Trimmable element handlers

1fd66b5

Squashed for clean rebase onto net11.0.

Document parameterless ctor requirement for [ElementHandler]

a94b163

Handlers resolved via [ElementHandler] attribute use Activator.CreateInstance(), not ActivatorUtilities. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove calls to obsolete AddMauiControlsHandlers in device tests

6df1fba

The method is now a no-op, and warnings-as-errors (CS0618) breaks the device test build on CI. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

simonrozsival force-pushed the dev/simonrozsival/net10.0-use-element-handler-attributes branch from f97fbcc to 5327392 Compare March 31, 2026 07:53

simonrozsival and others added 2 commits March 31, 2026 11:03

Fix CS8632: remove nullable annotations from #nullable disable context

aa37510

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Conversation

simonrozsival commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key changes

[ElementHandler] attribute

Handler resolution in MauiHandlersFactory

ElementExtensions.ToHandler() / SetHandler()

Mapper remapping via static constructors

Cleanup

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mattleibow commented Jun 17, 2025

Uh oh!

azure-pipelines bot commented Jun 17, 2025

Uh oh!

simonrozsival commented Nov 25, 2025

Uh oh!

Copilot AI commented Nov 25, 2025

Uh oh!

simonrozsival commented Nov 25, 2025

Uh oh!

Copilot AI commented Nov 25, 2025

Uh oh!

simonrozsival commented Dec 1, 2025

Uh oh!

Copilot AI commented Dec 1, 2025

Uh oh!

albyrock87 commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

simonrozsival commented Feb 20, 2026

Uh oh!

github-actions bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

simonrozsival commented Mar 18, 2026

Uh oh!

azure-pipelines bot commented Mar 18, 2026

Uh oh!

simonrozsival commented Mar 18, 2026

Uh oh!

azure-pipelines bot commented Mar 18, 2026

Uh oh!

simonrozsival commented Mar 18, 2026

Uh oh!

azure-pipelines bot commented Mar 18, 2026

Uh oh!

simonrozsival commented Mar 20, 2026

Uh oh!

azure-pipelines bot commented Mar 20, 2026

Uh oh!

simonrozsival commented Mar 20, 2026

Uh oh!

simonrozsival commented Mar 31, 2026

Uh oh!

azure-pipelines bot commented Mar 31, 2026

Uh oh!

simonrozsival commented Mar 31, 2026

Uh oh!

azure-pipelines bot commented Mar 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

simonrozsival commented Jun 12, 2025 •

edited

Loading

`[ElementHandler]` attribute

Handler resolution in `MauiHandlersFactory`

`ElementExtensions.ToHandler()` / `SetHandler()`

albyrock87 commented Feb 20, 2026 •

edited

Loading

github-actions bot commented Feb 27, 2026 •

edited

Loading