Bridge DI-registered Essentials implementations to static facades

src/Core/src/Hosting/EssentialsMauiAppBuilderExtensions.cs

@@ -3,10 +3,20 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Logging;
+using Microsoft.Maui.Accessibility;
 using Microsoft.Maui.ApplicationModel;
+using Microsoft.Maui.ApplicationModel.Communication;
+using Microsoft.Maui.ApplicationModel.DataTransfer;
+using MauiContacts = Microsoft.Maui.ApplicationModel.Communication.Contacts;
+using Microsoft.Maui.Authentication;
+using Microsoft.Maui.Devices;
+using Microsoft.Maui.Devices.Sensors;
 using Microsoft.Maui.Dispatching;
 using Microsoft.Maui.Hosting;
 using Microsoft.Maui.LifecycleEvents;
+using Microsoft.Maui.Media;
+using Microsoft.Maui.Networking;
+using Microsoft.Maui.Storage;
 #if ANDROID
 using Android.App;
 #endif
@@ -28,6 +38,26 @@ public static class EssentialsExtensions
 	{
 		internal static MauiAppBuilder UseEssentials(this MauiAppBuilder builder)
 		{
+#if !(ANDROID || __IOS__ || __MACCATALYST__ || WINDOWS || TIZEN)
+			// Register MainThreadBridgeInitializer FIRST so MainThread.SetCustomImplementation
+			// runs before EssentialsInitializer resolves DI-registered services. Order matters:
+			// IMauiInitializeService instances are executed in DI registration order
+			// (MauiContextExtensions.InitializeAppServices iterates GetServices<IMauiInitializeService>()),
+			// and on netstandard / external TFMs MainThread throws NotImplementedInReferenceAssemblyException
+			// until the bridge is installed. If EssentialsInitializer ran first, any DI-registered
+			// Essentials implementation whose constructor touched MainThread would fail during
+			// the very bridge call meant to enable it.
+			builder.Services.TryAddEnumerable(ServiceDescriptor.Transient<IMauiInitializeService, MainThreadBridgeInitializer>());
+#endif
+
+			// Register the EssentialsInitializer unconditionally so DI-registered Essentials
+			// implementations are bridged to the static facades during app startup, even when
+			// ConfigureEssentials() is not called. The initializer's AppActions event handler
+			// is only attached when at least one AppAction handler is configured, to avoid
+			// retaining the initializer instance via the static AppActions.OnAppAction event
+			// for apps that never opt into AppActions.
+			builder.Services.TryAddEnumerable(ServiceDescriptor.Transient<IMauiInitializeService, EssentialsInitializer>());
+
 			builder.ConfigureLifecycleEvents(life =>
 			{
 #if ANDROID
@@ -83,10 +113,6 @@ internal static MauiAppBuilder UseEssentials(this MauiAppBuilder builder)
 #endif
 			});
 
-#if !(ANDROID || __IOS__ || __MACCATALYST__ || WINDOWS || TIZEN)
-			builder.Services.TryAddEnumerable(ServiceDescriptor.Transient<IMauiInitializeService, MainThreadBridgeInitializer>());
-#endif
-
 			return builder;
 		}
 
@@ -163,12 +189,25 @@ public void Initialize(IServiceProvider services)
 					}
 				}
 
+				BridgeEssentialsFromDI(services);
+
 #if WINDOWS
-				ApplicationModel.Platform.MapServiceToken = _essentialsBuilder.MapServiceToken;
+				// Only forward MapServiceToken when ConfigureEssentials(e => e.UseMapServiceToken(...))
+				// supplied a value. Without this null guard, EssentialsInitializer (now registered
+				// unconditionally) would overwrite any token a caller had set directly via
+				// ApplicationModel.Platform.MapServiceToken before MauiApp.Build().
+				if (_essentialsBuilder.MapServiceToken is not null)
+					ApplicationModel.Platform.MapServiceToken = _essentialsBuilder.MapServiceToken;
 #endif
 
 #if !TIZEN
