[Extensibility] BlazorWebView: Add custom platform handler registration

[kubaflo]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description

Forward-ports #34225 to net11.0 and completes its custom-handler contract.

Adds IMauiBlazorWebViewBuilder.UsePlatformHandler overloads for handlers implementing the new IBlazorWebViewHandler capability interface:

• generic UsePlatformHandler<THandler>() for handlers with public parameterless constructors;
• factory UsePlatformHandler(Func<IServiceProvider, IBlazorWebViewHandler>) for handlers needing controlled construction.

IBlazorWebViewHandler exposes the two operations used by BlazorWebView: static-file-provider creation and scoped-service dispatch. This lets independent handlers work end-to-end without deriving from the built-in BlazorWebViewHandler. The built-in handler implements the capability explicitly, shared code no longer hard-casts to the concrete handler, and Windows teardown performs the required WebView2 cleanup based on the platform-view type for the built-in handler and custom handlers that expose WebView2 directly as their platform view. Custom handlers that wrap WebView2 instead are documented to close the owned control in their own disconnect logic.

Both registration overloads replace the default handler through ConfigureMauiHandlers. PublicAPI entries cover every MAUI TFM, and device tests use non-derived handlers to verify generic registration, UI-thread factory registration, file-provider creation, dispatch, and incompatible-handler diagnostics.

Fixes #34103
Part of #34099

Testing

• Microsoft.AspNetCore.Components.WebView.Maui.csproj net11.0 build with PublicAPI analyzers: passed
• MacCatalyst Category=BlazorWebView: 26 passed, 0 failed, 1 ignored
• Android custom-handler tests: 3 passed
  • UsePlatformHandlerGenericReplacesDefaultBlazorWebViewHandler
  • UsePlatformHandlerFactoryReplacesDefaultBlazorWebViewHandler
  • BlazorWebViewUsesCustomHandlerOperations

The remaining Android category tests timed out waiting for the emulator's WebView/Blazor runtime to initialize and did not involve the custom-handler path.

[github-actions]

🚀 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 -- 36658

Or

• Run remotely in PowerShell:

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

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Adds an extensibility point for MAUI Blazor Hybrid so custom platform backends can replace the default BlazorWebViewHandler without reimplementing AddMauiBlazorWebView() service registration, forward-ported to net11.0.

Changes:

• Introduces IMauiBlazorWebViewBuilder.UsePlatformHandler<THandler>() and UsePlatformHandler(Func<IServiceProvider, IViewHandler>) to override the IBlazorWebView handler registration via ConfigureMauiHandlers.
• Adds Core unit tests validating “last registration wins” behavior across multiple ConfigureMauiHandlers calls and factory-based handler registrations.
• Adds device tests validating the new public API replaces the default BlazorWebView handler end-to-end, plus PublicAPI entries for all relevant TFMs.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Core/tests/UnitTests/Hosting/HostBuilderHandlerTests.cs	Adds unit coverage proving handler registrations are replaceable (type + factory) across multiple ConfigureMauiHandlers calls.
src/BlazorWebView/tests/DeviceTests/Elements/BlazorWebViewTests.Services.cs	Adds device tests validating UsePlatformHandler overrides the default BlazorWebView handler in practice.
src/BlazorWebView/src/Maui/PublicAPI/net/PublicAPI.Unshipped.txt	Declares new public extension type + methods (net).
src/BlazorWebView/src/Maui/PublicAPI/net-windows/PublicAPI.Unshipped.txt	Declares new public extension type + methods (net-windows).
src/BlazorWebView/src/Maui/PublicAPI/net-tizen/PublicAPI.Unshipped.txt	Declares new public extension type + methods (net-tizen).
src/BlazorWebView/src/Maui/PublicAPI/net-maccatalyst/PublicAPI.Unshipped.txt	Declares new public extension type + methods (net-maccatalyst).
src/BlazorWebView/src/Maui/PublicAPI/net-ios/PublicAPI.Unshipped.txt	Declares new public extension type + methods (net-ios).
src/BlazorWebView/src/Maui/PublicAPI/net-android/PublicAPI.Unshipped.txt	Declares new public extension type + methods (net-android).
src/BlazorWebView/src/Maui/MauiBlazorWebViewBuilderExtensions.cs	Implements the new UsePlatformHandler overloads with null guards and trimming annotations.

[kubaflo]

🤖 AI-generated CI analysis (GitHub Copilot CLI, on behalf of @kubaflo).

maui-pr build 1516291 failed in two unrelated Microsoft.Maui.UnitTests.dll tests:

• Release: BorderStrokeShapeDoesNotLeak failed its GC-based Border should not be alive! assertion — a nondeterministic leak-test pattern in Core, unrelated to the BlazorWebView files changed here.
• Debug: MauiAppBuild_BridgesDispatcherToMainThread hit the reference-assembly MainThread implementation. This is the pre-existing hosting/static-state race whose test serialization is included in merged Bridge DI-registered Essentials implementations to static facades #35068 and the net11 forward-port [Extensibility] Essentials: Bridge DI implementations to static facades #36657; [Extensibility] BlazorWebView: Add custom platform handler registration #36658 does not touch Essentials/MainThread.

