전체 마이그레이션 전략

아티클
03/28/2023

소개

Windows App SDK는 OS에서 분리되어 NuGet 패키지를 통해 개발자에게 릴리스되는 구현이 포함된 광범위한 Windows API 세트를 제공합니다. UWP(유니버설 Windows 플랫폼) 애플리케이션을 사용하는 개발자는 앱을 Windows App SDK로 이동하면 기존 기술과 소스 코드를 잘 활용할 수 있습니다.

Windows App SDK를 사용하면 최신 런타임, 언어 및 플랫폼 기능을 앱에 통합할 수 있습니다. 각 애플리케이션이 서로 다르고 개발자의 요구 사항과 기본 설정도 서로 다르기 때문에 앱의 소스 코드를 마이그레이션하는 프로세스 접근 방식도 여러 가지가 있습니다. 하지만 대략적인 접근 방식과 다양한 기능 영역에 필요한 코드 변경은 비슷합니다. 따라서 이 항목에서는 앱 마이그레이션에 접근하는 방법에 대한 전략과 특정 기능 영역에 대한 자세한 정보(및 제한 사항)를 검토합니다. 따라서 UWP에서 WinUI 3 으로 포팅할 때 지원되는 기능도 참조하세요.

대부분의 WinRT(Windows 런타임) API는 Windows App SDK 앱에서 사용할 수 있습니다. 그러나 일부 API는 데스크톱 앱에서 지원되지 않거나 제한이 있습니다.

UWP 앱에서만 사용하도록 디자인된 UI 기능에 종속된 API.
패키지 ID가 필요한 API. 이러한 API는 MSIX를 사용하여 패키징된 데스크톱 앱에서만 지원됩니다.

이러한 API를 대신할 수 있는 대안을 소개하겠습니다. 대부분의 대안은 WinUI(Windows UI Library) 또는 Windows App SDK에서 사용할 수 있는 WinRT COM 인터페이스를 통해 사용할 수 있습니다.

예를 들어 주 창 개체를 추적하고 다양한 HWND 기반 API 및 상호 운용 패턴(예: IInitializeWithWindow::Initialize)을 사용해야 하는 특정 UI 시나리오를 살펴보겠습니다.

참고 항목

데스크톱 앱에서 지원되지 않는 Windows 런타임 API도 살펴보세요. Windows App SDK 앱은 데스크톱 앱의 일종입니다. 다른 종류의 데스크톱 앱으로는 .NET 데스크톱 앱과 C/C++ Win32 데스크톱 앱이 있습니다. 이 항목의 대상은 Windows App SDK 앱을 포함하여(이에 국한되지 않음) 다양한 종류의 데스크톱 앱으로 마이그레이션하려는 개발자입니다.

이 마이그레이션 가이드 및 개발자의 마이그레이션 경험에 대한 피드백을 기다리고 있습니다. 이 페이지 하단에 있는 피드백 섹션을 다음과 같이 사용할 수 있습니다.

Windows App SDK에 대한 질문과 피드백이 있거나 토론을 시작하려면 이 제품 단추를 사용합니다. WindowsAppSDK GitHub 리포지토리의 토론 탭에서 토론을 시작할 수도 있습니다. 이러한 채널을 사용하여 해결하려는 문제, 지금까지 시도한 문제 해결 방법, 앱에 이상적인 솔루션이 무엇인지 Microsoft에 알려줄 수도 있습니다.
이 마이그레이션 가이드에서 누락되었거나 잘못된 정보에 대한 피드백은 이 페이지 단추를 사용하세요.

Windows App SDK로 마이그레이션해야 하는 이유

Windows App SDK는 새로운 플랫폼 기능뿐만 아니라 사용자를 만족시키기 위해 개발되고 설계된 최신 WinUI 3(Windows UI 3) 라이브러리로 앱을 향상시킬 수 있는 기회를 제공합니다.

또한 Windows App SDK는 이전 버전과 호환되며 Windows 10 2018년 10월 업데이트라고도 하는 Windows 10, 버전 1809(10.0, 빌드 17763)까지 앱을 지원합니다.

Windows 앱 SDK 이동의 가치 제안은 다양합니다. 다음은 몇 가지 고려 사항입니다.

