[Windows] Lifecycle: Add AppInstance activated event

src/Controls/samples/Controls.Sample/MauiProgram.cs

@@ -4,6 +4,7 @@
 using System.Diagnostics.Metrics;
 using System.Linq;
 using System.Runtime.CompilerServices;
+using System.Threading.Tasks;
 using Maui.Controls.Sample.Controls;
 using Maui.Controls.Sample.Pages;
 using Maui.Controls.Sample.Services;
@@ -29,6 +30,8 @@
 #if ANDROID
 using Android.Gms.Common;
 using Android.Gms.Maps;
+#elif WINDOWS
+using Microsoft.Windows.AppLifecycle;
 #endif
 
 namespace Maui.Controls.Sample
@@ -286,6 +289,7 @@ static string GetTags(IEnumerable<KeyValuePair<string, object?>> tags) =>
 					events.AddWindows(windows => windows
 						// .OnPlatformMessage((a, b) => 
 						//	LogEvent(nameof(WindowsLifecycle.OnPlatformMessage)))
+						.OnAppInstanceActivated((application, args) => HandleWindowsAppInstanceActivated(application, args))
 						.OnActivated((a, b) => LogEvent(nameof(WindowsLifecycle.OnActivated)))
 						.OnClosed((a, b) => LogEvent(nameof(WindowsLifecycle.OnClosed)))
 						.OnLaunched((a, b) => LogEvent(nameof(WindowsLifecycle.OnLaunched)))
@@ -310,6 +314,34 @@ static bool LogEvent(string eventName, string? type = null)
 						Debug.WriteLine($"Lifecycle event: {eventName}{(type == null ? "" : $" ({type})")}");
 						return true;
 					}
+
+#if WINDOWS
+					static bool HandleWindowsAppInstanceActivated(Microsoft.UI.Xaml.Application application, AppActivationArguments args)
+					{
+						LogEvent(nameof(WindowsLifecycle.OnAppInstanceActivated), args.Kind.ToString());
+
+						// This sample opts into single-instancing from the MAUI lifecycle callback
+						// instead of a custom Program.cs entry point.
+						var keyInstance = AppInstance.FindOrRegisterForKey("Maui.Controls.Sample");
+
+						if (!keyInstance.IsCurrent)
+						{
+							// The WinAppSDK single-instance guidance redirects the activation and then
+							// terminates the losing instance immediately. Using Kill here avoids leaving
+							// a headless process around that can continue to hold build outputs open.
+							keyInstance.RedirectActivationToAsync(args).AsTask().GetAwaiter().GetResult();
+							Process.GetCurrentProcess().Kill();
+							return true;
+						}
+
+						if (Application.Current?.Windows.FirstOrDefault() is Window window)
+							// Redirected activations can arrive off the UI thread, so hop through the
+							// MAUI window dispatcher before re-activating the existing window.
+							window.Dispatcher.Dispatch(() => Application.Current.ActivateWindow(window));
+
+						return false;
+					}
+#endif
 				});
 
 			// Adapt to dual-screen and foldable Android devices like Surface Duo, includes TwoPaneView layout control

src/Core/src/LifecycleEvents/Windows/WindowsLifecycle.cs

