Fix MainThread throwing on custom platform backends

[Redth]

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

MainThread.BeginInvokeOnMainThread() and MainThread.InvokeOnMainThreadAsync() throw NotImplementedInReferenceAssemblyException on custom platform backends (e.g. Linux/GTK) even though the MAUI Dispatcher works correctly. This PR bridges the MAUI application dispatcher to MainThread during Essentials initialization so that custom platform backends get working MainThread support automatically.

Changes

• MainThread.shared.cs: Added internal backing delegates (SetCustomImplementation/ClearCustomImplementation) that allow a custom implementation to be injected
• MainThread.netstandard.cs: Modified PlatformIsMainThread and PlatformBeginInvokeOnMainThread to check backing delegates before throwing
• EssentialsMauiAppBuilderExtensions.cs: Added BridgeMainThreadFromDispatcher() that resolves the IDispatcherProvider during Essentials initialization and bridges it to MainThread
• AssemblyInfo.shared.cs: Added InternalsVisibleTo from Essentials to Core assembly
• MainThreadBridgeTests.cs: 11 focused regression tests covering direct injection, dispatcher bridge via MauiApp.Build(), argument validation, and cleanup

Design

On supported platforms (Android, iOS, Windows, Tizen), the platform-specific Platform* partial methods are defined in their respective files and used directly — the backing delegates are never consulted. Only on netstandard/external TFMs do the backing delegates provide the implementation, falling back to the existing throw behavior when no implementation has been set.

The bridge is intentionally minimal: simple Func<bool> and Action<Action> delegates rather than a full IMainThread interface, keeping the change focused and avoiding new public API surface.

Fixes #34101

