.net MAUI应用生命周期

.NET Multi-platform App UI (.NET MAUI) 应用通常有四种执行状态：“未运行”、“运行中”、“已停用”和“已停止”。 当应用从未运行状态转换为运行状态、从运行状态转换为已停用状态、从已停用状态转换为已停止状态、从已停止状态转换为运行状态，以及从已停止状态转换为未运行状态时，.NET MAUI 会引发 Window 类的跨平台生命周期事件。

下图显示了 .NET MAUI 应用生命周期的概述：

在此图中，灰色椭圆表示应用未加载到内存中。 浅蓝色椭圆表示应用在内存中。 圆弧上的文本指示 .NET MAUI 引发的并且向正在运行的应用提供通知的事件。

应用的执行状态取决于应用的历史记录。 例如，首次安装应用或启动设备时，可以将应用视为“未运行”。 启动应用后，将引发 Created 与 Activated 事件，并且应用处于“运行中”状态。 如果其他应用窗口获得焦点，则会引发 Deactivated 事件并且应用处于“已停用”状态。 如果用户切换到其他应用或返回到设备的主屏幕，以便应用窗口不再可见，则会引发 Deactivated 与 Stopped 事件，并且应用处于“已停止”状态。 如果用户返回到应用，则会引发 Resuming 事件，并且应用处于“运行中”状态。 或者，应用在运行时可能会由用户终止。 在这种情况下，应用处于“已停用”状态，然后处于“已停止”状态，将引发 Destroying 事件，并且应用处于“未运行”状态。 同样，设备可能会因资源限制而停止，进而将应用终止，此时会引发 Destroying 事件并且应用处于“未运行”状态。

此外，当引发平台生命周期事件时，.NET MAUI 会使应用得到通知。 有关详细信息，请参阅平台生命周期事件。

跨平台生命周期事件

Window 类定义以下跨平台生命周期事件：

事件	描述	采取的操作
Created	创建本机窗口后将引发此事件。 此时，跨平台窗口将具有本机窗口处理程序，但该窗口可能尚不可见。
Activated	当窗口已激活且已经或将要变为焦点窗口时，将引发此事件。
Deactivated	当窗口不再是焦点窗口时，将引发此事件。 但是，窗口可能依然可见。
Stopped	当窗口不再可见时，将引发此事件。 无法保证应用将从此状态继续运行，因为它可能由操作系统终止。	断开与任何长期进程的连接，或取消可能消耗设备资源的任何挂起请求。
Resumed	当应用在被停止后继续运行时，将引发此事件。 应用首次启动时不会引发此事件，并且仅当之前已经引发 Stopped 事件时才能引发。	订阅任何所需的事件，并刷新可见页面上的任何内容。
Destroying	当本机窗口被销毁并解除分配时，将引发此事件。 重新打开应用时，可能会对新的本机窗口使用相同的跨平台窗口。	移除已附加到本机窗口的任何事件订阅。

这些跨平台事件映射到不同的平台事件，下表显示了此映射：

活动	Android	iOS	Windows
Created	OnPostCreate	FinishedLaunching	Created
Activated	OnResume	OnActivated	Activated（CodeActivated 和 PointerActivated）
Deactivated	OnPause	OnResignActivation	Activated (Deactivated)
Stopped	OnStop	DidEnterBackground	VisibilityChanged
Resumed	OnRestart	WillEnterForeground	Resumed
Destroying	OnDestroy	WillTerminate	Closed

此外，Window 类还定义了当窗口关闭或进入后台状态时在 iOS 和 Mac Catalyst 上引发的 Backgrounding 事件。 BackgroundingEventArgs 对象附带此事件，任何 string 状态都应保存到 BackgroundingEventArgs 对象的 State 属性，OS 将一直保留该属性，直到恢复窗口为止。 当窗口恢复时，状态由 IActivationState 参数提供给 CreateWindow 替代。

除了这些事件，Window 类还具有以下可替代的生命周期方法：

