Ciclo di vita dell'app

Le app .NET multipiattaforma dell'interfaccia utente dell'app (.NET MAUI) hanno in genere quattro stati di esecuzione: non in esecuzione, in esecuzione, disattivati e arrestati. .NET MAUI genera eventi del ciclo di vita multipiattaforma nella Window classe quando un'app passa dallo stato non in esecuzione allo stato in esecuzione, lo stato di esecuzione allo stato disattivato, lo stato disattivato allo stato arrestato, lo stato arrestato allo stato in esecuzione e lo stato arrestato fino allo stato non in esecuzione.

Il diagramma seguente mostra una panoramica del ciclo di vita dell'app .NET MAUI:

Nel diagramma l'ovale grigio indica che l'app non viene caricata in memoria. Gli ovali blu chiaro indicano che l'app è in memoria. Il testo sugli archi indica gli eventi generati da .NET MAUI, che forniscono notifiche all'app in esecuzione.

Lo stato di esecuzione di un'app dipende dalla cronologia dell'app. Ad esempio, quando un'app viene installata per la prima volta o quando viene avviato un dispositivo, l'app può essere considerata non in esecuzione. Quando l'app viene avviata, Created vengono generati gli eventi e Activated e l'app è in esecuzione. Se una finestra dell'app diversa ottiene lo stato attivo, viene generato l'evento Deactivated e l'app viene disattivata. Se l'utente passa a un'app diversa o torna alla schermata Iniziale del dispositivo, in modo che la finestra dell'app non sia più visibile, gli Deactivated eventi e Stopped vengono generati e l'app viene arrestata. Se l'utente torna all'app, viene generato l'evento Resuming e l'app è in esecuzione. In alternativa, un'app potrebbe essere terminata da un utente durante l'esecuzione. In questo caso l'app viene disattivata e quindi arrestata, viene generato l'evento Destroying e l'app non è in esecuzione. Analogamente, un dispositivo potrebbe terminare un'app mentre è arrestata, a causa di restrizioni delle risorse e l'evento Destroying viene generato e l'app non è in esecuzione.

.NET MAUI consente inoltre alle app di ricevere notifiche quando vengono generati eventi del ciclo di vita della piattaforma. Per altre informazioni, vedere Eventi del ciclo di vita della piattaforma.

Eventi del ciclo di vita multipiattaforma

La Window classe definisce gli eventi del ciclo di vita multipiattaforma seguenti:

Questi eventi multipiattaforma sono mappati a diversi eventi della piattaforma e la tabella seguente illustra questo mapping:

Inoltre, la Window classe definisce anche un Backgrounding evento generato in iOS e Mac Catalyst quando la finestra viene chiusa o entra in uno stato di sfondo. Un BackgroundingEventArgs oggetto accompagna questo evento e qualsiasi string stato deve essere salvato in modo permanente nella State proprietà dell'oggetto BackgroundingEventArgs , che il sistema operativo manterrà fino a quando non sarà il momento di riprendere la finestra. Quando la finestra viene ripresa, lo stato viene fornito dall'argomento IActivationState all'override CreateWindow .

Oltre a questi eventi, la Window classe include anche i metodi del ciclo di vita sostituibili seguenti:

• OnCreated, che viene richiamato quando viene generato l'evento Created .
• OnActivated, che viene richiamato quando viene generato l'evento Activated .
• OnDeactivated, che viene richiamato quando viene generato l'evento Deactivated .
• OnStopped, che viene richiamato quando viene generato l'evento Stopped .
• OnResumed, che viene richiamato quando viene generato l'evento Resumed .
• OnDestroying, che viene richiamato quando viene generato l'evento Destroying .
• OnBackgrounding, che viene richiamato quando viene generato l'evento Backgrounding .

Per sottoscrivere gli eventi del ciclo di vita, eseguire l'override Window del CreateWindow metodo nella App classe per creare un'istanza Window in cui è possibile sottoscrivere gli eventi:

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;
        }
    }
}

In alternativa, per utilizzare gli override del ciclo di vita, creare una classe che deriva dalla Window classe

namespace MyMauiApp
{
    public class MyWindow : Window
    {
        public MyWindow() : base()
        {
        }

        public MyWindow(Page page) : base(page)
        {
        }

        protected override void OnCreated()
        {
            // Register services
        }
    }
}

La Windowclasse derivata da può quindi essere utilizzata eseguendo l'override del CreateWindow metodo nella App classe per restituire un'istanza MyWindow .

Eventi del ciclo di vita della piattaforma

.NET MAUI definisce i delegati richiamati in risposta agli eventi del ciclo di vita della piattaforma generati. I gestori possono essere specificati per questi delegati, usando metodi denominati o funzioni anonime, che vengono eseguiti quando viene richiamato il delegato. Questo meccanismo consente alle app di ricevere notifiche quando vengono generati eventi comuni del ciclo di vita della piattaforma.

Android

La tabella seguente elenca i delegati MAUI .NET richiamati in risposta agli eventi del ciclo di vita di Android generati:

Per rispondere a un delegato del ciclo di vita Android richiamato, chiamare il ConfigureLifecycleEvents metodo sull'oggetto MauiAppBuilder nel CreateMauiapp metodo della MauiProgram classe. Quindi, nell'oggetto ILifecycleBuilder chiamare il AddAndroid metodo e specificare che Action registra i gestori per i delegati necessari:

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();
        }
    }
}

