Migrering av programlivscykelfunktioner

Det här avsnittet innehåller migreringsvägledning i programmets livscykelområde.

Viktiga API:er

• AppInstance-klass
• Application.OnLaunched-metod
• AppInstance.GetActivatedEventArgs-metod
• ExtendedActivationKind uppräkning

Sammanfattning av skillnader i API och/eller funktioner

UWP-appar (Universal Windows Platform) är eninstans som standard. Windows App SDK-appar (WinUI 3) har flera instanser som standard.

En UWP-app har App metoder som OnFileActivated, OnSearchActivated, OnActivatedoch OnBackgroundActivated som implicit anger hur appen aktiverades. I en Windows App SDK-app i App.OnLaunched (eller i någon metod) anropar du (AppInstance.GetActivatedEventArgs) för att hämta den aktiverade händelsen args och kontrollera dem för att fastställa hur appen aktiverades.

Se även Bakgrundsaktiviteter raden i tabellen i avsnittet Vad som stöds när du migrerar från UWP till WinUI 3.

Eninstans-appar

UWP-appar (Universal Windows Platform) är eninstans som standard (du kan välja att stödja flera instanser – se Skapa en UWP-app med flera instanser).

Hur en UWP-app i en enda instans fungerar är att nästa gång (eller efterföljande gånger) du startar, aktiveras den aktuella instansen. Anta till exempel att du har implementerat filtypsassociationen i UWP-appen. Om du öppnar en fil från Utforskaren (av den typ som appen har registrerat en filtypsassociation för)– och appen redan körs – aktiveras den redan aktiva instansen.

Windows App SDK-appar (WinUI 3) är som standard instanser som kan köras flera gånger. Så, som standard, den andra (och efterföljande) gången du startar en Windows App SDK-app (WinUI 3) startas en ny instans av appen. Om till exempel en Windows App SDK-app (WinUI 3) implementerar filtypsassociation, och från Utforskaren öppnar du en fil (av rätt typ) medan appen redan körs, startas som standard en ny instans av appen.

Om du vill att din Windows App SDK-app (WinUI 3) ska vara eninstans som din UWP-app är kan du åsidosätta standardbeteendet som beskrivs ovan. Du använder AppInstance.FindOrRegisterForKey och AppInstance.IsCurrent för att avgöra om den aktuella instansen är huvudinstansen. Om det inte är det anropar du AppInstance.RedirectActivationToAsync för att omdirigera aktiveringen till den redan igång huvudinstansen och sedan avsluta från den aktuella instansen (utan att skapa eller aktivera huvudfönstret).

Mer information finns i App-instansiering med API för applivscykel.

Enkelt instansering i Main eller wWinMain

Det är bäst att kontrollera behovet av att omdirigera aktivering så tidigt som möjligt under appens körningsprocess. Därför rekommenderar vi att du utför din logik med enkel instancing i appens funktion Main (eller wWinMain för C++/WinRT). Det här avsnittet visar hur.

Normalt genereras appens Main-funktion automatiskt av byggsystemet och placeras i en dold fil. Det första steget är att konfigurera projektet att inte generera funktionen automatiskt. För att göra det definierar du symbolen DISABLE_XAML_GENERATED_MAIN i project Properties.

Instruktioner för C#

Gå till Egenskaper> (välj Alla konfigurationer och Alla plattformar) >Skapa>villkorsstyrda kompileringssymboleroch klistra in symbolen DISABLE_XAML_GENERATED_MAIN.

Eftersom vi just har förhindrat projektet från att automatiskt generera en Main-funktion kommer projektet inte att kompilera för tillfället. Så det andra och sista steget är att implementera vår egen version av den funktionen i en källkodsfil.

Lägg till ett nytt projektobjekt av typen Class i projektet och ge det namnet Program.cs. I Program.csersätter du koden class Program {} med din egen implementering. Ett exempel på koden som ska användas finns i Program.cs i AppLifecycle-exempel.

Instruktioner för C++/WinRT

Gå till Egenskaper> (välj Alla konfigurationer och Alla plattformar) >Konfigurationsegenskaper>C/C++>Preprocessor>Förprocessordefinitioner, Redigera värdet och lägg till symbolen DISABLE_XAML_GENERATED_MAIN.

Eftersom vi just har förhindrat projektet från att automatiskt generera en wWinMain--funktion, kommer projektet inte att byggas just nu. Så det andra och sista steget är att implementera vår egen version av den funktionen i en källkodsfil.

Lägg till en referens till Microsoft.Windows.ImplementationLibrary NuGet-paketet och uppdatera projektets pch.h- och App.xaml.cpp källkodsfiler. Ett exempel på koden som ska användas finns i AppLifecycle-exempel. Se till att ändra namnområdet i winrt::CppWinUiDesktopInstancing::implementation::App så att det passar just ditt projekt).

Lös felet C2872: Microsoft: tvetydig symbol genom att ändra using namespace Microsoft::UI::Xaml; till using namespace winrt::Microsoft::UI::Xaml;. Och gör ytterligare liknande ändringar i using-direktiven.

Enkeltsession i Application.OnLaunched

Ett alternativ till att använda Main eller wWinMain är att utföra din logik för enkel instansering i metoden Application.OnLaunched i klassen App.

