기간 이동 기능 마이그레이션

  • 아티클

이 항목에는 UWP의 ApplicationView/CoreWindow 또는 AppWindow에서 Window 앱 SDK Microsoft.UI.Windowing.AppWindow로의 마이그레이션을 포함하여 창 관리에 관련된 지침이 있습니다.

중요 API

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

Windows 앱 SDK는 Win32 HWND 모델을 기반으로 하는 Microsoft.UI.Windowing.AppWindow 클래스를 제공합니다. 해당 AppWindow 클래스는 UWP의 ApplicationView/CoreWindow 및 AppWindow의 Windows 앱 SDK 버전입니다.

Windows 앱 SDK 창 API를 활용한다는 것은 Win32 모델을 사용하도록 UWP 코드를 마이그레이션한다는 것을 의미합니다. Windows 앱 SDK AppWindow에 대한 자세한 내용은 앱 Windows 관리를 참조하세요.

팁

이 앱 관리 창 항목에는 WinUI 3 창에서 AppWindow를 검색하는 방법을 보여 주는 코드 예제가 포함되어 있습니다. WinUI 3 앱에서 이 항목의 나머지 부분에 멘션 AppWindow API를 호출할 수 있도록 해당 코드 패턴을 사용합니다.

UWP와 Windows 앱 SDK의 창 유형

UWP 앱에서 ApplicationView/CoreWindow 또는 AppWindow를 사용하여 창 콘텐츠를 호스팅할 수 있습니다. 해당 코드를 Windows 앱 SDK로 마이그레이션하는 작업은 UWP 앱에서 사용하는 두 개의 창 모델에 따라 다릅니다. UWP의 Windows.UI.WindowManagement.AppWindow에 익숙하다면 Microsoft.UI.Windowing.AppWindow와 유사한 점을 볼 수 있습니다.

UWP 창 유형

Windows 앱 SDK 창 유형

UWP와 Win32 간의 창 모델의 차이점은 UWP API 표면과 Windows 앱 SDK API 표면 간에 직접적인 1:1 매핑이 없다는 것을 의미합니다. UWP에서 이전하는 클래스 및 멤버 이름의 경우에도(이 항목의 매핑 테이블에 반영됨) 동작이 다를 수도 있습니다.

시작 화면

UWP 앱과 달리 Win32 앱은 기본적으로 시작 시 시작 화면을 표시하지 않습니다. 시작 환경을 위해 이 기능을 사용하는 UWP 앱은 첫 번째 앱 창에 대한 사용자 지정 전환을 구현하도록 선택할 수 있습니다.

창 만들기, 표시, 닫기 및 제거

Microsoft.UI.Windowing.AppWindow의 수명은 HWND의 수명과 동일합니다. 즉, AppWindow 개체는 창이 만들어진 직후에 사용할 수 있으며 창이 닫힐 때 제거됩니다.

만들기 및 표시

AppWindow.Create는 기본 구성으로 앱 창을 만듭니다. 창을 만들고 표시하는 것은 UI 프레임워크로 작업하지 않는 시나리오에만 필요합니다. UWP 앱을 Win32 호환 UI 프레임워크로 마이그레이션하는 경우 창 interop 메서드를 사용하여 이미 만들어진 창에서 AppWindow 개체에 계속 연결할 수 있습니다.

UWP ApplicationView/CoreWindow UWP AppWindow Windows 앱 SDK
CoreApplication.CreateNewView
또는
CoreWindow.GetForCurrentThread		 AppWindow.TryCreateAsync AppWindow.Create
CoreWindow.Activate AppWindow.TryShowAsync AppWindow.Show

닫기

UWP에서 ApplicationView.TryConsolidateAsync는 사용자가 닫기 동작을 시작하는 것과 동일한 프로그래밍 방식입니다. 이 통합 개념(UWP의 ApplicationView/CoreWindow 창 모델에서)은 Win32에 존재하지 않습니다. Win32에서는 창이 별도의 스레드에 존재할 필요가 없습니다. UWP의 ApplicationView/CoreWindow 창 모델을 복제하려면 개발자가 새 스레드를 만들고 거기에 새 창을 만들어야 합니다. Win32 모델에서 기본 시스템 동작은 닫기>숨기기>제거입니다.

UWP ApplicationView/CoreWindow UWP AppWindow Windows 앱 SDK
ApplicationView.TryConsolidateAsync AppWindow.CloseAsync AppWindow.Destroy

기본 창 사용자 지정

