애플리케이션 수명 주기 기능 마이그레이션

  • 아티클

이 항목에는 응용 프로그램 수명 주기 영역에 대한 마이그레이션 참고 자료가 포함되어 있습니다.

중요 API

API 및/또는 기능 차이점 요약

UWP(유니버설 Windows 플랫폼) 앱은 기본적으로 단일 인스턴스화됩니다. WinUI 3(Windows 앱 SDK) 앱은 기본적으로 다중 인스턴스화됩니다.

UWP 앱에는 앱이 어떻게 활성화되었는지 암시적으로 알려주는 OnFileActivated, OnSearchActivated, OnActivated, OnBackgroundActivated과 같은 App 메서드가 있습니다. Windows App SDK 앱에서는 App.Launched (또는 어떤 방식으로든)에서, (AppInstance.GetActivatedEventArgs)로 전화하여 활성화된 이벤트 아크를 검색하고, 앱이 어떻게 활성화되었는지 확인합니다.

또한 UWP에서 WinUI 3로 마이그레이션할 때 지원되는 항목의 표에서 Background tasks 행을 참조하십시오.

단일 인스턴스 앱

UWP(유니버설 Windows 플랫폼) 앱은 기본적으로 단일 인스턴스화됩니다(여러 인스턴스를 지원하도록 옵트인할 수 있음-인스턴스 UWP 앱 만들기 참조).

따라서 단일 인스턴스 UWP 앱이 동작하는 방식은 시작하는 두 번째(및 이후) 시간에 현재 인스턴스가 활성화되는 것입니다. 예를 들어 UWP 앱에서 파일 형식 연결 기능을 구현했다고 가정해 보겠습니다. 파일 탐색기에서 파일(앱이 파일 형식 연결을 등록한 형식)을 열면 앱이 이미 실행 중인 경우 이미 실행 중인 인스턴스가 활성화됩니다.

반면에 WinUI 3(Windows 앱 SDK) 앱은 기본적으로 다중 인스턴스화됩니다. 따라서 기본적으로 WinUI 3(Windows 앱 SDK) 앱을 시작하는 두 번째(및 후속) 시간에 앱의 새 인스턴스가 시작됩니다. 예를 들어 WinUI 3(Windows 앱 SDK) 앱이 파일 형식 연결을 구현하고 파일 탐색기에서 해당 앱이 이미 실행 중인 동안 올바른 형식의 파일을 열면 기본적으로 앱의 새 인스턴스가 시작됩니다.

UWP 앱처럼 WinUI 3(Windows 앱 SDK) 앱을 단일 인스턴스화하려는 경우 위에서 설명한 기본 동작을 재정의할 수 있습니다. AppInstance.FindOrRegisterForKey 및 AppInstance.IsCurrent를 사용하여 현재 인스턴스가 기본 인스턴스인지 확인합니다. 그렇지 않은 경우 AppInstance.RedirectActivationToAsync를 호출하여 활성화를 이미 실행 중인 기본 인스턴스로 리디렉션한 다음 주 창을 만들거나 활성화하지 않고 현재 인스턴스에서 종료합니다.

자세한 내용은 앱 수명 주기 API를 통해 앱 인스턴스화를 참조하세요.

Important

아래 표시된 코드는 x64 아키텍처를 대상으로 하는 경우 예상대로 작동합니다. 이는 C# 및 C++/WinRT 모두에 적용됩니다.

Main 또는 wWinMain의 단일 인스턴스화

앱 실행 시 활성화를 최대한 빨리 리디렉션해야 하는 필요성을 확인하는 것이 가장 좋습니다. 따라서 앱의 Main(또는 C++/WinRT의 경우 wWinMain) 함수에서 단일 인스턴스화 로직을 수행하는 것이 좋습니다. 이 섹션에서는 방법을 보여줍니다.

일반적으로 앱의 Main 함수는 빌드 시스템에서 자동 생성되어 숨겨진 파일에 저장됩니다. 따라서 첫 번째 단계는 해당 함수를 자동으로 생성하지 않도록 프로젝트를 구성하는 것입니다. 이를 수행하려면 속성 프로젝트에서 DISABLE_XAML_GENERATED_MAIN 기호를 정의합니다.

C#에 대한 지침

속성> ( 모든 구성 및 모든 플랫폼선택) >빌드>조건부 컴파일 기호로 이동하고 기호 DISAL_XAML_GENED_MAIN에 붙여넣습니다.

프로젝트에서 Main 함수를 자동 생성하지 못하도록 하기 때문에 프로젝트는 현재 빌드되지 않습니다. 따라서 두 번째 및 마지막 단계는 소스 코드 파일에서 해당 함수의 고유한 버전을 구현하는 것입니다.

Class 형식의 새 프로젝트 항목을 프로젝트에 추가하고 이름을 Program.cs 로 지정합니다 . 내부에서 Program.cs코드를 class Program {} 사용자 고유의 구현으로 바꿉다. 사용할 코드의 예제는 AppLifecycle 샘플을Program.cs 참조 하세요.