WinUI(Windows UI) 라이브러리 3 및 WebView2와 같은 최신 UI(사용자 인터페이스) 플랫폼 및 컨트롤
데스크톱 앱 플랫폼 간 단일 API 표면
Windows와 별도로 릴리스되는 더 빠른 릴리스 속도
모든 Windows 버전에서 일관적인 환경
.NET 호환성.
Windows 10, 버전 1809까지 이전 버전과 호환
런타임 환경 개선 MSIX 컨테이너를 참조하세요.

자세한 내용은 Windows App SDK를 참조하세요.

마이그레이션 프로세스 개요

참고 항목

마이그레이션하려는 앱의 UWP 버전을 원본 솔루션/프로젝트(마이그레이션 프로세스의 원본)라고 생각하면 됩니다. Windows App SDK 버전은 대상 솔루션(마이그레이션 프로세스의 대상)입니다.

Windows App SDK VSIX 설치

Windows App SDK에 대한 안정적인 릴리스 채널에서 Windows App SDK VSIX(Visual Stud 확장) 설치 관리자를 다운로드하고 실행하여 설치합니다.

새 프로젝트 만들기

Visual Studio에서 첫 번째 WinUI 3 프로젝트를 만듭니다. 예를 들어 비어 있는 앱, 패키지됨(데스크톱의 WinUI 3) 프로젝트 템플릿을 사용합니다 . 새 프로젝트 만들기 대화 상자에서 언어를 C# 또는 C++로, 플랫폼을 Windows App SDK로, 프로젝트 형식을 WinUI 또는 데스크톱으로 필터링하여 해당 프로젝트 템플릿을 찾을 수 있습니다.

솔루션 탐색기에 2개의 프로젝트가 표시되는데, 하나는 (데스크톱)으로 한정되고 다른 하나는 (패키지)로 한정됩니다.

종속성이 가장 적은 코드부터 먼저 마이그레이션

이 권장 사항을 설명하기 위해 PhotoLab 사례 연구를 예로 들겠습니다. PhotoLab 샘플 앱의 경우 가장 확실한 방법 중 하나는 앱에서 매우 중요한 MainPage를 마이그레이션하는 작업부터 시작하는 것입니다. 그러나 이렇게 하려고 하면 MainPage가 DetailPage 보기에 종속되어 있고, DetailPage는 Photo 모델에 종속되어 있다는 사실을 곧 알게 됩니다. 이 경로를 따른다면 작업이 지속적으로 중단될 수 있습니다(새로 발견되는 종속성을 해결하기 위해 전환). 물론 모든 종속성을 추적하여 결국 전체 프로젝트를 한 번의 거대한 도약으로 이식할 때까지는 클린 빌드를 얻을 것이라고 기대하지 않습니다.

반면 어디에도 종속되지 않은 프로젝트부터 시작하여 점차 밖으로 나가면서 작업한다면(가장 종속성이 적은 부분부터 가장 종속성이 많은 부분의 순서로) 한 번에 한 부분씩 집중할 수 있습니다. 또한 각 부분을 마이그레이션한 후 클린 빌드를 얻을 수 있으며, 이러한 방식으로 마이그레이션 프로세스가 정상적으로 진행되고 있는지 확인할 수 있습니다.

따라서 개발자 고유의 앱을 마이그레이션할 때는 종속성이 가장 적은 코드부터 마이그레이션하는 것이 좋습니다.

파일을 복사할까요 아니면 파일 콘텐츠를 복사할까요?

마이그레이션할 때 당연히 자산 파일 콘텐츠가 아닌 자산 파일을 복사합니다. 하지만 소스 코드 파일은 어떨까요? 예를 들어 PhotoLab 사례 연구 및 사진 편집기 사례 연구의 MainPage 클래스를 다시 살펴보겠습니다.

C#. C# 버전(PhotoLab)에서 MainPage는 소스 코드 파일 MainPage.xaml 및 MainPage.xaml.cs로 구성됩니다.

C++/WinRT. C++/WinRT 버전(사진 편집기)에서 MainPage는 소스 코드 파일 MainPage.xaml, MainPage.idl, MainPage.h 및 MainPage.cpp로 구성됩니다.

따라서 다음 두 옵션 중에 선택할 수 있습니다.