// App.xaml.cs in a Windows App SDK (WinUI 3) app
...
protected override async void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    // If this is the first instance launched, then register it as the "main" instance.
    // If this isn't the first instance launched, then "main" will already be registered,
    // so retrieve it.
    var mainInstance = Microsoft.Windows.AppLifecycle.AppInstance.FindOrRegisterForKey("main");

    // If the instance that's executing the OnLaunched handler right now
    // isn't the "main" instance.
    if (!mainInstance.IsCurrent)
    {
        // Redirect the activation (and args) to the "main" instance, and exit.
        var activatedEventArgs =
            Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().GetActivatedEventArgs();
        await mainInstance.RedirectActivationToAsync(activatedEventArgs);
        System.Diagnostics.Process.GetCurrentProcess().Kill();
        return;
    }

    m_window = new MainWindow();
    m_window.Activate();
}

// pch.h in a Windows App SDK (WinUI 3) app
...
#include <winrt/Microsoft.Windows.AppLifecycle.h>
...

// App.xaml.h
...
struct App : AppT<App>
{
    ...
    winrt::fire_and_forget OnLaunched(Microsoft::UI::Xaml::LaunchActivatedEventArgs const&);
    ...
}

// App.xaml.cpp
...
using namespace winrt;
using namespace Microsoft::Windows::AppLifecycle;
...
winrt::fire_and_forget App::OnLaunched(LaunchActivatedEventArgs const&)
{
    // If this is the first instance launched, then register it as the "main" instance.
    // If this isn't the first instance launched, then "main" will already be registered,
    // so retrieve it.
    auto mainInstance{ AppInstance::FindOrRegisterForKey(L"main") };

    // If the instance that's executing the OnLaunched handler right now
    // isn't the "main" instance.
    if (!mainInstance.IsCurrent())
    {
        // Redirect the activation (and args) to the "main" instance, and exit.
        auto activatedEventArgs{ AppInstance::GetCurrent().GetActivatedEventArgs() };
        co_await mainInstance.RedirectActivationToAsync(activatedEventArgs);
        ::ExitProcess(0);
        co_return;
    }

    window = make<MainWindow>();
    window.Activate();
}

Du kan också anropa AppInstance.GetInstances för att hämta en samling med körande AppInstance-objekt. Om antalet element i samlingen är större än 1 körs din huvudinstans redan och du bör omdirigera till den.

Filtypsassociation

Om du vill ange tilläggspunkten för en filtypsassociation i ett Windows App SDK-projekt gör du samma inställningar i din Package.appxmanifest fil som för ett UWP-projekt. Här är de inställningarna.

Öppna Package.appxmanifest. I -deklarationerväljer du Filtypsassociationeroch klickar på Lägg till. Ange följande egenskaper.

Visningsnamn: MyFile Name: myfile File type: .myf

Om du vill registrera filtypsassociationen skapar du appen, startar den och stänger den.

Skillnaden kommer i imperativ kod. I en UWP-app implementerar du App::OnFileActivated för att hantera filaktivering. Men i en Windows App SDK-app skriver du kod i App::OnLaunched för att kontrollera den utökade aktiveringstypen (ExtendedActivationKind) för den aktiverade händelsen args (AppInstance.GetActivatedEventArgs) och se om aktiveringen är en filaktivering.

Om din app har navigering har du redan navigeringskod i App::OnLaunched, och du kanske vill återanvända den logiken. Mer information finns i Behöver jag implementera sidnavigering?.

// App.xaml.cs in a Windows App SDK app
...
using Microsoft.Windows.AppLifecycle;
...
protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    var activatedEventArgs = Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().GetActivatedEventArgs();
    if (activatedEventArgs.Kind == Microsoft.Windows.AppLifecycle.ExtendedActivationKind.File)
    {
        ...
    }
    ...
}

// pch.h in a Windows App SDK app
...
#include <winrt/Microsoft.Windows.AppLifecycle.h>

// App.xaml.cpp
...
using namespace Microsoft::Windows::AppLifecycle;
...
void App::OnLaunched(LaunchActivatedEventArgs const&)
{
    auto activatedEventArgs{ AppInstance::GetCurrent().GetActivatedEventArgs() };
    if (activatedEventArgs.Kind() == ExtendedActivationKind::File)
    {
        ...
    }
    ...
}

OnActivated, OnBackgroundActivated och andra metoder för aktiveringshantering

Om du vill åsidosätta de olika sätt som appen kan aktiveras på i en UWP-app kan du åsidosätta motsvarande metoder i klassen App, till exempel OnFileActivated, OnSearchActivatedeller den mer allmänna OnActivated.

I en Windows App SDK-app i App.OnLaunched (eller faktiskt när som helst) kan du anropa (AppInstance.GetActivatedEventArgs) för att hämta den aktiverade händelsen args och kontrollera dem för att avgöra hur appen aktiverades.

Mer information och ett kodexempel finns i avsnittet filtypsassociation ovan. Du kan använda samma teknik för varje typ av aktivering som specificeras av ExtendedActivationKind-uppsättningen.

Relaterade ämnen

• Windows App SDK och Windows-versioner som stöds
• App-instancing med appens livscykel-API
• Behöver jag implementera sidnavigering?