• OnCreated，在引发 Created 事件时调用。
• OnActivated，在引发 Activated 事件时调用。
• OnDeactivated，在引发 Deactivated 事件时调用。
• OnStopped，在引发 Stopped 事件时调用。
• OnResumed，在引发 Resumed 事件时调用。
• OnDestroying，在引发 Destroying 事件时调用。
• OnBackgrounding，在引发 Backgrounding 事件时调用。

要订阅 Window 生命周期事件，请重写 App 类中的 CreateWindow 方法，以创建可在其上订阅事件的 Window 实例：

C#复制

namespace MyMauiApp
{public partial class App : Application{public App(){InitializeComponent();MainPage = new MainPage();}protected override Window CreateWindow(IActivationState activationState){Window window = base.CreateWindow(activationState);window.Created += (s, e) =>{// Custom logic};return window;}}
}

或者，若要使用生命周期重写，请创建派生自 Window 类的类

C#复制

namespace MyMauiApp
{public class MyWindow : Window{public MyWindow() : base(){}public MyWindow(Page page) : base(page){}protected override void OnCreated(){// Register services}}
}

然后，可以通过重写 App 类中的 CreateWindow 方法来使用 Window 派生类，以返回 MyWindow 实例。

 警告

如果设置了 App.MainPage 属性，并且 CreateWindow 方法使用接受 Page 参数的重写创建 Window 对象，则将引发 InvalidOperationException 对象。

平台生命周期事件

.NET MAUI 定义了在响应所引发的平台生命周期事件时调用的委托。 可以使用在调用委托时执行的命名方法或匿名函数为这些委托指定处理程序。 通过此机制，应用可在常见平台生命周期事件发生时收到通知。

 重要

ConfigureLifecycleEvents 方法位于 Microsoft.Maui.LifecycleEvents 命名空间中。

Android

下表列出了为响应所引发的 Android 生命周期事件而调用的 .NET MAUI 委托：

委托	参数	描述	评论
OnActivityResult	Android.App.Activity、int、Android.App.Result、Android.Content.Intent?	启动的活动退出时调用。
OnApplicationConfigurationChanged	Android.App.Application、Android.Content.Res.Configuration	在组件运行期间设备配置发生更改时调用。
OnApplicationCreate	Android.App.Application	应用启动后，在创建活动、服务或接收方对象（不包括内容提供程序）之前调用。
OnApplicationCreating	Android.App.Application	应用启动时，在活动、服务或接收方对象（不包括内容提供程序）创建之前调用。
OnApplicationLowMemory	Android.App.Application	当系统内存不足时调用，并且正在运行的进程应减少其内存使用率。
OnApplicationTrimMemory	Android.App.Application、Android.Content.TrimMemory	当操作系统确定某个进程应当从其自身删减不需要的内存时调用。
OnBackPressed	Android.App.Activity	当活动检测到按下后退键时调用。
OnConfigurationChanged	Android.App.Activity、Android.Content.Res.Configuration	在活动运行期间设备配置发生更改时调用。
OnCreate	Android.App.Activity、Android.OS.Bundle?	创建活动时引发。
OnDestroy	Android.App.Activity	在活动完成时调用，或者因为系统暂时销毁活动实例以节省空间而调用。	始终调用超级类的实现。
OnNewIntent	Android.App.Activity、Android.Content.Intent?	当活动在活动堆栈的顶部重新启动时调用，而不是启动活动的新实例。
OnPause	Android.App.Activity	当活动进入后台但尚未终止时调用。	始终调用超级类的实现。
OnPostCreate	Android.App.Activity、Android.OS.Bundle?	在调用 OnStart 和 OnRestoreInstanceState 之后，活动启动完成时调用。	始终调用超级类的实现。 这是应用通常不应使用的仅限系统的事件。
OnPostResume	Android.App.Activity	在调用 OnResume 之后，活动恢复完成时调用。	始终调用超级类的实现。 这是应用通常不应使用的仅限系统的事件。
OnRequestPermissionsResult	Android.App.Activity、int、string[]、Android.Content.PM.Permission[]	作为请求权限的结果的回叫调用。
OnRestart	Android.App.Activity	在 OnStop 后调用。此时当前活动重新显示给用户（用户已导航回该活动）。	始终调用超级类的实现。
OnRestoreInstanceState	Android.App.Activity、Android.OS.Bundle	OnStart 后调用。此时活动从以前保存的状态重新初始化。
OnResume	Android.App.Activity	OnRestoreInstanceState、OnRestart 或 OnPause 后调用，以指示活动处于活动状态并且已准备好接收输入。
OnSaveInstanceState	Android.App.Activity、Android.OS.Bundle	调用来从被终止的活动中检索每个实例的状态，以便可以在 OnCreate 或 OnRestoreInstanceState 中恢复状态。
OnStart	Android.App.Activity	在 OnCreate 或 OnRestart 之后调用，此时活动已经停止，但正在显示给用户。	始终调用超级类的实现。
OnStop	Android.App.Activity	当用户不再看到活动时调用。	始终调用超级类的实现。

 重要

每个委托都有一个相应的同名扩展方法，可以调用该方法来注册委托的处理程序。

若要响应要调用的 Android 生命周期委托，请在 MauiProgram 类的 CreateMauiapp 方法中在 MauiAppBuilder 对象上调用 ConfigureLifecycleEvents 方法。 然后，在对象 ILifecycleBuilder 上，调用 AddAndroid 方法并指定为所需委托注册处理程序的 Action：

C#复制

using Microsoft.Maui.LifecycleEvents;namespace PlatformLifecycleDemo
{public static class MauiProgram{public static MauiApp CreateMauiApp(){var builder = MauiApp.CreateBuilder();builder.UseMauiApp<App>().ConfigureLifecycleEvents(events =>{
#if ANDROIDevents.AddAndroid(android => android.OnActivityResult((activity, requestCode, resultCode, data) => LogEvent(nameof(AndroidLifecycle.OnActivityResult), requestCode.ToString())).OnStart((activity) => LogEvent(nameof(AndroidLifecycle.OnStart))).OnCreate((activity, bundle) => LogEvent(nameof(AndroidLifecycle.OnCreate))).OnBackPressed((activity) => LogEvent(nameof(AndroidLifecycle.OnBackPressed)) && false).OnStop((activity) => LogEvent(nameof(AndroidLifecycle.OnStop))));
#endifstatic bool LogEvent(string eventName, string type = null){System.Diagnostics.Debug.WriteLine($"Lifecycle event: {eventName}{(type == null ? string.Empty : $" ({type})")}");return true;}});return builder.Build();}}
}

有关 Android 应用生命周期的详细信息，请参阅 developer.android.com 上的了解活动生命周期。

iOS 和 Mac Catalyst

下表列出了为响应正在引发的 iOS 和 Mac Catalyst 生命周期事件而调用的 .NET MAUI 委托：

委托	参数	描述
ApplicationSignificantTimeChange	UIKit.UIApplication	在发生重大时间更改（例如午夜、运营商更改时间或夏令时开始或停止）时调用。
ContinueUserActivity	UIKit.UIApplication、Foundation.NSUserActivity、UIKit.UIApplicationRestorationHandler	当应用收到与用户活动关联的数据（例如使用 Handoff 从其他设备传输活动）时调用。
DidEnterBackground	UIKit.UIApplication	当应用进入后台时调用。
FinishedLaunching	UIKit.UIApplication、Foundation.NSDictionary	在应用启动时调用。
OnActivated	UIKit.UIApplication	在应用启动时调用，每次应用返回到前台时调用。
OnResignActivation	UIKit.UIApplication	在应用即将进入后台、暂停运行或用户遇到中断情形（如接到电话或短信）时调用。
OpenUrl	UIKit.UIApplication、Foundation.NSDictionary	当应用应打开指定的 URL 时调用。
PerformActionForShortcutItem	UIKit.UIApplication、UIKit.UIApplicationShortcutItem、UIKit.UIOperationHandler	启动主屏幕快速操作时调用。
PerformFetch	UIKit.UIApplication、Action<UIBackgroundFetchResult>	需要告知应用可开始提取操作以下载可用数据时调用。
SceneContinueUserActivity	UIKit.UIScene、Foundation.NSUserActivity	需要处理指定的与移交相关的活动时调用。
SceneDidDisconnect	UIKit.UIScene	从应用中删除场景时调用。
SceneDidEnterBackground	UIKit.UIScene	当场景在后台运行且未出现在屏幕上时调用。
SceneDidFailToContinueUserActivity	UIKit.UIScene、string、Foundation.NSError	需要通知用户无法完成活动时调用。
SceneDidUpdateUserActivity	UIKit.UIScene、Foundation.NSUserActivity	更新指定活动时调用。
SceneOnActivated	UIKit.UIScene	当场景处于活动状态并能够响应用户事件时调用。
SceneOnResignActivation	UIKit.UIScene	当场景即将退出活动状态并停止响应用户事件时调用。
SceneOpenUrl	UIKit.UIScene、Foundation.NSSet<UIKit.UIOpenUrlContext>	当场景要求打开一个或多个 URL 时调用。
SceneRestoreInteractionState	UIKit.UIScene、Foundation.NSUserActivity	需要还原活动状态时调用。
SceneWillConnect	UIKit.UIScene、UIKit.UISceneSession、UIKit.UISceneConnectionOptions	将场景添加到应用时调用。
SceneWillContinueUserActivity	UIKit.UIScene、string	需要准备接收与移交相关的数据时调用。
SceneWillEnterForeground	UIKit.UIScene	当场景即将在前台运行并且对用户可见时调用。
WillEnterForeground	UIKit.UIApplication	当应用将从后台状态返回时调用。
WillFinishLaunching	UIKit.UIApplication、Foundation.NSDictionary	在应用已开始启动但尚未发生状态还原时调用。
WillTerminate	UIKit.UIApplication	在应用因内存限制而终止，或者由用户直接终止的情况下调用。
WindowSceneDidUpdateCoordinateSpace	UIKit.UIWindowScene、UIKit.IUICoordinateSpace、UIKit.UIInterfaceOrientation、UIKit.UITraitCollection	场景的大小、方向或特征发生更改时调用。

 重要

除 PerformFetch 以外，每个委托都有相应的同名扩展方法，可以调用该方法来注册委托的处理程序。

若要响应要调用的 iOS 和 Mac Catalyst 生命周期委托，请在 MauiProgram 类的 CreateMauiapp 方法中对 MauiAppBuilder 对象调用 ConfigureLifecycleEvents 方法。 然后，在 ILifecycleBuilder 对象上调用 AddiOS 方法并指定为所需委托注册处理程序的 Action：

C#复制

using Microsoft.Maui.LifecycleEvents;namespace PlatformLifecycleDemo
{public static class MauiProgram{public static MauiApp CreateMauiApp(){var builder = MauiApp.CreateBuilder();builder.UseMauiApp<App>().ConfigureLifecycleEvents(events =>{
#if IOS || MACCATALYSTevents.AddiOS(ios => ios.OnActivated((app) => LogEvent(nameof(iOSLifecycle.OnActivated))).OnResignActivation((app) => LogEvent(nameof(iOSLifecycle.OnResignActivation))).DidEnterBackground((app) => LogEvent(nameof(iOSLifecycle.DidEnterBackground))).WillTerminate((app) => LogEvent(nameof(iOSLifecycle.WillTerminate))));
#endifstatic bool LogEvent(string eventName, string type = null){System.Diagnostics.Debug.WriteLine($"Lifecycle event: {eventName}{(type == null ? string.Empty : $" ({type})")}");return true;}});return builder.Build();}}
}

要详细了解 iOS 应用生命周期，请参阅 developer.apple.com 上的管理应用的生命周期。

Windows

下表列出了为响应引发的 Windows 生命周期事件而调用的 .NET MAUI 委托：

委托	参数	描述
OnActivated	Microsoft.UI.Xaml.Window、Microsoft.UI.Xaml.WindowActivatedEventArgs	如果应用未恢复，在引发平台 Activated 事件时调用。
OnClosed	Microsoft.UI.Xaml.Window、Microsoft.UI.Xaml.WindowEventArgs	在引发平台 Closed 事件时调用。
OnLaunched	Microsoft.UI.Xaml.Window、Microsoft.UI.Xaml.LaunchActivatedEventArgs	创建并激活本机窗口后，由 .NET MAUI 的 Application.OnLaunched 重写调用。
OnLaunching	Microsoft.UI.Xaml.Window、Microsoft.UI.Xaml.LaunchActivatedEventArgs	在创建和激活本机窗口前，由 .NET MAUI 的 Application.OnLaunched 重写调用。
OnPlatformMessage	Microsoft.UI.Xaml.Window、WindowsPlatformMessageEventArgs	当 .NET MAUI 接收到特定的本机 Windows 消息时调用。
OnPlatformWindowSubclassed	Microsoft.UI.Xaml.Window、WindowsPlatformWindowSubclassedEventArgs	由 .NET MAUI 在 Win32 窗口被子类化时调用。
OnResumed	Microsoft.UI.Xaml.Window	如果应用正在恢复，在引发平台 Activated 事件时调用。
OnVisibilityChanged	Microsoft.UI.Xaml.Window、Microsoft.UI.Xaml.WindowVisibilityChangedEventArgs	引发平台 VisibilityChanged 事件时调用。
OnWindowCreated	Microsoft.UI.Xaml.Window	为跨平台 Window 创建本机窗口时调用。

.NET MAUI 使用 OnPlatformMessage 委托将特定的本机 Windows 消息公开为生命周期事件。 此委托附带的 WindowsPlatformMessageEventArgs 对象包含类型为 uint 的 MessageId 属性。 可以检查此属性的值以确定传递到应用窗口的消息。 有关 Windows 消息的详细信息，请参阅 Windows 消息（Win32 和 C++ 入门）。 有关窗口消息常量的列表，请参阅 Window 通知。

 重要

每个委托都有一个相应的同名扩展方法，可以调用该方法来注册委托的处理程序。

要响应正在调用的 Windows 生命周期委托，请在 MauiProgram 类的 CreateMauiApp 方法中对 MauiAppBuilder 对象调用 ConfigureLifecycleEvents 方法。 然后，在 ILifecycleBuilder 对象上调用 AddWindows 方法并指定为所需委托注册处理程序的 Action：

C#复制

using Microsoft.Maui.LifecycleEvents;namespace PlatformLifecycleDemo
{public static class MauiProgram{public static MauiApp CreateMauiApp(){var builder = MauiApp.CreateBuilder();builder.UseMauiApp<App>().ConfigureLifecycleEvents(events =>{
#if WINDOWSevents.AddWindows(windows => windows.OnActivated((window, args) => LogEvent(nameof(WindowsLifecycle.OnActivated))).OnClosed((window, args) => LogEvent(nameof(WindowsLifecycle.OnClosed))).OnLaunched((window, args) => LogEvent(nameof(WindowsLifecycle.OnLaunched))).OnLaunching((window, args) => LogEvent(nameof(WindowsLifecycle.OnLaunching))).OnVisibilityChanged((window, args) => LogEvent(nameof(WindowsLifecycle.OnVisibilityChanged))).OnPlatformMessage((window, args) =>{if (args.MessageId == Convert.ToUInt32("031A", 16)){// System theme has changed}}));
#endifstatic bool LogEvent(string eventName, string type = null){System.Diagnostics.Debug.WriteLine($"Lifecycle event: {eventName}{(type == null ? string.Empty : $" ({type})")}");return true;}});return builder.Build();}}
}

检索 Window 对象

平台代码可以使用 GetWindow 扩展方法从平台生命周期事件中检索应用的 Window 对象：

C#复制

using Microsoft.Maui.LifecycleEvents;namespace PlatformLifecycleDemo
{public static class MauiProgram{public static MauiApp CreateMauiApp(){var builder = MauiApp.CreateBuilder();builder.UseMauiApp<App>().ConfigureLifecycleEvents(events =>{
#if WINDOWSevents.AddWindows(windows => windows.OnClosed((window, args) =>{IWindow appWindow = window.GetWindow();}));
#endif});return builder.Build();}}
}

自定义生命周期事件

虽然 .NET MAUI 定义为响应引发的平台生命周期事件而调用的委托，但它仅公开一组常见的平台生命周期事件。 但是，它还包括一种机制（通常适用于库作者），该机制支持应用在引发其他平台生命周期事件时收到通知。 完成此目的的过程如下所示：

• 为 .NET MAUI 未公开的平台生命周期事件注册事件处理程序。
• 在平台生命周期事件的事件处理程序中，检索 ILifecycleEventService 实例并调用其 InvokeEvents 方法，同时指定平台事件名称作为其参数。

然后，想要接收平台生命周期事件通知的应用应修改其 MauiProgram 类的 CreateMauiApp 方法，以调用 MauiAppBuilder 对象上的 ConfigureLifecycleEvents 方法。 然后，在 ILifecycleBuilder 对象上调用 AddEvent 方法，并指定平台事件名称和引发平台事件时将调用的 Action。

示例

当本机应用窗口首次呈现或更改其呈现大小时，将发生 WinUI 3 Window.SizeChanged 事件。 .NET MAUI 不会将此平台事件公开为生命周期事件。 但是，当使用以下方法引发此平台事件时，应用可以接收通知：

• 为 Window.SizeChanged 平台生命周期事件注册事件处理程序：

  C#复制

  using Microsoft.Maui.LifecycleEvents;
  ...public static MauiApp CreateMauiApp()
  {var builder = MauiApp.CreateBuilder();builder.UseMauiApp<App>().ConfigureLifecycleEvents(events =>{
  #if WINDOWSevents.AddWindows(windows => windows.OnWindowCreated(window =>{window.SizeChanged += OnSizeChanged;}));
  #endif});return builder.Build();
  }    
  

• 在平台生命周期事件的事件处理程序中，检索 ILifecycleEventService 实例并调用其 InvokeEvents 方法，同时将平台事件名称指定为其参数：

  C#复制

  using Microsoft.Maui.LifecycleEvents;
  ...#if WINDOWSstatic void OnSizeChanged(object sender, Microsoft.UI.Xaml.WindowSizeChangedEventArgs args){ILifecycleEventService service = MauiWinUIApplication.Current.Services.GetRequiredService<ILifecycleEventService>();service.InvokeEvents(nameof(Microsoft.UI.Xaml.Window.SizeChanged));}
  #endif
  

  Windows 上的 MauiWinUIApplication 类型可用于通过其 Current 属性访问本机应用实例。 Android 上的 MauiApplication 类型可用于访问本机应用实例。 同样，iOS 上的 MauiUIApplicationDelegate 类型可用于访问本机应用实例。

   警告

  使用 InvokeEvents 方法调用未注册的事件不会引发异常。

• 在 MauiProgram 类的 CreateMauiApp 方法中，调用 MauiAppBuilder 对象上的 ConfigureLifecycleEvents 方法。 然后，在 ILifecycleBuilder 对象上，调用 AddEvent 方法并指定平台事件名称和引发平台事件时调用的 Action：

  C#复制

  using Microsoft.Maui.LifecycleEvents;namespace PlatformLifecycleDemo
  {public static class MauiProgram{public static MauiApp CreateMauiApp(){var builder = MauiApp.CreateBuilder();builder.UseMauiApp<App>().ConfigureLifecycleEvents(events =>{
  #if WINDOWSevents.AddWindows(windows => windows.OnWindowCreated(window =>{window.SizeChanged += OnSizeChanged;}));events.AddEvent(nameof(Microsoft.UI.Xaml.Window.SizeChanged), () => LogEvent("Window SizeChanged"));
  #endifstatic bool LogEvent(string eventName, string type = null){System.Diagnostics.Debug.WriteLine($"Lifecycle event: {eventName}{(type == null ? string.Empty : $" ({type})")}");return true;}});return builder.Build();}}
  }
  

总体效果是，当用户更改 Windows 上的应用窗口大小时，将执行 AddEvent 方法中指定的操作。