C++/WinRT에 대한 지침

속성> ( 모든 구성 및 모든 플랫폼선택) >구성 속성>C/C++>Preprocessor>PreprocessorDefinitions, 값을 편집하고 기호 DISE_XAML_GENED_MAIN를 추가합니다.

프로젝트가 wWinMain 함수를 자동으로 생성 하지 못하도록 했기 때문에 현재 프로젝트가 빌드되지 않습니다. 따라서 두 번째 및 마지막 단계는 소스 코드 파일에서 해당 함수의 고유한 버전을 구현하는 것입니다.

이 Microsoft.Windows.ImplementationLibrary NuGet 패키지에 대한 참조를 추가하고 프로젝트 pch.h 및 App.xaml.cpp 소스 코드 파일을 업데이트합니다. 사용할 코드의 예제는 AppLifecycle 샘플을 참조 하세요. 특정 프로젝트에 맞게 네임스페이스를 winrt::CppWinUiDesktopInstancing::implementation::App 변경해야 합니다.)

"오류 C2872: 'Microsoft': 모호한 기호"를 해결하려면 using namespace Microsoft::UI::Xaml; 에서 using namespace winrt::Microsoft::UI::Xaml;로 변경합니다 . 그리고 using 지시문에 유사한 추가 변경을 수행합니다.

Application.OnLaunched의 단일 인스턴스화

Main 또는 wWinMain 사용에 대한 대안은 앱 클래스의 Application.OnLaunched 메소드에서 단일 인스턴스화 로직을 수행하는 것입니다.

Important

Application.OnLaunched에서 이 작업을 수행하면 앱을 단순화할 수 있습니다. 그러나 앱이 수행하는 다른 작업에 따라 많은 것이 달라집니다. 리디렉션한 다음 현재 인스턴스를 종료하려는 경우, 버리기 작업(또는 명시적으로 실행 취소해야 하는 작업)을 수행하지 않는 것이 좋습니다. 이와 같은 경우 Application.OnLaunched가 너무 늦을 수 있으며 앱의 Main 또는 wWinMain 함수에서 작업을 수행하는 것이 좋습니다.

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

또는 AppInstance.GetInstances를 호출하여 실행 중인 AppInstance 개체의 컬렉션을 검색할 수 있습니다. 해당 컬렉션의 요소 수가 1보다 큰 경우 기본 인스턴스가 이미 실행 중이며 해당 인스턴스로 리디렉션해야 합니다.

파일 형식 연결

Windows 앱 SDK 프로젝트에서 파일 형식 연결에 대한 확장점을 지정하려면 Package.appxmanifest 파일에서 UWP 프로젝트와 동일한 설정을 지정합니다. 이러한 설정은 다음과 같습니다.

Package.appxmanifest을(를) 여십시오. 선언에서 파일 형식 연결을 선택하고 추가를 클릭합니다. 다음과 같이 속성을 설정합니다.

표시 이름: MyFile 이름: myfile 파일 형식: .myf

파일 형식 연결을 등록하려면 앱을 빌드하고 시작한 후 닫습니다.

차이점은 명령적 코드에서 발생합니다. UWP 앱에서는 파일 활성화를 처리하기 위해 App::OnFileActivated를 구현합니다. 그러나 Windows 앱 SDK 앱에서는 App::OnLaunched에 코드를 작성하여 활성화된 이벤트 인수(AppInstance.GetActivatedEventArgs) 및 활성화 종류(ExtendedActivationKind)가 파일 활성화인지 확인합니다.

참고 항목

App::OnLaunched에 전달된 Microsoft.UI.Xaml.LaunchActivatedEventArgs 개체를 사용하여 활성화 종류를 결정하면 무조건 "Launch"를 보고하기 때문에 이러한 방법을 사용하지 마세요.

앱에 탐색이 있는 경우 App::OnLaunched에 탐색 코드가 이미 있으며 해당 논리를 다시 사용할 수 있습니다. 자세한 내용은 페이지 탐색을 구현해야 하나요?를 참조하세요.

// 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 및 기타 활성화 처리 메서드

UWP 앱에서 앱을 활성화할 수 있는 다양한 수단을 재정의하기 위해 OnFileActivated, OnSearchActivated 또는 보다 일반적인 OnActivated와 같은 앱 클래스의 해당 메서드를 재정의할 수 있습니다.

Windows 앱 SDK 앱의 App.OnLaunched에서(또는 실제로는 언제든지) (AppInstance.GetActivatedEventArgs)를 호출하여 활성화된 이벤트 인수를 검색하고 앱이 활성화된 방법을 확인할 수 있습니다.

자세한 내용 및 코드 예제는 위의 파일 형식 연결 섹션을 참조하세요. ExtendedActivationKind 열거형으로 지정된 모든 활성화 종류에 동일한 기술을 적용할 수 있습니다.