@@ -1,7 +1,10 @@
-namespace Microsoft.Maui.LifecycleEvents
+using Microsoft.Windows.AppLifecycle;
+
+namespace Microsoft.Maui.LifecycleEvents
 {
 	public static class WindowsLifecycle
 	{
+		public delegate bool OnAppInstanceActivated(UI.Xaml.Application application, AppActivationArguments args);
 		public delegate void OnActivated(UI.Xaml.Window window, UI.Xaml.WindowActivatedEventArgs args);
 		public delegate void OnClosed(UI.Xaml.Window window, UI.Xaml.WindowEventArgs args);
 		public delegate void OnLaunched(UI.Xaml.Application application, UI.Xaml.LaunchActivatedEventArgs args);

src/Core/src/LifecycleEvents/Windows/WindowsLifecycleBuilderExtensions.cs

@@ -2,6 +2,7 @@
 {
 	public static class WindowsLifecycleBuilderExtensions
 	{
+		public static IWindowsLifecycleBuilder OnAppInstanceActivated(this IWindowsLifecycleBuilder lifecycle, WindowsLifecycle.OnAppInstanceActivated del) => lifecycle.OnEvent(del);
 		public static IWindowsLifecycleBuilder OnActivated(this IWindowsLifecycleBuilder lifecycle, WindowsLifecycle.OnActivated del) => lifecycle.OnEvent(del);
 		public static IWindowsLifecycleBuilder OnClosed(this IWindowsLifecycleBuilder lifecycle, WindowsLifecycle.OnClosed del) => lifecycle.OnEvent(del);
 		public static IWindowsLifecycleBuilder OnLaunching(this IWindowsLifecycleBuilder lifecycle, WindowsLifecycle.OnLaunching del) => lifecycle.OnEvent(del);

src/Core/src/Platform/Windows/MauiWinUIApplication.cs

@@ -1,7 +1,8 @@
-using System;
+using System;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Maui.Hosting;
 using Microsoft.Maui.LifecycleEvents;
+using Microsoft.Windows.AppLifecycle;
 
 namespace Microsoft.Maui
 {
@@ -20,9 +21,17 @@ public abstract class MauiWinUIApplication : UI.Xaml.Application, IPlatformAppli
 
 		protected override void OnLaunched(UI.Xaml.LaunchActivatedEventArgs args)
 		{
-			// Windows running on a different thread will "launch" the app again
+			LaunchActivatedEventArgs = args;
+
+			var launchActivation = AppInstance.GetCurrent().GetActivatedEventArgs();
+
+			// A running WinUI app can be activated again without rebuilding the MAUI application.
+			// Reuse the existing services and let activation handlers short-circuit the relaunch path.
 			if (_application != null && _services != null)
 			{
+				if (launchActivation is AppActivationArguments activatedEventArgs && OnAppInstanceActivated(activatedEventArgs))
+					return;
+
 				_services.InvokeLifecycleEvents<WindowsLifecycle.OnLaunching>(del => del(this, args));
 				_services.InvokeLifecycleEvents<WindowsLifecycle.OnLaunched>(del => del(this, args));
 				return;
@@ -37,6 +46,14 @@ protected override void OnLaunched(UI.Xaml.LaunchActivatedEventArgs args)
 
 			_services = applicationContext.Services;
 
+			// Future AppInstance activation callbacks need the app-level services to exist first.
+			RegisterForAppInstanceActivated();
+
+			// Run the initial activation after services are available, but before OnLaunching/window creation,
+			// so handlers can redirect or suppress the default startup flow.
+			if (launchActivation is AppActivationArguments initialActivation && OnAppInstanceActivated(initialActivation))
+				return;
+
 			_services.InvokeLifecycleEvents<WindowsLifecycle.OnLaunching>(del => del(this, args));
 
 			_application = _services.GetRequiredService<IApplication>();
@@ -48,10 +65,41 @@ protected override void OnLaunched(UI.Xaml.LaunchActivatedEventArgs args)
 			_services.InvokeLifecycleEvents<WindowsLifecycle.OnLaunched>(del => del(this, args));
 		}
 
+		protected virtual bool OnAppInstanceActivated(AppActivationArguments args)
+		{
+			var wasHandled = false;
+
+			_services?.InvokeLifecycleEvents<WindowsLifecycle.OnAppInstanceActivated>(del =>
+			{
+				// Preserve any earlier "handled" result so multiple listeners can participate safely.
+				wasHandled = del(this, args) || wasHandled;
+			});
+
+			return wasHandled;
+		}
+
+		void RegisterForAppInstanceActivated()
+		{
+			if (_isRegisteredForAppInstanceActivated)
+				return;
+
+			_isRegisteredForAppInstanceActivated = true;
+
+			// After startup, later file/protocol/redirected activations are delivered through AppInstance.
+			AppInstance.GetCurrent().Activated += HandleAppInstanceActivated;
+
+			void HandleAppInstanceActivated(object? sender, AppActivationArguments args)
+			{
+				OnAppInstanceActivated(args);
+			}
+		}
+
 		public static new MauiWinUIApplication Current => (MauiWinUIApplication)UI.Xaml.Application.Current;
 
 		public UI.Xaml.LaunchActivatedEventArgs LaunchActivatedEventArgs { get; protected set; } = null!;
 
+		bool _isRegisteredForAppInstanceActivated;
+
 		IServiceProvider? _services;
 
 		IApplication? _application;

src/Core/src/PublicAPI/net-windows/PublicAPI.Unshipped.txt

@@ -1,2 +1,6 @@
-#nullable enable
+#nullable enable
+Microsoft.Maui.LifecycleEvents.WindowsLifecycle.OnAppInstanceActivated
 override Microsoft.Maui.Platform.MauiPasswordTextBox.OnCreateAutomationPeer() -> Microsoft.UI.Xaml.Automation.Peers.AutomationPeer!
+static Microsoft.Maui.LifecycleEvents.WindowsLifecycleBuilderExtensions.OnAppInstanceActivated(this Microsoft.Maui.LifecycleEvents.IWindowsLifecycleBuilder! lifecycle, Microsoft.Maui.LifecycleEvents.WindowsLifecycle.OnAppInstanceActivated! del) -> Microsoft.Maui.LifecycleEvents.IWindowsLifecycleBuilder!
+virtual Microsoft.Maui.LifecycleEvents.WindowsLifecycle.OnAppInstanceActivated.Invoke(Microsoft.UI.Xaml.Application! application, Microsoft.Windows.AppLifecycle.AppActivationArguments! args) -> bool
+virtual Microsoft.Maui.MauiWinUIApplication.OnAppInstanceActivated(Microsoft.Windows.AppLifecycle.AppActivationArguments! args) -> bool

src/Core/tests/DeviceTests.Shared/MauiProgramDefaults.cs

@@ -27,7 +27,7 @@ public static MauiApp CreateMauiApp(List<Assembly> testAssemblies)
 			});
 		}
 
-		public static MauiApp CreateMauiApp(Func<IServiceProvider, TestOptions> options)
+		public static MauiApp CreateMauiApp(Func<IServiceProvider, TestOptions> options, Action<MauiAppBuilder> configureBuilder = null)
 		{
 			var appBuilder = MauiApp.CreateBuilder();
 
@@ -95,6 +95,8 @@ public static MauiApp CreateMauiApp(Func<IServiceProvider, TestOptions> options)
 				ValidateScopes = true,
 			}));
 
+			configureBuilder?.Invoke(appBuilder);
+
 			var mauiApp = appBuilder.Build();
 
 			DefaultTestApp = mauiApp.Services.GetRequiredService<IApplication>();

src/Core/tests/DeviceTests/LifecycleEventOrderTests.Android.cs

@@ -0,0 +1,43 @@
+using System.Linq;
+using Microsoft.Maui.LifecycleEvents;
+using Xunit;
+
+namespace Microsoft.Maui.DeviceTests
+{
+	[Category(TestCategory.Lifecycle)]
+	public class LifecycleEventOrderTests
+	{
+		[Fact(DisplayName = "Android lifecycle events fire during startup")]
+		public void AndroidLifecycleEventsFireDuringStartup()
+		{
+			var log = MauiProgram.LifecycleEventLog;
+
+			Assert.Contains(nameof(AndroidLifecycle.OnCreate), log);
+			Assert.Contains(nameof(AndroidLifecycle.OnStart), log);
+			Assert.Contains(nameof(AndroidLifecycle.OnResume), log);
+		}
+
+		[Fact(DisplayName = "Android lifecycle events fire in correct order")]
+		public void AndroidLifecycleEventsFireInCorrectOrder()
+		{
+			var log = MauiProgram.LifecycleEventLog;
+
+			var createIndex = log.IndexOf(nameof(AndroidLifecycle.OnCreate));
+			var startIndex = log.IndexOf(nameof(AndroidLifecycle.OnStart));
+			var resumeIndex = log.IndexOf(nameof(AndroidLifecycle.OnResume));
+
+			// Expected startup order: OnCreate → OnStart → OnResume
+			Assert.True(createIndex < startIndex,
+				$"Expected OnCreate before OnStart. Log: [{string.Join(", ", log)}]");
+			Assert.True(startIndex < resumeIndex,
+				$"Expected OnStart before OnResume. Log: [{string.Join(", ", log)}]");
+		}
+
+		[Fact(DisplayName = "OnCreate fires exactly once during startup")]
+		public void OnCreateFiresExactlyOnce()
+		{
+			var count = MauiProgram.LifecycleEventLog.Count(e => e == nameof(AndroidLifecycle.OnCreate));
+			Assert.Equal(1, count);
+		}
+	}
+}

src/Core/tests/DeviceTests/LifecycleEventOrderTests.Windows.cs

@@ -0,0 +1,47 @@
+using System.Linq;
+using Microsoft.Maui.LifecycleEvents;
+using Xunit;
+
+namespace Microsoft.Maui.DeviceTests
+{
+	[Category(TestCategory.Lifecycle)]
+	public class LifecycleEventOrderTests
+	{
+		[Fact(DisplayName = "Windows lifecycle events fire during startup")]
+		public void WindowsLifecycleEventsFireDuringStartup()
+		{
+			var log = MauiProgram.LifecycleEventLog;
+
+			Assert.Contains(nameof(WindowsLifecycle.OnAppInstanceActivated), log);
+			Assert.Contains(nameof(WindowsLifecycle.OnLaunching), log);
+			Assert.Contains(nameof(WindowsLifecycle.OnLaunched), log);
+			Assert.Contains(nameof(WindowsLifecycle.OnWindowCreated), log);
+		}
+
+		[Fact(DisplayName = "Windows lifecycle events fire in correct order")]
+		public void WindowsLifecycleEventsFireInCorrectOrder()
+		{
+			var log = MauiProgram.LifecycleEventLog;
+
+			var activatedIndex = log.IndexOf(nameof(WindowsLifecycle.OnAppInstanceActivated));
+			var launchingIndex = log.IndexOf(nameof(WindowsLifecycle.OnLaunching));
+			var windowCreatedIndex = log.IndexOf(nameof(WindowsLifecycle.OnWindowCreated));
+			var launchedIndex = log.IndexOf(nameof(WindowsLifecycle.OnLaunched));
+
+			// Expected startup order: OnAppInstanceActivated → OnLaunching → OnWindowCreated → OnLaunched
+			Assert.True(activatedIndex < launchingIndex,
+				$"Expected OnAppInstanceActivated before OnLaunching. Log: [{string.Join(", ", log)}]");
+			Assert.True(launchingIndex < windowCreatedIndex,
+				$"Expected OnLaunching before OnWindowCreated. Log: [{string.Join(", ", log)}]");
+			Assert.True(windowCreatedIndex < launchedIndex,
+				$"Expected OnWindowCreated before OnLaunched. Log: [{string.Join(", ", log)}]");
+		}
+
+		[Fact(DisplayName = "OnAppInstanceActivated fires exactly once during startup")]
+		public void OnAppInstanceActivatedFiresExactlyOnce()
+		{
+			var count = MauiProgram.LifecycleEventLog.Count(e => e == nameof(WindowsLifecycle.OnAppInstanceActivated));
+			Assert.Equal(1, count);
+		}
+	}
+}

src/Core/tests/DeviceTests/LifecycleEventOrderTests.iOS.cs

@@ -0,0 +1,41 @@
+using System.Linq;
+using Microsoft.Maui.LifecycleEvents;
+using Xunit;
+
+namespace Microsoft.Maui.DeviceTests
+{
+	[Category(TestCategory.Lifecycle)]
+	public class LifecycleEventOrderTests
+	{
+		[Fact(DisplayName = "iOS lifecycle events fire during startup")]
+		public void iOSLifecycleEventsFireDuringStartup()
+		{
+			var log = MauiProgram.LifecycleEventLog;
+
+			Assert.Contains(nameof(iOSLifecycle.FinishedLaunching), log);
+		}
+
+		[Fact(DisplayName = "FinishedLaunching fires before OnActivated")]
+		public void FinishedLaunchingFiresBeforeOnActivated()
+		{
+			var log = MauiProgram.LifecycleEventLog;
+
+			var launchIndex = log.IndexOf(nameof(iOSLifecycle.FinishedLaunching));
+			Assert.True(launchIndex >= 0, "FinishedLaunching should have fired");
+
+			var activatedIndex = log.IndexOf(nameof(iOSLifecycle.OnActivated));
+			if (activatedIndex >= 0)
+			{
+				Assert.True(launchIndex < activatedIndex,
+					$"Expected FinishedLaunching before OnActivated. Log: [{string.Join(", ", log)}]");
+			}
+		}
+
+		[Fact(DisplayName = "FinishedLaunching fires exactly once during startup")]
+		public void FinishedLaunchingFiresExactlyOnce()
+		{
+			var count = MauiProgram.LifecycleEventLog.Count(e => e == nameof(iOSLifecycle.FinishedLaunching));
+			Assert.Equal(1, count);
+		}
+	}
+}

src/Core/tests/DeviceTests/MauiProgram.cs

@@ -14,6 +14,12 @@ public static class MauiProgram
 		public static UI.Xaml.Window DefaultWindow => MauiProgramDefaults.DefaultWindow;
 #endif
 
+		/// <summary>
+		/// Records platform lifecycle event names in the order they fire during app startup.
+		/// Used by LifecycleEventOrderTests to validate event ordering.
+		/// </summary>
+		public static List<string> LifecycleEventLog { get; } = new();
+
 		public static IApplication DefaultTestApp { get; private set; }
 
 		public static MauiApp CreateMauiApp() =>
@@ -29,6 +35,51 @@ public static MauiApp CreateMauiApp() =>
 				};
 
 				return options;