All BlazorWebView-specific code/build tests and the remaining CI legs passed. No PR-caused failure was found; re-running CI.

[kubaflo]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 3 pipeline(s).

[kubaflo]

🤖 AI-generated device-test analysis (GitHub Copilot CLI, on behalf of @kubaflo).

maui-pr-devicetests build 1516323 has no BlazorWebView failure:

• Both MacCatalyst queues and both iOS queues fail the same five Essentials FileSystem_Tests with NullReferenceException: Arg_NullReferenceException in FileStream.ReadAsync(Memory<byte>). This is the known .NET 11 runtime regression dotnet/runtime#129813.
• One MacCatalyst Controls work item failed CarouselViewDoesNotLeakWithDefaultItemsLayout because the GC leak assertion did not collect the view, an unrelated nondeterministic CollectionView/GC test.
• All other work items passed; no test covering UsePlatformHandler failed.

No PR-caused device-test failure was found.

[kubaflo]

🤖 AI-generated CI analysis update (GitHub Copilot CLI, on behalf of @kubaflo).

The newly completed iOS CollectionView failure in maui-pr-uitests build 1516322 is confirmed pre-existing on net11.0. BottomSheetDetentHeightIsCorrectWhenCollectionViewIsMeasuredBeforeMount timed out waiting for its element on both PR attempts at Issue32983.cs:22. The exact test also failed on base build 1501538 on both iOS 18.5 and vlatest queues, including retries. PR #36658 changes only BlazorWebView handler registration, so this failure is unrelated.

[kubaflo]

🤖 AI-generated CI analysis update (GitHub Copilot CLI, on behalf of @kubaflo).

The two Image-category failures in UI build 1516322 also exactly match the net11.0 baseline. The PR’s iOS and MacCatalyst legs each failed the same 10 tests on both attempts: the eight Image/ImageButton aspect visual tests, DownSizeImageAppearProperly, and LoadTestImageButtonShouldLoadImageWithoutException. Base build 1501538 contains the same complete 10-test set, including the same Status: Error occurred assertion for the load test. These failures predate and are unrelated to the Blazor handler-registration change.

[kubaflo]

🤖 AI-generated CI analysis update (GitHub Copilot CLI, on behalf of @kubaflo).

UI build 1516322 is complete. Its final MacCatalyst CollectionView job exceeded the 180-minute job limit after CollectionViewSelectionChangesVisualState failed on the first attempt; the exact test also failed in net11.0 base build 1501538, whose MacCatalyst CollectionView job was likewise canceled. Together with the previously documented exact-base Image and BottomSheet matches and the known runtime/GC device failures, every completed failure is unrelated to the Blazor handler-registration change. A clean CI rerun has been requested.

[kubaflo]

/azp run

[kubaflo]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 3 pipeline(s).

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

[kubaflo]

Current-head CI evidence (builds still active): device build 1531528 currently has failed MacCatalyst CoreCLR, iOS Mono, and iOS CoreCLR legs. Current net11.0 baseline device build 1531485 has the exact same three failed job names. This is current-base evidence that these device reds are unrelated to the BlazorWebView changes; remaining jobs are still pending.

[kubaflo]

Updated device evidence for 1531528: Windows Helix completed with both MauiBlazorWebView packaged and unpackaged work items green; Core, Essentials, and Graphics also passed. Only baseline Controls packaged/unpackaged failed. The remaining failed platform job names match current net11.0 baseline 1531485; remaining jobs are still pending.

[kubaflo]

Final UI 1531526 classification: Controls Material3 (API 36) and Controls CollectionView both fail in current net11.0 baseline UI 1531376; the Editor/Effects/Essentials/FlyoutPage/Focus/Fonts/Frame/Gestures/GraphicsView group failed concurrently across multiple unrelated PRs. No failure correlates with the BlazorWebView handler-registration diff. A UI-only replacement run is justified.

[kubaflo]

/azp run maui-pr-uitests

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).

[kubaflo]

Replacement UI 1531707 currently has one unrelated Android UI timeout: Issue32871.BottomPaddingShouldBePreservedWhileKeyboardIsShowing timed out waiting for an element in the API30 SafeArea shard. The PR changes BlazorWebView handler registration and does not touch SafeArea, keyboard, or this test; remaining jobs are still active.

[kubaflo]

Final CI classification: main 1531521 is fully green. Windows device Helix confirms MauiBlazorWebView packaged/unpackaged passed; device reds are baseline Controls/platform jobs. UI replacement 1531707 has only current-base CollectionView/vlatest CollectionView, Material3 API36, and API30 Shell failures, plus the unrelated Issue32871 SafeArea element timeout and known cancellation/timeout infrastructure. Further reruns add no signal. CI is ready for the unrelated-red exception after human approval.