.NET Upgrade Assistant를 사용하여 UWP에서 Windows App SDK로 마이그레이션

아티클
03/27/2024

.NET Upgrade Assistant( .NET Upgrade Assistant개요 참조)는 C# Universal Windows Platform(UWP) 앱을 Windows App SDK를 사용하는 Windows UI Library(WinUI) 3 앱으로 마이그레이션하는 데 도움이 될 수 있는 Visual Studio 확장(권장) 및 명령줄 도구입니다.

.NET 업그레이드 도우미의 UWP 지원에 대한 로드맵에는 추가 도구 개선 사항과 새 기능에 대한 마이그레이션 지원 추가가 포함됩니다. .NET 업그레이드 도우미와 관련된 문제가 발견되면 Visual Studio 내에서 피드백 보내기 문제>보고를 선택하여>문제를 제출할 수 있습니다.

이 업그레이드 도우미 GitHub 리포지토리도 참조하세요. 명령줄에서 도구를 실행하는 옵션이 설명되어 있습니다.

.NET Upgrade Assistant 설치

.NET 업그레이드 도우미를 Visual Studio 확장 또는 .NET 명령줄 도구로 설치할 수 있습니다. 자세한 내용은 .NET 업그레이드 도우미 설치를 참조하세요.

요약

.NET 업그레이드 도우미를 사용하여 UWP 앱을 마이그레이션하는 경우 도구가 수행하는 마이그레이션 프로세스의 대략적인 단계와 단계는 다음과 같습니다.

필요에 따라 프로젝트를 복사하고 복사본을 마이그레이션합니다. 원래 프로젝트를 변경하지 않고 그대로 유지합니다.
필요에 따라 프로젝트를 현재 위치로 마이그레이션합니다(폴더 이름을 변경하지 않고 동일한 폴더 및 파일에서). 복사본을 만들지 않습니다.
프로젝트를 .NET Framework 프로젝트 형식에서 최신 .NET SDK 프로젝트 형식으로 업그레이드합니다.
NuGet 패키지 참조를 정리합니다. 앱에서 참조하는 패키지 외에도 packages.config 파일에는 해당 패키지의 종속성에 대한 참조가 포함되어 있습니다. 예를 들어, 패키지 B에 따라 달라지는 패키지 A에 참조를 추가한 경우, 두 패키지 모두 packages.config 파일에서 참조됩니다. 새 프로젝트 시스템에서는 패키지 A에 대한 참조만 있으면 됩니다. 따라서 이 단계에서는 패키지 참조를 분석하고 필요하지 않은 참조를 제거합니다. 앱이 여전히 .NET Framework 어셈블리를 참조하고 있습니다. 이러한 어셈블리 중 일부는 NuGet 패키지로 사용할 수 있습니다. 따라서 이 단계에서는 이러한 어셈블리를 분석하고 적절한 NuGet 패키지를 참조합니다.
.NET 6 및 Windows 앱 SDK 대상으로 합니다.
TFM(대상 프레임워크 모니커)( SDK 스타일 프로젝트의 대상 프레임워크 참조)을 .NET Framework에서 제안된 SDK로 변경합니다. 예들 들어 net6.0-windows입니다.
소스별 코드 변경을 수행하여 UWP 소스 코드를 WinUI 2에서 WinUI 3으로 마이그레이션합니다.
템플릿, 구성 및 코드 파일을 추가/업데이트합니다. 예를 들어 필요한 게시 프로필, App.xaml.cs, MainWindow.xaml.cs, MainWindow.xaml, 및 기타를 추가합니다.
네임스페이스를 업데이트하고 MainPage 탐색을 추가합니다.
UWP와 Windows 앱 SDK 간에 다른 API를 검색하고 수정하려고 시도하고 작업 목록 TODO를 사용하여 더 이상 지원되지 않는 API를 표시합니다.

또한 이 도구는 실행될 때 도구의 출력 내에서 경고 메시지 형식으로 마이그레이션 지침을 제공하고 작업 목록 TODO를 프로젝트의 소스 코드 내에서 주석 형식으로 제공하는 것을 목표로 합니다(예: UWP 소스 코드의 완전히 자동화된 마이그레이션이 불가능한 경우). 일반적인 작업 목록 TODO에는 이 마이그레이션 설명서의 항목에 대한 링크가 포함되어 있습니다. 개발자는 항상 마이그레이션 프로세스를 제어할 수 있습니다.

팁

도구에서 생성한 모든 TODO를 보려면 Visual Studio의 작업 목록을 확인합니다.

참고 항목

도구 실행이 완료되면 필요한 경우 수행할 수 있는 몇 가지 후속 단계가 있습니다. 코드를 App.xaml.old.csApp.xaml.cs이동할 수 있으며 도구에서 만든 백업에서 복원 AssemblyInfo.cs 할 수 있습니다.