(권장 옵션) 파일 탐색기를 사용하여 파일 자체를 복사한 다음, 대상 프로젝트에 복사본을 추가할 수 있습니다. App.xaml 및 App.xaml.cs 파일은 대상 프로젝트에 이미 있고 Windows App SDK와 관련된 소스 코드를 포함하고 있기 때문에 이 권장 옵션의 예외입니다. 이러한 파일은 이미 있는 소스 코드를 소스 프로젝트의 소스 코드와 병합해야 합니다.
또는 Visual Studio를 사용하여 대상 프로젝트에 새 Page 파일(예: MainPage.xaml 및 MainPage.xaml.cs)을 만든 다음, 소스 코드 파일의 콘텐츠를 원본 프로젝트에서 대상 프로젝트로 복사할 수도 있습니다. C++/WinRT 프로젝트의 경우 이 옵션을 선택하면 훨씬 많은 단계를 수행해야 합니다.

MainPage 및 MainWindow 섹션도 확인하세요.

폴더 및 파일 이름 차이(C++/WinRT)

C++/WinRT UWP 프로젝트에서 XAML 뷰에 대한 코드 숨김 파일의 이름은 MainPage.h 및 MainPage.cpp 형식으로 지정됩니다. 하지만 C++/WinRT Windows App SDK에서는 이름을 MainPage.xaml.h 및 MainPage.xaml.cpp로 변경해야 합니다.

C++/WinRT UWP 프로젝트에서 MyPage라는 가상의 XAML 보기를 (모델, 보기 및 viewmodel의 의미에서) 마이그레이션하는 경우 MyPage.xaml.cpp에서 #include "DetailPage.xaml.h" 바로 뒤에 #include "MyPage.g.cpp"를 추가해야 합니다. 그리고 MyModel이라는 가상 모델의 경우 MyModel.cpp에서 "MyModel.h" 바로 뒤에 #include "MyModel.g.cpp"를 추가합니다. 예제는 DetailPage 소스 코드 마이그레이션을 참조하세요.

마이그레이션된 프로젝트의 이름을 변경하는 경우

마이그레이션하는 동안 대상 프로젝트의 이름을 원본 프로젝트와 다르게 지정할 수 있습니다. 이렇게 하면 원본 프로젝트 내부의 기본 네임스페이스에 영향을 미칩니다. 원본 프로젝트에서 대상 프로젝트로 소스 코드를 복사할 때 소스 코드에 언급된 네임스페이스 이름을 변경해야 할 수도 있습니다.

예를 들어 UWP PhotoLab 샘플 앱의 Windows App SDK 마이그레이션(C#) 사례 연구에서 프로젝트 이름(및 결과적으로 기본 네임스페이스 이름)을 변경합니다. 이 사례 연구에서는 원본 프로젝트에서 대상 프로젝트로 파일 콘텐츠를 복사하는 대신 파일 탐색기 사용하여 전체 파일을 복사합니다. 원본 프로젝트/네임스페이스 이름은 PhotoLab이고, 대상 프로젝트/네임스페이스 이름은 PhotoLabWinUI3입니다. 따라서 복사한 소스 코드 파일의 콘텐츠에서 PhotoLab을 검색하여 PhotoLabWinUI3으로 변경해야 합니다.

이 사례 연구에서는 App.xaml, App.xaml.cs, MainPage.xaml, MainPage.xaml.cs, DetailPage.xaml, DetailPage.xaml.cs, ImageFileInfo.cs 및 LoadedImageBrush.cs에서 이렇게 변경했습니다.

원본 프로젝트에 설치된 것과 동일한 NuGet 패키지 설치

마이그레이션 프로세스 중에 해야 하는 한 가지 작업은 원본 프로젝트가 종속된 NuGet 패키지를 식별하는 것입니다. 그런 다음, 동일한 NuGet 패키지를 대상 프로젝트에 설치합니다.

예를 들어 UWP PhotoLab 샘플 앱의 Windows App SDK 마이그레이션(C#) 사례 연구에서 원본 프로젝트에는 Microsoft.Graphics.Win2D NuGet 패키지의 참조가 포함되어 있습니다. 따라서 이 사례 연구에서는 동일한 NuGet 패키지에 대한 참조를 대상 프로젝트에 추가합니다.