UWP에서 Windows 앱 SDK로 마이그레이션할 때 기본 AppWindow에서 동일한 환경을 기대할 수 있습니다. 그러나 필요한 경우 사용자 지정된 창 환경을 위해 기본 Microsoft.UI.Windowing.AppWindow를 변경할 수 있습니다. 창을 사용자 지정하는 방법에 대한 자세한 내용은 Microsoft.UI.Windowing.AppWindow를 참조하세요.

창 크기 조정

UWP ApplicationView/CoreWindow UWP AppWindow Windows 앱 SDK
ApplicationView.TryResizeView AppWindow.RequestSize AppWindow.Resize
CoreWindow.Bounds(C#에서 일반적으로 CoreWindow.GetForCurrentThread.Bounds로 표시됨) AppWindowPlacement.Size AppWindow.Size

창 위치 지정

UWP ApplicationView/CoreWindow UWP AppWindow Windows 앱 SDK
가능하지 않음 AppWindow.GetPlacement AppWindow.Position
가능하지 않음 Appwindow.RequestMoveXxx AppWindow.Move

Window title

UWP ApplicationView/CoreWindow UWP AppWindow Windows 앱 SDK
ApplicationView.Title AppWindow.Title AppWindow.Title

컴팩트 오버레이 및 전체 화면

컴팩트 오버레이 또는 전체 화면으로 들어가는 앱은 Windows 앱 SDK AppWindowPresenter를 활용해야 합니다. UWP AppWindow에 익숙하다면 Presenter 개념에도 이미 익숙할 것입니다.

UWP 앱 창 Presenter에서 Windows 앱 SDK 앱 창 Presenter로 기능 및 동작의 1:1 매핑은 없습니다. UWP ApplicationView/CoreWindow 앱이 있는 경우 앱에서 컴팩트 오버레이(picture-in-picture) 또는 전체 화면 창 환경을 계속 사용할 수 있지만 Presenter 개념이 생소할 수 있습니다. 앱 창 Presenter에 대한 자세한 내용은 Presenter를 참조하세요. 기본적으로 중첩된 Presenter는 만들 때 AppWindow에 적용됩니다. CompactOverlay 및 FullScreen은 기본값 외에 사용할 수 있는 유일한 Presenter입니다.

컴팩트 오버레이

UWP의 ApplicationViewMode 또는 AppWindowPresentionKind를 사용하여 축소된 오버레이 창을 표시한 경우 축소된 오버레이 AppWindowPresenterKind를 사용해야 합니다. Microsoft.UI.Windowing.CompactOverlayPresenter는 16:9 가로 세로 비율에서 3개의 고정 창 크기만 지원하며 사용자가 크기를 조정할 수 없습니다. ApplicationViewMode.TryEnterViewModeAsync or AppWindowPresenterKind.RequestPresentation 대신 AppWindow.SetPresenter를 사용하여 AppWindow의 프레젠테이션을 변경해야 합니다.

UWP ApplicationView/CoreWindow UWP AppWindow Windows 앱 SDK
ApplicationViewMode.CompactOverlay AppWindowPresentationKind.CompactOverlay AppWindowPresenterKind.CompactOverlay
ApplicationView.TryEnterViewModeAsync(ApplicationViewMode.CompactOverlay 포함) AppWindowPresenter.RequestPresentation(AppWindowPresenterKind.CompactOverlay 포함) AppWindow.SetPresenter(AppWindowPresenterKind.CompactOverlay 포함)

전체 화면

UWP의 ApplicationViewWindowingMode 또는 AppWindowPresentionKind 클래스를 사용하여 전체 화면 창을 표시한 경우 전체 화면 AppWindowPresenterKind를 사용해야 합니다. Windows 앱 SDK는 가장 제한적인 전체 화면 환경만 지원합니다(즉, FullScreen이 IsExclusive인 경우). ApplicationView/CoreWindow의 경우 ApplicationView.ExitFullScreenMode를 사용하여 전체 화면에서 앱을 제외할 수 있습니다. Presenter를 사용할 때 AppWindow.SetPresenter를 통해 Presenter를 다시 중첩/기본값으로 설정하여 전체 화면에서 앱을 제외할 수 있습니다.

UWP ApplicationView/CoreWindow UWP AppWindow Windows 앱 SDK
ApplicationViewWindowingMode.FullScreen AppWindowPresentationKind.FullScreen AppWindowPresenterKind.FullScreen
ApplicationView.TryEnterFullScreenMode AppWindowPresenter.RequestPresentation(AppWindowPresenterKind.FullScreen 포함) AppWindow.SetPresenter(AppWindowPresenterKind.FullScreen 포함)

앱 창 Presenter를 사용하는 방법에 대한 자세한 내용은 창 갤러리 샘플을 참조하세요. 다양한 앱 창 Presenter 상태를 전환하는 방법을 보여 줍니다.

사용자 지정 제목 표시줄

참고 항목

제목 표시줄 사용자 지정 API는 현재 Windows 11에서만 작동합니다. 이러한 API를 호출하기 전에 코드에서 AppWindowTitleBar.IsCustomizationSupported를 확인하는 것이 좋습니다.

앱이 기본 제목 표시줄을 사용하는 경우 Win32로 마이그레이션할 때 추가 제목 표시줄 작업이 필요하지 않습니다. 반면에 UWP 앱에 사용자 지정 제목 표시줄이 있는 경우 Windows 앱 SDK 앱에서 다음 시나리오를 다시 만들 수 있습니다.

  1. 시스템에서 그린 제목 표시줄 사용자 지정
  2. 앱에서 그린 사용자 지정 제목 표시줄

UWP ApplicationViewTitleBar, CoreApplicationViewTitleBar 및 AppWindowTitleBar 클래스를 사용하는 코드는 Windows 앱 SDK Microsoft.UI.Windowing.AppWindowTitleBar 클래스를 사용하도록 마이그레이션됩니다.

시스템에서 그린 제목 표시줄 사용자 지정

다음은 색상 사용자 지정 API 표입니다.

참고 항목

AppWindowTitleBar.ExtendsContentIntoTitleBar가 true인 경우 투명도는 다음 속성에 대해서만 지원됩니다. AppWindowTitleBar.ButtonBackgroundColor, AppWindowTitleBar.ButtonInactiveBackgroundColor, AppWindowTitleBar.ButtonPressedBackgroundColor, AppWindowTitleBar.ButtonHoverBackgroundColor 및 AppWindowTitleBar.BackgroundColor(암시적으로 설정됨).

UWP ApplicationView/CoreWindow UWP AppWindow Windows 앱 SDK
ApplicationViewTitleBar의 속성 AppWindowTitleBar의 속성 AppWindowTitleBar의 속성
BackgroundColor BackgroundColor BackgroundColor
ButtonBackgroundColor ButtonBackgroundColor ButtonBackgroundColor
ButtonForegroundColor ButtonForegroundColor ButtonForegroundColor
ButtonHoverBackgroundColor ButtonHoverBackgroundColor ButtonHoverBackgroundColor
ButtonHoverForegroundColor ButtonHoverForegroundColor ButtonHoverForegroundColor
ButtonInactiveBackgroundColor ButtonInactiveBackgroundColor ButtonInactiveBackgroundColor
ButtonInactiveForegroundColor ButtonInactiveForegroundColor ButtonInactiveForegroundColor
ButtonPressedBackgroundColor ButtonPressedBackgroundColor ButtonPressedBackgroundColor
ButtonPressedForegroundColor ButtonPressedForegroundColor ButtonPressedForegroundColor
전경색 전경색 전경색
InactiveBackgroundColor InactiveBackgroundColor InactiveBackgroundColor
InactiveForegroundColor InactiveForegroundColor InactiveForegroundColor

이러한 Windows 앱 SDK API는 AppWindow.Title API 외에 시스템에서 그린 제목 표시줄을 추가로 사용자 지정하기 위한 것입니다.

  • AppWindow.SetIcon. 리소스 또는 파일에 대한 hIcon 핸들 또는 문자열 경로를 사용하여 제목 표시줄 및 작업 표시줄 아이콘 그림을 설정합니다.
  • AppWindowTitleBar.IconShowOptions. 창 아이콘이 제목 표시줄에 표시되는 방식을 지정하는 값을 가져오거나 설정합니다. 현재HideIconAndSystemMenu 및 ShowIconAndSystemMenu 두 가지 값을 지원합니다.
  • AppWindowTitleBar.ResetToDefault. 현재 제목 표시줄을 창의 기본 설정으로 다시 설정합니다.

앱에서 그린 사용자 지정 제목 표시줄(완전한 사용자 지정)

AppWindowTitleBar를 사용하도록 마이그레이션하는 경우 다음 사용자 지정 제목 표시줄 API를 호출하기 전에 코드에서 AppWindowTitleBar.IsCustomizationSupported를 확인하는 것이 좋습니다.

UWP ApplicationView/CoreWindow Windows App SDK AppWindow
CoreApplicationViewTitleBar.ExtendViewIntoTitleBar AppWindowTitleBar.ExtendsContentIntoTitleBar
플랫폼은 계속해서 최소화/최대화/닫기 단추를 표시하고 폐색 정보를 보고합니다.
CoreApplicationViewTitleBar.SystemOverlayLeftInset AppWindowTitleBar.LeftInset
CoreApplicationViewTitleBar.SystemOverlayRightInset AppWindowTitleBar.RightInset
CoreApplicationViewTitleBar.Height AppWindowTitleBar.Height
AppWindowTitleBarOcclusion
AppWindowTitleBar.GetTitleBarOcclusions		 ExtendsContentIntoTitleBar가 true인 경우 앱 콘텐츠를 가리는 앱 창의 시스템 예약 영역을 나타냅니다. Windows 앱 SDK AppWindow 왼쪽 및 오른쪽 삽입 정보는 제목 표시줄 높이와 함께 동일한 정보를 제공합니다.
AppWindowTitleBar.LeftInset, AppWindowTitleBar.RightInset, AppWindowTitleBar.Height

이러한 Windows 앱 SDK API는 전체 제목 표시줄 사용자 지정을 위한 것입니다.

이러한 UWP AppWindow API에는 Windows App SDK API에 대한 직접적인 1:1 매핑이 없습니다.

AppWindowTitleBar를 사용하는 방법에 대한 자세한 내용은 창 갤러리 샘플을 참조하세요. 사용자 지정 색 제목 표시줄을 만드는 방법과 사용자 지정 제목 표시줄을 그리는 방법을 보여 줍니다.

이벤트 처리

UWP 앱이 AppWindow.Changed 이벤트를 사용하는 경우 해당 코드를 Microsoft.UI.Windowing.AppWindow.Changed 이벤트로 마이그레이션할 수 있습니다.

사이즈 변경 이벤트

크기 변경 이벤트 처리 코드를 마이그레이션할 때 Windows 앱 SDK AppWindowChangedEventArgs.DidSizeChange 속성을 사용하도록 전환해야 합니다. 앱 창의 크기가 변경된 경우 값은 true이고, 그렇지 않으면 false입니다.

UWP ApplicationView/CoreWindow UWP AppWindow Windows 앱 SDK
CoreWindow.SizeChanged AppWindowChangedEventArgs.DidSizeChange AppWindowChangedEventArgs.DidSizeChange

MainPage와 MainWindow

Visual Studio에서 새 UWP 프로젝트를 만들 때 프로젝트 템플릿은 MainPage 클래스를 제공합니다. 앱의 경우 해당 클래스의 이름을 바꾸거나 더 많은 페이지와 사용자 컨트롤을 추가했을 수 있습니다. 프로젝트 템플릿은 또한 App 클래스의 메서드에서 탐색 코드를 제공합니다.

Visual Studio에서 새 Windows 앱 SDK 프로젝트를 만들 때 프로젝트 템플릿은 MainWindow 클래스(유형 Microsoft.UI.Xaml.Window)를 제공하지만 페이지는 없습니다. 그리고 프로젝트 템플릿은 탐색 코드를 제공하지 않습니다.

그러나 Windows 앱 SDK 프로젝트에 페이지와 사용자 컨트롤을 추가할 수 있는 옵션이 있습니다. 예를 들어 프로젝트에 새 페이지 항목(WinUI 빈 페이지(WinUI>3))을 추가하고 이름을 지정 MainPage.xaml하거나 다른 이름을 지정할 수 있습니다. 그러면 프로젝트에 Microsoft.UI.Xaml.Controls.Page 유형의 새 클래스가 추가됩니다. 그런 다음 프로젝트에 탐색 코드를 추가하는 방법에 대한 정보는 페이지 탐색을 구현해야 하나요?를 참조하세요.

충분히 간단한 Windows 앱 SDK 앱의 경우 페이지나 사용자 컨트롤을 만들 필요가 없으며 XAML 태그와 코드 숨김을 MainWindow에 복사할 수 있습니다. 그러나 해당 워크플로의 예외에 대한 정보는 Visual State Manager 및 Page.Resources를 참조하세요.

CoreWindow.Dispatcher를 Window.DispatcherQueue로 변경

UWP의 Windows.UI.Core.CoreWindow 클래스에 대한 일부 사용 사례는 Windows 앱 SDK의 Microsoft.UI.Xaml.Window로 마이그레이션됩니다.

예를 들어 UWP 앱에서 Windows.UI.Core.CoreWindow.Dispatcher 속성을 사용하는 경우 솔루션은 Microsoft.UI.Xaml.Window.Dispatcher 속성(항상 null을 반환함)으로 마이그레이션하지 않습니다. 대신 Microsoft.UI.Dispatching.DispatcherQueue를 반환하는 Microsoft.UI.Xaml.Window.DispatcherQueue 속성으로 마이그레이션합니다.

자세한 내용과 코드 예는 Windows.UI.Core.CoreDispatcher를 Microsoft.UI.Dispatching.DispatcherQueue로 변경을 참조하세요.