도구에서 지원하는 내용

.NET Upgrade Assistant의 이번 릴리스는 현재 미리보기 중이며 자주 업데이트를 받고 있습니다. 이 도구는 현재 C# 프로그래밍 언어만 지원합니다. C++가 아닙니다. 또한 대부분의 경우 이 릴리스에서는 마이그레이션을 완료하기 위해 추가적인 노력이 필요합니다.

이 도구는 프로젝트와 코드를 컴파일하도록 마이그레이션하는 것을 목표로 합니다. 그러나 일부 기능은 조사하고 수정해야 합니다( 작업 목록 TODO를 통해). 마이그레이션하기 전에 고려해야 할 사항에 대한 자세한 내용은 UWP에서 WinUI 3로 마이그레이션할 때 지원되는 사항을 참조하십시오.

.NET 업그레이드 도우미의 현재 릴리스에 대한 다음과 같은 제한 사항으로 인해 앱을 마이그레이션하기 전에 향후 릴리스를 기다리도록 선택할 수 있습니다.

ApplicationView API에서 마이그레이션은 지원되지 않습니다.
AppWindow 관련 API에서 마이그레이션은 지원되지 않습니다.

가능한 경우 도구는 경고를 생성하려고 합니다. 고의로 변경될 때까지 코드가 컴파일되지 않습니다.

사용자 지정 보기는 지원되지 않습니다. 예를 들어 MessageDialog를 확장하고 API를 잘못 호출하는 사용자 지정 대화 상자에 대한 경고 또는 수정 사항이 수신되지 않습니다.
Windows 런타임 구성 요소는 지원되지 않습니다.

다중 창 앱이 올바르게 마이그레이션되지 않을 수 있습니다.
비표준 파일 구조(예: App.xamlApp.xaml.cs 루트 폴더에 있지 않음)를 따르는 프로젝트가 올바르게 마이그레이션되지 않을 수 있습니다.

이 업그레이드 도우미 GitHub 리포지토리는 팁 및 알려진 문제를 해결하는 방법을 설명합니다. 도구를 사용하는 동안 문제가 발견되면 동일한 GitHub 리포지토리에 보고하고 영역 태그 UWP로 태그를 지정하세요. 우리는 그것을 주셔서 감사합니다!

참고 항목

마이그레이션 프로세스에 대한 지침과 UWP와 Windows 앱 SDK 기능 및 API 간의 차이점은 UWP에서 Windows 앱 SDK 마이그레이션을 참조하세요.

팁

명령을 upgrade-assistant --version실행하여 가지고 있는 도구의 버전을 확인할 수 있습니다.

UWP PhotoLab 샘플을 사용하여 도구 시험 사용

시험 사용을 위해 .NET 업그레이드 도우미를 살펴보겠습니다.

원본 자료로 UWP PhotoLab 샘플 애플리케이션을 마이그레이션합니다. PhotoLab은 이미지 파일을 보고 편집하기 위한 샘플 앱입니다. XAML 레이아웃, 데이터 바인딩 및 UI 사용자 지정 기능을 보여 줍니다.

참고 항목

UWP PhotoLab 샘플 앱의 Windows 앱 SDK 마이그레이션에서 PhotoLab 샘플이 완전히 수동으로 마이그레이션되는 사례 연구를 확인할 수 있습니다.

먼저 위의 링크에서 PhotoLab 샘플 소스 코드를 복제하거나 다운로드합니다.

팁

이 도구를 사용하여 앱 마이그레이션을 자동화한 후에는 마이그레이션을 완료하기 위해 추가 수동 작업이 필요합니다.

Visual Studio에서 PhotoLab 솔루션을 엽니다.
.NET Upgrade Assistant 확장을 설치한 후(이 항목의 앞에 있는 .NET Upgrade Assistant 설치 참조), Solution Explorer에서 프로젝트를 마우스 오른쪽 버튼으로 클릭하고 Upgrade을 클릭합니다.
이 프로젝트를 최신 .NET 버전 옵션으로 업그레이드를 선택합니다.
이 현재 위치 프로젝트 업그레이드 옵션을 선택합니다.
대상 프레임워크를 선택합니다.
이 선택한 업그레이드를 클릭합니다.
.NET 업그레이드 도우미가 실행되고 Visual Studio 출력 창을 사용하여 정보 및 상태 출력합니다.

업그레이드 작업이 완료될 때까지 진행률 표시줄을 모니터링할 수 있습니다.

이 PhotoLab 샘플 앱에 대한 코드 마이그레이션에는 다음이 포함됩니다.