Per altre informazioni sul ciclo di vita dell'app Android, vedere Informazioni sul ciclo di vita delle attività in developer.android.com.

iOS e Mac Catalyst

La tabella seguente elenca i delegati MAUI .NET richiamati in risposta agli eventi del ciclo di vita di iOS e Mac Catalyst generati:

Per rispondere a un delegato del ciclo di vita di iOS e Mac Catalyst richiamato, chiamare il ConfigureLifecycleEvents metodo sull'oggetto MauiAppBuilder nel CreateMauiapp metodo della MauiProgram classe. Quindi, nell'oggetto ILifecycleBuilder chiamare il AddiOS metodo e specificare che Action registra i gestori per i delegati necessari:

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();
        }
    }
}

Per altre informazioni sul ciclo di vita dell'app iOS, vedere Gestione del ciclo di vita dell'app in developer.apple.com.

Finestre

La tabella seguente elenca i delegati MAUI .NET richiamati in risposta agli eventi del ciclo di vita di Windows generati:

.NET MAUI espone messaggi nativi specifici di Windows come evento del ciclo di vita con il OnPlatformMessage delegato . L'oggetto WindowsPlatformMessageEventArgs che accompagna questo delegato include una MessageId proprietà di tipo uint. Il valore di questa proprietà può essere esaminato per determinare quale messaggio è stato passato alla finestra dell'app. Per altre informazioni sui messaggi di Windows, vedere Messaggi di Windows (Introduzione a Win32 e C++). Per un elenco delle costanti dei messaggi della finestra, vedere Notifiche delle finestre.

Per rispondere a un delegato del ciclo di vita di Windows richiamato, chiamare il ConfigureLifecycleEvents metodo sull'oggetto MauiAppBuilder nel CreateMauiApp metodo della MauiProgram classe. Quindi, nell'oggetto ILifecycleBuilder chiamare il AddWindows metodo e specificare che Action registra i gestori per i delegati necessari:

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();
        }
    }
}

Recuperare l'oggetto Window

Il codice della piattaforma può recuperare l'oggetto dell'app dagli eventi del ciclo di vita della Window piattaforma, con il GetWindow metodo di estensione:

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();
        }
    }
}

Eventi del ciclo di vita personalizzati

Anche se .NET MAUI definisce delegati richiamati in risposta agli eventi del ciclo di vita della piattaforma generati, espone solo un set comune di eventi del ciclo di vita della piattaforma. Include tuttavia anche un meccanismo, in genere per gli autori di librerie, che consente alle app di ricevere notifiche quando vengono generati eventi aggiuntivi del ciclo di vita della piattaforma. A tale scopo, seguire questa procedura:

• Registrare un gestore eventi per un evento del ciclo di vita della piattaforma che non è esposto da .NET MAUI.
• Nel gestore eventi per l'evento del ciclo di vita della piattaforma recuperare l'istanza ILifecycleEventService e chiamarne InvokeEvents il metodo, specificando il nome dell'evento della piattaforma come argomento.

Quindi, le app che vogliono ricevere la notifica dell'evento del ciclo di vita della piattaforma devono modificare il CreateMauiApp metodo della relativa MauiProgram classe per chiamare il ConfigureLifecycleEvents metodo sull'oggetto MauiAppBuilder . Quindi, nell'oggetto ILifecycleBuilder chiamare il AddEvent metodo e specificare il nome dell'evento della piattaforma e l'oggetto Action che verrà richiamato quando viene generato l'evento della piattaforma.

Esempio

L'evento WinUI 3 Window.SizeChanged si verifica quando è stato eseguito il primo rendering della finestra dell'app nativa o ha modificato le dimensioni di rendering. .NET MAUI non espone questo evento della piattaforma come evento del ciclo di vita. Tuttavia, le app possono ricevere notifiche quando questo evento della piattaforma viene generato usando l'approccio seguente:

• Registrare un gestore eventi per l'evento del ciclo di vita della Window.SizeChanged piattaforma:

  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();
  }    
  

• Nel gestore eventi per l'evento del ciclo di vita della piattaforma recuperare l'istanza ILifecycleEventService e chiamarne InvokeEvents il metodo, specificando il nome dell'evento della piattaforma come argomento:

  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
  

  Il MauiWinUIApplication tipo in Windows può essere usato per accedere all'istanza dell'app nativa tramite la relativa Current proprietà. Il MauiApplication tipo in Android può essere usato per accedere all'istanza dell'app nativa. Analogamente, il MauiUIApplicationDelegate tipo in iOS può essere usato per accedere all'istanza dell'app nativa.

  Avviso

  La chiamata di un evento non registrato, con il InvokeEvents metodo , non genera un'eccezione.

• CreateMauiApp Nel metodo della MauiProgram classe chiamare il ConfigureLifecycleEvents metodo sull'oggetto MauiAppBuilder . Quindi, nell'oggetto ILifecycleBuilder chiamare il AddEvent metodo e specificare il nome dell'evento della piattaforma e che Action verrà richiamato quando viene generato l'evento della piattaforma:

  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();
          }
      }
  }
  

L'effetto complessivo è che quando un utente modifica le dimensioni della finestra dell'app in Windows, viene eseguita l'azione specificata nel AddEvent metodo .