-				AppActions.OnAppAction += HandleOnAppAction;
+				// Only subscribe to the static AppActions.OnAppAction event when at least one
+				// handler was actually registered via IEssentialsBuilder.OnAppAction. The static
+				// event subscription would otherwise pin this initializer instance for the app's
+				// lifetime (and across repeated MauiApp.Build() calls in tests / hosting scenarios)
+				// even when the handler is a no-op.
+				if (_essentialsBuilder.AppActionHandlers is not null)
+					AppActions.OnAppAction += HandleOnAppAction;
 
 				if (_essentialsBuilder.AppActions is not null)
 				{
@@ -180,6 +219,106 @@ public void Initialize(IServiceProvider services)
 					VersionTracking.Track();
 			}
 
+			/// <summary>
+			/// Bridges DI-registered Essentials implementations to the static facades.
+			/// If a service is registered in DI, it becomes the backing implementation for
+			/// the corresponding static API. If not registered, the existing lazy platform
+			/// default behavior is preserved.
+			/// </summary>
+			static void BridgeEssentialsFromDI(IServiceProvider services)
+			{
+				// SetDefault pattern types
+				BridgeIfRegistered<IAccelerometer>(services, Accelerometer.SetDefault);
+				// IActivityStateManager is intentionally NOT bridged. It is Android-only, and its
+				// platform default is already initialized — with its ActivityLifecycleCallbacks
+				// registered — by ApplicationModel.Platform.Init() during UseEssentials(), before this
+				// bridge runs at MauiApp.Build() time. Replacing ActivityStateManager.Default after that
+				// point would leave the original lifecycle listener registered while the replacement
+				// missed the initial Init(Application) call. Custom (non-Android) backends never reach
+				// the Android-only code path, so bridging it here serves no purpose.
+				BridgeIfRegistered<IBarometer>(services, Barometer.SetDefault);
+				BridgeIfRegistered<IBattery>(services, Battery.SetDefault);
+				BridgeIfRegistered<IBrowser>(services, Browser.SetDefault);
+				BridgeIfRegistered<IClipboard>(services, Clipboard.SetDefault);
+				BridgeIfRegistered<ICompass>(services, Compass.SetDefault);
+				BridgeIfRegistered<IContacts>(services, MauiContacts.SetDefault);
+				BridgeIfRegistered<IEmail>(services, Email.SetDefault);
+				BridgeIfRegistered<IFilePicker>(services, FilePicker.SetDefault);
+				BridgeIfRegistered<IFlashlight>(services, Flashlight.SetDefault);
+				BridgeIfRegistered<IGeolocation>(services, Geolocation.SetDefault);
+				BridgeIfRegistered<IGyroscope>(services, Gyroscope.SetDefault);
+				BridgeIfRegistered<IHapticFeedback>(services, HapticFeedback.SetDefault);
+				BridgeIfRegistered<ILauncher>(services, Launcher.SetDefault);
+				BridgeIfRegistered<IMagnetometer>(services, Magnetometer.SetDefault);
+				BridgeIfRegistered<IMap>(services, Map.SetDefault);
+				BridgeIfRegistered<IMediaPicker>(services, MediaPicker.SetDefault);
+				BridgeIfRegistered<IOrientationSensor>(services, OrientationSensor.SetDefault);
+				BridgeIfRegistered<IPhoneDialer>(services, PhoneDialer.SetDefault);
+				BridgeIfRegistered<IPreferences>(services, Preferences.SetDefault);
+				BridgeIfRegistered<IScreenshot>(services, Screenshot.SetDefault);
+				BridgeIfRegistered<ISecureStorage>(services, SecureStorage.SetDefault);
+				BridgeIfRegistered<ISemanticScreenReader>(services, SemanticScreenReader.SetDefault);
+				BridgeIfRegistered<IShare>(services, Share.SetDefault);
+				BridgeIfRegistered<ISms>(services, Sms.SetDefault);
+				BridgeIfRegistered<ITextToSpeech>(services, TextToSpeech.SetDefault);
+				BridgeIfRegistered<IVersionTracking>(services, VersionTracking.SetDefault);
+				BridgeIfRegistered<IVibration>(services, Vibration.SetDefault);
+				// IWebAuthenticator: on Android/iOS/MacCatalyst the platform callback activities
+				// and lifecycle hooks (WebAuthenticatorCallbackActivity.OnResume, Platform.OpenUrl,
+				// ContinueUserActivity) cast WebAuthenticator.Default to IPlatformWebAuthenticatorCallback
+				// via AsPlatformCallback(). Only bridge a DI implementation that supports that contract
+				// on those platforms, mirroring the IAppActions guard below, to avoid a
+				// PlatformNotSupportedException at runtime.
+				var webAuthenticator = services.GetService<IWebAuthenticator>();
+				if (webAuthenticator is not null)
+				{
+#if ANDROID || __IOS__ || __MACCATALYST__
+					if (webAuthenticator is IPlatformWebAuthenticatorCallback)
+						WebAuthenticator.SetDefault(webAuthenticator);
+#else
+					WebAuthenticator.SetDefault(webAuthenticator);
+#endif
+				}
+#if WINDOWS || __IOS__ || __MACCATALYST__
+				BridgeIfRegistered<IWindowStateManager>(services, WindowStateManager.SetDefault);
+#endif
+				BridgeIfRegistered<IAppleSignInAuthenticator>(services, AppleSignInAuthenticator.SetDefault);
+
+				// SetCurrent pattern types
+				// IAppActions: On native platforms, lifecycle hooks cast AppActions.Current to
+				// IPlatformAppActions via AsPlatform(). Only bridge if the DI implementation
+				// supports it, to prevent PlatformNotSupportedException at runtime.
+				var appActions = services.GetService<IAppActions>();
+				if (appActions is not null)
+				{
+#if WINDOWS || __IOS__ || __MACCATALYST__ || ANDROID
+					if (appActions is IPlatformAppActions)
+						AppActions.SetCurrent(appActions);
+#else
+					AppActions.SetCurrent(appActions);
+#endif
+				}
+				BridgeIfRegistered<IAppInfo>(services, AppInfo.SetCurrent);
+				BridgeIfRegistered<IConnectivity>(services, Connectivity.SetCurrent);
+				BridgeIfRegistered<IDeviceDisplay>(services, DeviceDisplay.SetCurrent);
+				BridgeIfRegistered<IDeviceInfo>(services, DeviceInfo.SetCurrent);
+				BridgeIfRegistered<IFileSystem>(services, FileSystem.SetCurrent);
+				BridgeIfRegistered<IGeocoding>(services, Geocoding.SetCurrent);
+			}
+
+			/// <summary>
+			/// Resolves a DI-registered implementation and assigns it to the corresponding static facade.
+			/// Note: The resolved instance is stored in a static field for the app lifetime, effectively
+			/// promoting it to singleton scope regardless of its DI registration lifetime. Services bridged
+			/// here should be registered as Singleton for correct behavior.
+			/// </summary>
+			static void BridgeIfRegistered<T>(IServiceProvider services, Action<T?> setter) where T : class
+			{
+				var impl = services.GetService<T>();
+				if (impl is not null)
+					setter(impl);
+			}
+
 			private static async void SetAppActions(IServiceProvider services, List<AppAction> appActions)
 			{
 				try

src/Core/tests/UnitTests/Dispatching/DispatcherTests.cs

@@ -10,6 +10,15 @@ namespace Microsoft.Maui.UnitTests.Dispatching
 	// Technically these tests are useless because they cannot test shipping code as they are
 	// none of the platforms. However, they sort of do test the test dispatcher...
 	[Category(TestCategory.Core, TestCategory.Dispatching)]
+	// DispatcherTests mutates the static DispatcherProvider.Current. Other test
+	// classes that build a MauiApp capture that singleton via DI (see
+	// AppHostBuilderExtensions.ConfigureDispatching's IDispatcherProvider factory)
+	// and the MainThreadBridgeInitializer / ApplicationDispatcherInitializer call
+	// IDispatcher resolution at MauiApp.Build() time. If DispatcherTests' Dispose
+	// runs concurrently and disposes its DispatcherProviderStub's ThreadLocal,
+	// those bystander tests throw ObjectDisposedException. Serialize via the
+	// shared MainThreadStaticState collection.
+	[Collection("MainThreadStaticState")]
 	public class DispatcherTests : IDisposable
 	{
 		DispatcherProviderStub _dispatcherProvider;