应用生命周期

项目
10/31/2024

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

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

.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`	[.]
`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 实例：

namespace MyMauiApp
{
    public partial class App : Application
    {
        public App()
        {
            InitializeComponent();

            MainPage = new MainPage();
        }

        protected override Window CreateWindow(IActivationState? activationState)
        {
            Window window = new Window(new AppShell());

            window.Created += (s, e) =>
            {
                // Custom logic
            };

            return window;
        }
    }
}

namespace MyMauiApp
{
    public partial class App : Application
    {
        public App()
        {
            InitializeComponent();
        }

        protected override Window CreateWindow(IActivationState activationState)
        {
            Window window = base.CreateWindow(activationState);

            window.Created += (s, e) =>
            {
                // Custom logic
            };

            return window;
        }
    }
}

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

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

重要说明

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

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

using Microsoft.Maui.LifecycleEvents;

namespace PlatformLifecycleDemo
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureLifecycleEvents(events =>
                {
#if ANDROID
                    events.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))));
#endif
                    static 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`	.- .	当应用收到与用户活动关联的数据（例如使用 Handoff 从其他设备传输活动）时调用。
`DidEnterBackground`	`UIKit.UIApplication`	当应用进入后台时调用。
`FinishedLaunching`	%>	在应用启动时调用。
`OnActivated`	`UIKit.UIApplication`	在应用启动时调用，每次应用返回到前台时调用。
`OnResignActivation`	`UIKit.UIApplication`	在应用即将进入后台、暂停运行或用户遇到中断情形（如接到电话或短信）时调用。
`OpenUrl`	%>	当应用应打开指定的 URL 时调用。
`PerformActionForShortcutItem`	.- .	启动主屏幕快速操作时调用。
`PerformFetch`	%>	需要告知应用可开始提取操作以下载可用数据时调用。
`SceneContinueUserActivity`	%>	需要处理指定的与移交相关的活动时调用。
`SceneDidDisconnect`	`UIKit.UIScene`	从应用中删除场景时调用。
`SceneDidEnterBackground`	`UIKit.UIScene`	当场景在后台运行且未出现在屏幕上时调用。
`SceneDidFailToContinueUserActivity`	.- .	需要通知用户无法完成活动时调用。
`SceneDidUpdateUserActivity`	%>	更新指定活动时调用。
`SceneOnActivated`	`UIKit.UIScene`	当场景处于活动状态并能够响应用户事件时调用。
`SceneOnResignActivation`	`UIKit.UIScene`	当场景即将退出活动状态并停止响应用户事件时调用。
`SceneOpenUrl`	%>	当场景要求打开一个或多个 URL 时调用。
`SceneRestoreInteractionState`	%>	需要还原活动状态时调用。
`SceneWillConnect`	.- .	将场景添加到应用时调用。
`SceneWillContinueUserActivity`	%>	需要准备接收与移交相关的数据时调用。
`SceneWillEnterForeground`	`UIKit.UIScene`	当场景即将在前台运行并且对用户可见时调用。
`WillEnterForeground`	`UIKit.UIApplication`	当应用将从后台状态返回时调用。
`WillFinishLaunching`	%>	在应用已开始启动但尚未发生状态还原时调用。
`WillTerminate`	`UIKit.UIApplication`	在应用因内存限制而终止，或者由用户直接终止的情况下调用。
`WindowSceneDidUpdateCoordinateSpace`		场景的大小、方向或特征发生更改时调用。

重要说明

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

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

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 || MACCATALYST
                    events.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))));
#endif
                    static 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`	%>	如果应用未恢复，在引发平台 Activated 事件时调用。
`OnClosed`	%>	在引发平台 Closed 事件时调用。
`OnLaunched`	%>	创建并激活本机窗口后，由 .NET MAUI 的 Application.OnLaunched 重写调用。
`OnLaunching`	%>	在创建和激活本机窗口前，由 .NET MAUI 的 Application.OnLaunched 重写调用。
`OnPlatformMessage`	%>	当 .NET MAUI 接收到特定的本机 Windows 消息时调用。
`OnPlatformWindowSubclassed`	%>	由 .NET MAUI 在 Win32 窗口被子类化时调用。
`OnResumed`	`Microsoft.UI.Xaml.Window`	如果应用正在恢复，在引发平台 `Activated` 事件时调用。
`OnVisibilityChanged`	%>	引发平台 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：

using Microsoft.Maui.LifecycleEvents;

namespace PlatformLifecycleDemo
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureLifecycleEvents(events =>
                {
#if WINDOWS
                    events.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
                               }
                           }));
#endif
                    static 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 对象：

using Microsoft.Maui.LifecycleEvents;

namespace PlatformLifecycleDemo
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureLifecycleEvents(events =>
                {
#if WINDOWS
                    events.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 平台生命周期事件注册事件处理程序：

using Microsoft.Maui.LifecycleEvents;
...

public static MauiApp CreateMauiApp()
{
      var builder = MauiApp.CreateBuilder();
      builder
            .UseMauiApp<App>()
            .ConfigureLifecycleEvents(events =>
            {
#if WINDOWS
                  events.AddWindows(windows => windows
                         .OnWindowCreated(window =>
                         {
                                window.SizeChanged += OnSizeChanged;
                         }));
#endif
            });

      return builder.Build();
}

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

#if WINDOWS
        static 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：

using Microsoft.Maui.LifecycleEvents;

namespace PlatformLifecycleDemo
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureLifecycleEvents(events =>
                {
#if WINDOWS
                    events.AddWindows(windows => windows
                           .OnWindowCreated(window =>
                           {
                                  window.SizeChanged += OnSizeChanged;
                           }));

                    events.AddEvent(nameof(Microsoft.UI.Xaml.Window.SizeChanged), () => LogEvent("Window SizeChanged"));
#endif
                    static 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 方法中指定的操作。

注意

AddEvent 方法还具有一个允许指定委托的重载。

通过

应用生命周期

跨平台生命周期事件

平台生命周期事件

Android

iOS 和 Mac Catalyst

Windows

检索 Window 对象

自定义生命周期事件

示例

其他资源