[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 -- 35070

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

This PR aims to make MainThread work on custom/external platform backends (e.g., Linux/GTK) by bridging MAUI’s dispatcher into Essentials MainThread during Essentials initialization, avoiding NotImplementedInReferenceAssemblyException on those backends.

Changes:

• Added internal delegate-backed injection points to MainThread for external/unsupported TFMs.
• Updated the netstandard MainThread implementation to use the injected delegates when present.
• Added an Essentials initialization-time bridge from IDispatcher/IDispatcherProvider to MainThread, plus new Core unit tests.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/Essentials/src/MainThread/MainThread.shared.cs	Adds internal backing delegates and setters/clearers for a custom MainThread implementation.
src/Essentials/src/MainThread/MainThread.netstandard.cs	Uses backing delegates (when set) instead of always throwing on netstandard/external TFMs.
src/Core/src/Hosting/EssentialsMauiAppBuilderExtensions.cs	Bridges a MAUI dispatcher into MainThread during Essentials initialization.
src/Essentials/src/AssemblyInfo/AssemblyInfo.shared.cs	Adds InternalsVisibleTo for Core and Core unit tests to call Essentials internals.
src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs	Adds regression tests validating injection and dispatcher-bridge behavior.

[Redth]

No code change was needed for the dogfood note, but the PR has now been updated and is ready for validation with the standard script.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

[PureWeen]

🔍 Multi-Model Code Review — PR #35070

Fix MainThread throwing on custom platform backends

3 independent reviewers analyzed this PR. Findings below reflect adversarial consensus — only issues confirmed by 2+ reviewers are included. Single-reviewer findings that failed consensus are noted in the informational section.

---

CI Status

⚠️ Partially complete — All 22 completed checks ✅ passing (builds, Helix unit tests, Windows integration tests, iOS ARM64 tests, Android). 8 macOS integration tests still pending. No failures detected.

---

Prior Review Status

6 issues were flagged by the automated Copilot reviewer on the initial commit. All 6 were addressed by Redth in a follow-up commit (thread-safety via immutable holder, atomic reads, GetOptionalApplicationDispatcher, platform guard, unused usings, nullable fix). The test parallelization concern (#7) was acknowledged but declined with reasonable justification.

---

🟡 MODERATE

1. Bridge not cleared on MauiApp.Dispose() — stale dispatcher reference persists (3/3 reviewers)

File: src/Core/src/Hosting/EssentialsMauiAppBuilderExtensions.cs (bridge) + MainThread.shared.cs

BridgeMainThreadFromDispatcher captures an IDispatcher in lambdas stored in a process-global static field (s_mainThreadImplementation). When MauiApp is disposed, the service provider and potentially the dispatcher are torn down, but MainThread still holds the stale reference. No ClearCustomImplementation() is called during shutdown.

Impact: In multi-build/test-host scenarios, MainThread.IsMainThread could delegate to a disposed dispatcher, causing ObjectDisposedException or incorrect behavior. The test class works around this manually in IDisposable.Dispose(), masking the production gap.

Mitigation: Low practical risk — custom backends (Linux/GTK) typically have a single long-lived MauiApp, and rebuilding calls SetCustomImplementation again, atomically replacing the stale reference. However, a defensive IDisposable hook or a documented "set-once, app-lifetime" contract would be cleaner.

---

2. EssentialsInitializer now runs unconditionally for all MAUI apps (2/3 reviewers)

File: src/Core/src/Hosting/EssentialsMauiAppBuilderExtensions.cs, line 85 (new TryAddEnumerable in UseEssentials)

Previously, EssentialsInitializer.Initialize() only ran when the user explicitly called ConfigureEssentials(). This PR registers it in UseEssentials() (called unconditionally by MauiAppBuilder). As a result, all MAUI apps now get EssentialsInitializer.Initialize() side-effects:

• AppActions.OnAppAction += HandleOnAppAction; — static event subscription on all non-Tizen platforms (handler is a no-op when no handlers are configured, but creates a GC root)
• #if WINDOWS: ApplicationModel.Platform.MapServiceToken = null where it previously wasn't set

Impact: Behavioral contract change — apps that deliberately don't call ConfigureEssentials() silently get Essentials initialization. Functionally harmless (no-op handler), but unexpected. The bridge registration itself is correct and necessary.

---

3. Test parallelization risk with process-global state (2/3 reviewers)

File: src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs

Tests mutate two process-global statics (MainThread.s_mainThreadImplementation via Set/ClearCustomImplementation, DispatcherProvider.Current via SetCurrent). xUnit runs test classes in parallel, so MainThreadBridgeTests can race with DispatcherTests.cs and any other class touching these globals.

Status: The author correctly noted this follows the existing DispatcherTests.cs pattern and declined to add [Collection] isolation, arguing it should be a broader cleanup. This is pre-existing technical debt that this PR extends but doesn't create. Acknowledged — not blocking.

---

🟢 MINOR

4. Missing test coverage for InvokeOnMainThreadAsync through the bridge (2/3 reviewers)

File: src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs

Tests cover IsMainThread and BeginInvokeOnMainThread, but none of the four InvokeOnMainThreadAsync overloads. These are built on the tested primitives so coverage is implicit, but a direct integration test for the async path (especially Func<Task> with ConfigureAwait(false)) would catch regressions specific to task completion through the dispatcher bridge.

---

5. SequencedDispatcherProvider test doesn't exercise what it claims (2/3 reviewers)

File: src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs — MauiAppBuild_UsesCachedApplicationDispatcherForBridge

The SequencedDispatcherProvider returns dispatcherStub on first call and null on second. The intent is to verify the bridge caches the dispatcher. However, ApplicationDispatcher is a singleton — its Dispatcher property is set once during construction via GetDispatcher(). GetOptionalApplicationDispatcher() returns the already-constructed singleton's .Dispatcher, so the second null value is never reached. The test passes but doesn't verify dispatcher caching behavior.

---

6. s_mainThreadImplementation should be nullable-annotated (2/3 reviewers)

File: src/Essentials/src/MainThread/MainThread.shared.cs

static MainThreadImplementation s_mainThreadImplementation;  // defaults to null

ClearCustomImplementation() explicitly writes null. The field should be MainThreadImplementation? to be proactively correct if/when Essentials adopts <Nullable>enable</Nullable>. No functional impact today.

---

ℹ️ Informational (discarded by consensus)

Finding	Flagged by	Consensus	Reason for discard
TOCTOU: two reads of s_mainThreadImplementation in shared BeginInvokeOnMainThread	1/3	1/3	Theoretical — ClearCustomImplementation only called in test teardown, never concurrently in production
IDispatcher.Dispatch return value silently discarded	1/3	1/3	Correct — BeginInvokeOnMainThread is void; consistent with all existing platform implementations
SetCustomImplementation silently no-ops on native platforms	1/3	1/3	Intentional design — internal API for netstandard path only, existing comment documents intent

---

✅ Verified: No Issues

Concern	Verdict
Thread safety (Volatile.Read/Write)	✅ Correct — single immutable holder, local read before use
Platform guard (#if)	✅ Correct — bridge only runs on custom backends
TryAddEnumerable idempotency	✅ Safe — deduplicates by ServiceType+ImplementationType
Dispatcher initialization order	✅ ConfigureDispatching() runs before UseEssentials()
IsDispatchRequired → IsMainThread inversion	✅ Semantically correct
InternalsVisibleTo entries	✅ Appropriate scope for SetCustomImplementation access
internal visibility choice	✅ Conservative — can promote to public later

---

Recommended Action

⚠️ Request changes — Two items to address:

1. Finding [Draft] Readme WIP #1 (stale bridge): Consider adding a ClearCustomImplementation() call on MauiApp disposal, OR document that the bridge is set-once/app-lifetime and callers must not rely on it after disposal. At minimum, add a code comment in BridgeMainThreadFromDispatcher noting the lifetime assumption.

2. Finding Update README.md #5 (test intent): The MauiAppBuild_UsesCachedApplicationDispatcherForBridge test name implies it's testing dispatcher caching, but SequencedDispatcherProvider's null branch is never reached. Either rename the test to match what it actually verifies, or restructure to genuinely test caching.

Findings #2, #3, #4, #6 are noted but not blocking — they can be addressed as follow-ups.

[Redth]

Thanks for the thorough multi-model review. Here's how each finding was addressed in commit c7bbfc0:

Finding 1 (stale bridge reference): Partially accepted -- added detailed lifetime documentation on s_mainThreadImplementation explaining why it is not cleared on dispose (single long-lived app, atomic replacement on rebuild, undefined behavior post-disposal). Adding disposal hooks would overcomplicate things for a theoretical risk.

Finding 2 (unconditional EssentialsInitializer): Accepted -- extracted a dedicated MainThreadBridgeInitializer class that only does the dispatcher bridge. EssentialsInitializer is no longer registered in UseEssentials(), restoring the previous contract where it only runs when ConfigureEssentials() is explicitly called.

Finding 3 (test parallelization): Acknowledged but declined -- follows established DispatcherTests.cs pattern, should be a broader cleanup if pursued.

Finding 4 (async test coverage): Accepted -- added InvokeOnMainThreadAsync_Action_WorksThroughBridge test.

Finding 5 (misleading test name): Accepted -- renamed to MauiAppBuild_BridgeUsesApplicationDispatcher and removed unused SequencedDispatcherProvider.

Finding 6 (nullable annotation): Accepted -- added #nullable enable/restore around the field declaration.

All 13 MainThreadBridgeTests pass.

[MauiBot]

🤖 AI Summary

👋 @Redth — new AI review results are available. Please review the latest session below.

📊 Review Session — c7bbfc0 · Address multi-model review: extract MainThreadBridgeInitializer, add async test, improve docs · 2026-04-26 11:36 UTC

---

🚦 Gate — Test Before & After Fix

---

Gate Result: ✅ PASSED

Platform: ANDROID · Base: main · Merge base: f49d3bdb

Test	Without Fix (expect FAIL)	With Fix (expect PASS)
🧪 MainThreadBridgeTests MainThreadBridgeTests	✅ FAIL — 130s	✅ PASS — 121s

🔴 Without fix — 🧪 MainThreadBridgeTests: FAIL ✅ · 130s

  Determining projects to restore...
  Restored /home/vsts/work/1/s/src/Core/src/Core.csproj (in 8.53 sec).
  Restored /home/vsts/work/1/s/src/Controls/src/Core/Controls.Core.csproj (in 8.43 sec).
  Restored /home/vsts/work/1/s/src/Graphics/src/Graphics/Graphics.csproj (in 9 ms).
  Restored /home/vsts/work/1/s/src/Essentials/src/Essentials.csproj (in 15 ms).
  Restored /home/vsts/work/1/s/src/TestUtils/src/TestUtils/TestUtils.csproj (in 677 ms).
  Restored /home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj (in 1.62 sec).
  1 of 7 projects are up-to-date for restore.
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13939991
  Graphics -> /home/vsts/work/1/s/artifacts/bin/Graphics/Debug/net10.0/Microsoft.Maui.Graphics.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13939991
  Essentials -> /home/vsts/work/1/s/artifacts/bin/Essentials/Debug/net10.0/Microsoft.Maui.Essentials.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13939991
  Core -> /home/vsts/work/1/s/artifacts/bin/Core/Debug/net10.0/Microsoft.Maui.dll
  Controls.BindingSourceGen -> /home/vsts/work/1/s/artifacts/bin/Controls.BindingSourceGen/Debug/netstandard2.0/Microsoft.Maui.Controls.BindingSourceGen.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13939991
  Controls.Core -> /home/vsts/work/1/s/artifacts/bin/Controls.Core/Debug/net10.0/Microsoft.Maui.Controls.dll
  TestUtils -> /home/vsts/work/1/s/artifacts/bin/TestUtils/Debug/netstandard2.0/Microsoft.Maui.TestUtils.dll
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(18,15): error CS0117: 'MainThread' does not contain a definition for 'ClearCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(23,15): error CS0117: 'MainThread' does not contain a definition for 'ClearCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(31,18): error CS0122: 'NotImplementedInReferenceAssemblyException' is inaccessible due to its protection level [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(39,18): error CS0122: 'NotImplementedInReferenceAssemblyException' is inaccessible due to its protection level [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(46,15): error CS0117: 'MainThread' does not contain a definition for 'SetCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(56,15): error CS0117: 'MainThread' does not contain a definition for 'SetCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(69,15): error CS0117: 'MainThread' does not contain a definition for 'SetCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(86,15): error CS0117: 'MainThread' does not contain a definition for 'SetCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(99,15): error CS0117: 'MainThread' does not contain a definition for 'SetCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(105,15): error CS0117: 'MainThread' does not contain a definition for 'ClearCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(107,18): error CS0122: 'NotImplementedInReferenceAssemblyException' is inaccessible due to its protection level [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(115,22): error CS0117: 'MainThread' does not contain a definition for 'SetCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]
/home/vsts/work/1/s/src/Core/tests/UnitTests/Hosting/MainThreadBridgeTests.cs(122,22): error CS0117: 'MainThread' does not contain a definition for 'SetCustomImplementation' [/home/vsts/work/1/s/src/Core/tests/UnitTests/Core.UnitTests.csproj]

🟢 With fix — 🧪 MainThreadBridgeTests: PASS ✅ · 121s

  Determining projects to restore...
  All projects are up-to-date for restore.
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13939991
  Graphics -> /home/vsts/work/1/s/artifacts/bin/Graphics/Debug/net10.0/Microsoft.Maui.Graphics.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13939991
  Essentials -> /home/vsts/work/1/s/artifacts/bin/Essentials/Debug/net10.0/Microsoft.Maui.Essentials.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13939991
  Core -> /home/vsts/work/1/s/artifacts/bin/Core/Debug/net10.0/Microsoft.Maui.dll
  Controls.BindingSourceGen -> /home/vsts/work/1/s/artifacts/bin/Controls.BindingSourceGen/Debug/netstandard2.0/Microsoft.Maui.Controls.BindingSourceGen.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13939991
  Controls.Core -> /home/vsts/work/1/s/artifacts/bin/Controls.Core/Debug/net10.0/Microsoft.Maui.Controls.dll
  TestUtils -> /home/vsts/work/1/s/artifacts/bin/TestUtils/Debug/netstandard2.0/Microsoft.Maui.TestUtils.dll
  Core.UnitTests -> /home/vsts/work/1/s/artifacts/bin/Core.UnitTests/Debug/net10.0/Microsoft.Maui.UnitTests.dll
Test run for /home/vsts/work/1/s/artifacts/bin/Core.UnitTests/Debug/net10.0/Microsoft.Maui.UnitTests.dll (.NETCoreApp,Version=v10.0)
VSTest version 18.0.1 (x64)

Starting test execution, please wait...
A total of 1 test files matched the specified pattern.
[xUnit.net 00:00:00.00] xUnit.net VSTest Adapter v2.8.2+699d445a1a (64-bit .NET 10.0.0)
[xUnit.net 00:00:00.21]   Discovering: Microsoft.Maui.UnitTests
[xUnit.net 00:00:00.88]   Discovered:  Microsoft.Maui.UnitTests
[xUnit.net 00:00:00.89]   Starting:    Microsoft.Maui.UnitTests
  Passed MauiAppBuild_BridgesDispatcherToMainThread [54 ms]
  Passed SetCustomImpl_NullBeginInvoke_Throws [2 ms]
  Passed WithCustomImpl_IsMainThread_ReturnsFalse [< 1 ms]
  Passed WithCustomImpl_IsMainThread_UsesBackingImpl [< 1 ms]
  Passed MauiAppBuild_BridgeUsesApplicationDispatcher [4 ms]
  Passed WithoutCustomImpl_BeginInvoke_Throws [< 1 ms]
  Passed MauiAppBuild_BeginInvoke_DispatchesToDispatcher [3 ms]
  Passed SetCustomImpl_NullIsMainThread_Throws [< 1 ms]
  Passed InvokeOnMainThreadAsync_Action_WorksThroughBridge [2 ms]
[xUnit.net 00:00:01.09]   Finished:    Microsoft.Maui.UnitTests
  Passed ClearCustomImpl_RestoresThrowBehavior [< 1 ms]
  Passed WithCustomImpl_BeginInvoke_CallsBackingImpl [< 1 ms]
  Passed WithoutCustomImpl_IsMainThread_Throws [< 1 ms]
  Passed BeginInvoke_WhenOnMainThread_InvokesDirectly [< 1 ms]

Test Run Successful.
Total tests: 13
     Passed: 13
 Total time: 2.2619 Seconds

📁 Fix files reverted (4 files)

• src/Core/src/Hosting/EssentialsMauiAppBuilderExtensions.cs
• src/Essentials/src/AssemblyInfo/AssemblyInfo.shared.cs
• src/Essentials/src/MainThread/MainThread.netstandard.cs
• src/Essentials/src/MainThread/MainThread.shared.cs

---

🧪 UI Tests — Category Detection

---

Detected UI test categories: Essentials

---

🔍 Pre-Flight — Context & Validation

---

Issue: #34101 - MainThread.BeginInvokeOnMainThread throws on custom platform backends
PR: #35070 - Fix MainThread throwing on custom platform backends
Platforms Affected: Custom/netstandard TFMs (Linux/GTK etc.) — native platforms (Android, iOS, macCatalyst, Windows, Tizen) are unaffected
Files Changed: 4 implementation, 1 test (+ AssemblyInfo)

Key Findings

• MainThread.BeginInvokeOnMainThread() and MainThread.IsMainThread throw NotImplementedInReferenceAssemblyException on custom platform backends even though IDispatcher works correctly
• Fix adds an internal MainThreadImplementation sealed class (atomic state holder) + Volatile.Read/Write for thread safety
• New MainThreadBridgeInitializer bridges GetOptionalApplicationDispatcher() to MainThread during app initialization, guarded by #if !(ANDROID || __IOS__ || __MACCATALYST__ || WINDOWS || TIZEN)
• Prior automated code review found 6 issues; all 6 were addressed by the author in a follow-up commit
• All CI checks are passing: builds, Helix unit tests, integration tests (Windows + macOS), iOS ARM64

Code Review Summary

Verdict: LGTM
Confidence: high
Errors: 0 | Warnings: 2 | Suggestions: 2

Key code review findings:

• ⚠️ SetCustomImplementation/ClearCustomImplementation compile on all TFMs but silently no-op on native platforms — no error or signal to callers (MainThread.shared.cs:41-51)
• ⚠️ MauiAppBuild_BridgesDispatcherToMainThread and MauiAppBuild_BridgeUsesApplicationDispatcher are functionally duplicate tests (same assertion, same stub config) (MainThreadBridgeTests.cs:125-149 and 207-229)
• 💡 MainThreadBridgeInitializer silently skips bridging when dispatcher is null — no log/warning emitted (EssentialsMauiAppBuilderExtensions.cs:134-136)
• 💡 Captured dispatcher in lambdas creates permanent strong root through static MainThread — not cleared on MauiApp.Dispose() by design, but worth documenting in XML doc

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #35070	Add internal MainThreadImplementation holder; bridge via MainThreadBridgeInitializer on non-native TFMs using GetOptionalApplicationDispatcher()	✅ PASSED (Gate)	4 impl + 1 test	Prior code review issues addressed in follow-up commit

---

🔬 Code Review — Deep Analysis

---

Code Review — PR #35070

Independent Assessment

What this changes: Adds an internal extensibility point to MainThread (two delegates wrapped in a sealed MainThreadImplementation class, accessed via Volatile.Read/Write) that the netstandard platform partial uses before throwing NotImplementedInReferenceAssemblyException. A new MainThreadBridgeInitializer — registered only on non-native TFMs — bridges IDispatcher.IsDispatchRequired and IDispatcher.Dispatch to MainThread during IMauiInitializeService initialization. Also adds InternalsVisibleTo("Microsoft.Maui") to Essentials so Core can call the new internal methods.

Inferred motivation: Custom platform backends (e.g. Linux/GTK) that implement MAUI's IDispatcher correctly still got NotImplementedInReferenceAssemblyException from MainThread because the Essentials netstandard stub simply threw unconditionally. This PR wires the working dispatcher into MainThread automatically, without adding any public API.

---

Reconciliation with PR Narrative

Author claims: Fixes #34101 — MainThread.* APIs throw on custom platform backends even though the MAUI Dispatcher works. The bridge is minimal (no new public API), internally scoped, and leaves native platform code paths untouched.

Agreement: Code matches the claim precisely. The #if !(ANDROID || __IOS__ || __MACCATALYST__ || WINDOWS || TIZEN) guards are symmetrical in both the service registration and the class definition. Native platforms remain unaffected at compile time.

---

Findings

⚠️ Warning — SetCustomImplementation/ClearCustomImplementation are callable (and silently no-op) on native platforms

SetCustomImplementation and ClearCustomImplementation live in MainThread.shared.cs, so they compile on all TFMs including Android/iOS/Windows. But on those platforms, PlatformIsMainThread and PlatformBeginInvokeOnMainThread are provided by platform-specific partial implementations that never consult s_mainThreadImplementation. Calling SetCustomImplementation on Android will write to the field and return, with zero observable effect — no error, no warning.

The comment in the code acknowledges this ("On supported platforms the Platform* methods are used directly"), but a caller on a native platform has no way to discover that the method did nothing. The method signature gives no signal. Consider adding an [EditorBrowsable(EditorBrowsableState.Never)] attribute or at minimum promoting the comment to an XML <remarks> on the method:

/// <remarks>
/// This has no effect on native platforms (Android, iOS, macCatalyst, Windows, Tizen)
/// where PlatformIsMainThread and PlatformBeginInvokeOnMainThread use native implementations directly.
/// </remarks>
internal static void SetCustomImplementation(...)

MainThreadBridgeTests.cs — given the tests run on netstandard, this behavior gap is not tested. A test calling SetCustomImplementation on a platform build and then verifying IsMainThread still uses the native path would close this documentation gap.

⚠️ Warning — MauiAppBuild_BridgesDispatcherToMainThread and MauiAppBuild_BridgeUsesApplicationDispatcher are duplicate tests

Both tests (lines 125–149 and 207–229) configure the stub with isInvokeRequired: () => false and assert Assert.True(MainThread.IsMainThread). The only difference is that one passes invokeOnMainThread: null and the other passes invokeOnMainThread: action => action(). Since neither test exercises BeginInvokeOnMainThread, the invokeOnMainThread parameter doesn't affect the assertion. The tests are functionally identical.

The second test (MauiAppBuild_BridgeUsesApplicationDispatcher) should either be removed or evolved to assert something different — e.g., verify that BeginInvokeOnMainThread calls through to the dispatcher's Dispatch method (as MauiAppBuild_BeginInvoke_DispatchesToDispatcher already does for isInvokeRequired: () => true).

💡 Suggestion — MainThreadBridgeInitializer silently does nothing when no dispatcher is available

var dispatcher = services.GetOptionalApplicationDispatcher();
if (dispatcher is null)
    return;

On an unusual/broken DI configuration where the dispatcher isn't yet available, the bridge is simply skipped — no warning, no log. Any subsequent MainThread.IsMainThread call will throw NotImplementedInReferenceAssemblyException, which is hard to correlate back to the silent skip here. A Debug.Assert or a debug-only log line would help diagnostics on custom backends during development.

💡 Suggestion — The captured dispatcher closure creates a permanent strong root through MainThread

MainThread.SetCustomImplementation(
    isMainThread: () => !dispatcher.IsDispatchRequired,
    beginInvokeOnMainThread: action => dispatcher.Dispatch(action));

MainThread is a static class. Once SetCustomImplementation is called, the captured dispatcher reference lives in the static s_mainThreadImplementation field until ClearCustomImplementation is called or another SetCustomImplementation replaces it. Since MauiApp.Dispose() does not clear this (by documented design), disposing a MauiApp on a custom backend does not release the dispatcher captured here. For custom backends with multiple sequential MauiApp instances, this is a soft leak. The test Dispose() method already calls ClearCustomImplementation(), which is the right mitigation — worth noting this requirement explicitly in the initializer's XML doc comment.

---

Devil's Advocate

"Is the Volatile.Read/Write sufficient for thread safety?" — Yes, for this use case. The field is written once during app initialization on the main thread, then read on any thread. Volatile gives acquire/release semantics on the single reference. No lock is needed because MainThreadImplementation is itself immutable.

"Could the #if guard miss a TFM?" — The guard !(ANDROID || __IOS__ || __MACCATALYST__ || WINDOWS || TIZEN) is identical in both the service registration and the class definition, so there's no gap there. If a future official platform TFM is added without updating this guard, MainThreadBridgeInitializer would redundantly attempt to bridge alongside the native implementation. It wouldn't break anything (native Platform* methods take precedence), but it would be wasteful. Low-risk concern for a future PR.

"Could the duplicate tests hide a regression?" — Modestly yes. The gap is in testing BeginInvokeOnMainThread routes through the dispatcher post-Build on the non-dispatching thread. MauiAppBuild_BeginInvoke_DispatchesToDispatcher does cover this when isInvokeRequired: () => true. The duplicate is noise, not a safety net hole.

---

Verdict: LGTM

Confidence: high
Summary: The core mechanism is correct — thread-safe via Volatile, scoped precisely to non-native TFMs, no native platform code paths affected, CI fully green across all platforms and integration tests. The two warnings are real but non-blocking: one is a documentation gap on an internal API, the other is a test quality issue (duplicate test) that doesn't affect coverage of the critical path. Addressing them before merge would improve maintainability, but neither prevents the change from shipping.

---

🔧 Fix — Analysis & Comparison

---

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
1	try-fix (claude-opus-4.6)	Lazy-resolving bare fields via DispatcherProvider.Current — no wrapper class, hooks in UseEssentials(), resolves fresh each call	✅ PASS	5 files	No stale-reference risk; but Essentials→Core static dependency (layering concern)
2	try-fix (claude-sonnet-4.6)	SynchronizationContext-based polymorphic bridge — abstract class in Essentials, Core extends with IDispatcher impl	✅ PASS	4 files	Type-polymorphic, uses BCL abstraction; higher complexity
3	try-fix (gpt-5.3-codex)	Runtime fallback in netstandard path — calls DispatcherProvider.Current.GetForCurrentThread() at call-time; no Core hook	✅ PASS	3 files	Zero startup overhead; Essentials→Core static coupling same as Attempt 1
4	try-fix (gpt-5.4)	Capture startup SynchronizationContext + thread ID at build time; no IDispatcher dependency	❌ FAIL	5 files	Racy async test; conceptually sound but needs more robust test harness
PR	PR #35070	Sealed MainThreadImplementation holder; IMauiInitializeService bridge; GetOptionalApplicationDispatcher() via DI; Volatile.Read/Write	✅ PASSED (Gate)	4 impl + 1 test	Thread-safe, clean layering via DI, proper lifecycle hook

Cross-Pollination

Model	Round	New Ideas?	Details
claude-opus-4.6	2	No	"Design space thoroughly covered along both axes: what carries the capability (IDispatcher, delegates, SynchronizationContext) and when it's resolved (startup, per-call, polymorphic)"

Exhausted: Yes
Selected Fix: PR's fix — Reasons:

1. Thread-safe via Volatile.Read/Write — Attempts 1 and 3 lack formal thread safety
2. Clean dependency direction — Core calls Essentials internals (InternalsVisibleTo), not Essentials referencing Core statics (Attempts 1 and 3 create Essentials→Core.DispatcherProvider coupling)
3. Proper lifecycle via IMauiInitializeService — integrates with MAUI DI/initialization pipeline
4. Atomic immutable holder — single Volatile.Write publishes both delegates atomically; no partial observation
5. Uses GetOptionalApplicationDispatcher() (DI-resolved) vs. static singleton — more testable

---

📋 Report — Final Recommendation

---

✅ Final Recommendation: APPROVE

Phase Status

Phase	Status	Notes
Pre-Flight	✅ COMPLETE	Issue #34101 analyzed; prior code review issues confirmed all addressed
Code Review	LGTM (high)	0 errors, 2 warnings, 2 suggestions
Gate	✅ PASSED	Unit tests (netstandard/net10.0) — FAIL without fix, PASS with fix (13/13)
Try-Fix	✅ COMPLETE	4 attempts: 3 passing, 1 failing; cross-pollination exhausted
Report	✅ COMPLETE

Code Review Impact on Try-Fix

Code review highlighted two concerns: (1) stale dispatcher reference in static field after MauiApp.Dispose(), and (2) duplicate tests. These guided try-fix exploration — Attempt 1 specifically addressed the stale-reference concern by resolving the dispatcher fresh per call, which confirmed the PR's design decision (documented lifetime, atomic replacement) is a deliberate and acceptable tradeoff. Attempt 4 explored dispatcher-free approaches (thread ID + SynchronizationContext capture) but failed on test reliability, validating that the PR's IDispatcher-based approach is more robust. No code review ❌ Errors were found, so the hard gate does not apply.

Summary

PR #35070 fixes MainThread.BeginInvokeOnMainThread() and MainThread.IsMainThread throwing NotImplementedInReferenceAssemblyException on custom platform backends (Linux/GTK, etc.) where IDispatcher works correctly. The fix is minimal: an internal MainThreadImplementation holder + Volatile.Read/Write thread safety + a MainThreadBridgeInitializer that bridges GetOptionalApplicationDispatcher() to MainThread during MAUI initialization, guarded by #if !(ANDROID || __IOS__ || __MACCATALYST__ || WINDOWS || TIZEN). All CI checks pass. A prior automated code review found 6 issues; all 6 were addressed by the author in a follow-up commit.

Root Cause

The Essentials MainThread.netstandard.cs implementation unconditionally threw NotImplementedInReferenceAssemblyException for PlatformIsMainThread and PlatformBeginInvokeOnMainThread. Custom platform backends (netstandard TFMs) had no mechanism to register an alternative implementation. Meanwhile, the MAUI IDispatcher was fully functional on those same backends via the dispatcher infrastructure.

Fix Quality

The PR's fix is the best among all candidates explored:

• Thread safety: Volatile.Read/Write with an immutable MainThreadImplementation holder — single atomic publication, no partial-update risk
• Clean dependency layering: Core calls Essentials internals via InternalsVisibleTo (not Essentials calling Core statics), maintaining proper assembly dependency direction
• Proper lifecycle: IMauiInitializeService hook integrates with MAUI's DI initialization pipeline, not a static builder-time side-effect
• DI-resolved dispatcher: GetOptionalApplicationDispatcher() vs. static DispatcherProvider.Current — more testable and correct for multi-app scenarios
• Platform guard: Symmetric #if in both service registration and class definition — native platforms completely unaffected at compile time
• Test coverage: 13 focused regression tests covering all key scenarios including async path, argument validation, and bridge lifecycle

The two remaining warnings (internal API silent no-op on native platforms, duplicate test) are non-blocking and can be addressed as follow-up improvements.

---

[kubaflo]

@Redth can it go to inflight or rather net11?