콘텐츠 대화 상자 및 파일 저장 선택기 API에 대한 변경 내용입니다.
애니메이션 패키지에 대한 XAML 업데이트입니다.
경고 메시지를 표시하고, 커스텀 백 버튼을 위해 DetailPage.xaml, DetailPage.xaml.cs, MainPage.xaml.cs 에서 작업 목록 TODO를 추가합니다.
뒤로 단추 기능을 구현하고 작업 목록 TODO를 추가하여 XAML 단추를 사용자 지정합니다.
뒤로 단추 구현에 대해 자세히 알아보는 데 사용할 수 있는 설명서에 대한 링크가 제공됩니다.

결과 .csproj 버전 번호는 약간 다르지만, 기본적으로 다음과 같이 표시됩니다(간결하게 하기 위해 일부 빌드 구성 속성 그룹이 제거됨).

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
    <OutputType>WinExe</OutputType>
    <DefaultLanguage>en-US</DefaultLanguage>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <EnableMsixTooling>true</EnableMsixTooling>
    <Platforms>x86;x64;arm64</Platforms>
    <PublishProfile>win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>
  <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
      <SubType>Designer</SubType>
    </AppxManifest>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.1.0" />
    <PackageReference Include="Microsoft.Graphics.Win2D" Version="1.0.0.30" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="6.0.0" />
    <PackageReference Include="CommunityToolkit.WinUI.UI.Animations" Version="7.1.2" />
  </ItemGroup>
  <ItemGroup>
    <Compile Remove="App.xaml.old.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="App.xaml.old.cs" />
  </ItemGroup>
</Project>

볼 수 있듯이 프로젝트는 이제 Windows 앱 SDK, WinUI 3 및 .NET 6을 참조합니다. 그 PhotoLab이 마이그레이션되었으므로 WinUI 3 앱이 제공해야 하는 모든 새로운 기능을 활용하고 플랫폼을 통해 앱을 확장할 수 있습니다.

또한 .NET Upgrade Assistant는 업그레이드 프로세스를 계속 진행하는 데 도움이 되는 분석기를 프로젝트에 추가합니다. 예를 들어 Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers NuGet 패키지가 있습니다.

후속 수동 마이그레이션

이 시점에서 마이그레이션된 PhotoLab 솔루션 또는 프로젝트를 열고 소스 코드에서 변경된 내용을 확인할 수 있습니다. WinUI 3 버전이 UWP 버전처럼 빌드, 실행 및 동작하기 전에 연결 작업을 완료하려면 프로젝트에 좀 더 많은 작업이 필요합니다.

수동으로 마이그레이션을 완료하기 위해 수행해야 할 작업은 Visual Studio(View>작업 목록)의 작업 목록를 참조하십시오.

앱의 UWP(.NET Framework) 버전에 프로젝트에서 실제로 사용하지 않는 라이브러리 참조가 포함되어 있을 수 있습니다. 각 참조를 분석하고 필요한지 여부를 결정해야 합니다. 또한 도구가 잘못된 버전에 대한 NuGet 패키지 참조를 추가하거나 업그레이드했을 수도 있습니다.

업그레이드 도우미는 앱을 시작하려면 몇 가지 편집이 필요한 편집을 편집 Package.appxmanifest하지 않습니다.

루트 <패키지> 요소에 다음 네임스페이스를 추가합니다.

xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

이 <Application> 요소를 EntryPoint="appnamehere.App" 에서 EntryPoint="$targetentrypoint$"로 편집합니다
지정된 항목을 Capability 다음으로 대체합니다.

<rescap:Capability Name="runFullTrust" />

파일 .csproj 에서 설정할 <OutputType>WinExe</OutputType> 프로젝트 파일을 편집해야 할 수 있습니다 <UseMaui>False</UseMaui>.

XAML 컨트롤을 많이 사용하려면 다음 예와 같이 app.xaml 파일에 <XamlControlsResources>가 포함되어 있는지 확인합니다:

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            <!-- Other merged dictionaries here -->
        </ResourceDictionary.MergedDictionaries>
        <!-- Other app resources here -->
    </ResourceDictionary>
</Application.Resources>

문제 해결 팁

.NET 업그레이드 도우미를 사용하는 경우 발생할 수 있는 여러 가지 알려진 문제가 있습니다. 경우에 따라서는 이러한 문제들이 .NET 업그레이드 도우미가 내부에서 사용하는 try-convert 도구와 관련이 있습니다.

하지만 자세한 문제 해결 팁과 알려진 문제는 업그레이드 도우미 GitHub 리포지토리를 참조하세요.

.NET Upgrade Assistant를 사용하여 UWP에서 Windows App SDK로 마이그레이션

.NET Upgrade Assistant 설치

요약

도구에서 지원하는 내용

UWP PhotoLab 샘플을 사용하여 도구 시험 사용

후속 수동 마이그레이션

문제 해결 팁

피드백

추가 리소스