+			},
+			configureBuilder: builder =>
+			{
+				builder.ConfigureLifecycleEvents(life =>
+				{
+#if ANDROID
+					life.AddAndroid(android =>
+					{
+						android.OnCreate((a, b) =>
+							LifecycleEventLog.Add(nameof(AndroidLifecycle.OnCreate)));
+						android.OnStart(a =>
+							LifecycleEventLog.Add(nameof(AndroidLifecycle.OnStart)));
+						android.OnResume(a =>
+							LifecycleEventLog.Add(nameof(AndroidLifecycle.OnResume)));
+						android.OnPostResume(a =>
+							LifecycleEventLog.Add(nameof(AndroidLifecycle.OnPostResume)));
+					});
+#elif IOS || MACCATALYST
+					life.AddiOS(ios =>
+					{
+						ios.FinishedLaunching((app, options) =>
+						{
+							LifecycleEventLog.Add(nameof(iOSLifecycle.FinishedLaunching));
+							return true;
+						});
+						ios.OnActivated(app =>
+							LifecycleEventLog.Add(nameof(iOSLifecycle.OnActivated)));
+					});
+#elif WINDOWS
+					life.AddWindows(windows =>
+					{
+						windows.OnAppInstanceActivated((app, args) =>
+						{
+							LifecycleEventLog.Add(nameof(WindowsLifecycle.OnAppInstanceActivated));
+							return false;
+						});
+						windows.OnLaunching((app, args) =>
+							LifecycleEventLog.Add(nameof(WindowsLifecycle.OnLaunching)));
+						windows.OnLaunched((app, args) =>
+							LifecycleEventLog.Add(nameof(WindowsLifecycle.OnLaunched)));
+						windows.OnWindowCreated(w =>
+							LifecycleEventLog.Add(nameof(WindowsLifecycle.OnWindowCreated)));
+					});
+#endif
+				});
 			});
 	}
 }

src/Core/tests/DeviceTests/TestCategory.cs

@@ -51,5 +51,6 @@ public static class TestCategory
 		public const string View = "View";
 		public const string WebView = "WebView";
 		public const string Window = "Window";
+		public const string Lifecycle = "Lifecycle";
 	}
 }