Xamarin.Forms UWP 프로젝트 마이그레이션

아티클
02/13/2024

Xamarin.Forms UWP 프로젝트를 WinUI 3 프로젝트로 업데이트하려면 다음을 수행해야 합니다.

프로젝트 파일을 SDK 스타일로 업데이트합니다.
네임스페이스 업데이트
API 변경 내용 해결
호환되지 않는 종속성을 .NET 8 버전으로 업데이트하거나 대체합니다.
앱을 컴파일하고 테스트합니다.

SDK 스타일 프로젝트 파일로 업데이트

기존 Xamarin.Forms UWP 프로젝트를 SDK 스타일 WinUI 3 프로젝트로 업데이트할 수 있습니다. .NET MAUI WinUI 3 앱에 대한 SDK 스타일 프로젝트는 다음 예제와 유사합니다.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType> <!-- in Xamarin.Forms this was AppContainerExe -->
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RootNamespace>YOUR_NAMESPACE_HERE.WinUI</RootNamespace>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <Platforms>x86;x64;ARM64</Platforms>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <UseMaui>true</UseMaui>
    <!-- We do not want XAML files to be processed as .NET MAUI XAML -->
    <EnableDefaultMauiItems>false</EnableDefaultMauiItems>
  </PropertyGroup>
  ...
</Project>

Important

TFM(대상 프레임워크 모니커)은 .NET(이 경우 .NET 8)을 사용하는 것으로 프로젝트를 나타냅니다. SDK 스타일 프로젝트의 대상 프레임워크에 대한 자세한 내용은 SDK 스타일 프로젝트의 대상 프레임워크를 참조하세요.

.NET MAUI 지원을 사용하려면 프로젝트 파일에 추가 <UseMaui>true</UseMaui> 해야 합니다. 또한 프로젝트 파일에 추가 <EnableDefaultMauiItems>false</EnableDefaultMauiItems> 했는지 확인합니다. 이렇게 하면 이미 정의되고 있는 메서드에 대한 InitializeComponent 빌드 오류가 수신되지 않습니다.

MSBuild 속성 변경

프로젝트를 업그레이드하는 동안 프로젝트 파일에서 다음 UWP MSBuild 속성을 제거하는 것이 좋습니다.

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

또한 대상 프로젝트의 플랫폼 아키텍처가 다음 .NET 런타임 식별자를 사용하여 지정되었는지 확인해야 합니다.

<PropertyGroup>
   <!-- Used in .NET MAUI WinUI projects -->
   <Platforms>x86;x64;ARM64</Platforms>
</PropertyGroup>

런타임 식별자에 대한 자세한 내용은 .NET RID 카탈로그를 참조 하세요.

네임스페이스 변경

UWP와 WinUI 3 사이의 네임스페이스 이름에는 차이가 있습니다. 대부분의 경우 네임스페이스 이름을 변경하는 것만큼 쉽습니다. 그러면 코드가 컴파일됩니다. 예를 들어 네임스페이스를 네임스페이 Windows.UI.XamlMicrosoft.UI.Xaml 스로 바꿔야 합니다. 마찬가지로 네임스페이스를 네임스페이 Windows.UI.Xaml.ControlsMicrosoft.UI.Xaml.Controls 스로 바꿔야 합니다.

매핑이 더 복잡하여 접근 방법을 변경해야 하는 경우도 있습니다. 자세한 내용은 UWP API 및 라이브러리를 Windows 앱 SDK 매핑을 참조하세요.

API 변경

앱에 영향을 줄 수 있는 API 변경 내용을 해결해야 합니다. 예를 들어 일부 형식, 메서드 및 속성의 이름이 변경되거나 사용되지 않거나 제거되었을 수 있습니다. UWP 프로젝트를 WinUI 3으로 업그레이드할 때 지원되는 항목에 대한 자세한 내용은 UWP에서 WinUI 3으로 마이그레이션할 때 지원되는 내용을 참조하세요. UWP 기능 및 API를 WinUI 3에 매핑하는 방법에 대한 자세한 내용은 UWP 기능을 Windows 앱 SDK 매핑하고 UWP API 및 라이브러리를 Windows 앱 SDK 매핑하는 방법을 참조하세요.

프로젝트 파일에서 속성을 설정 $(SupportedOSPlatformVersion) 하여 프로젝트를 이전 OS 버전과 호환할 수 있습니다.

<PropertyGroup>
   <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

$(SupportedOSPlatformVersion) 속성은 앱이나 라이브러리를 실행하는 데 필요한 최소 OS 버전을 나타냅니다. 프로젝트에서 이 최소 런타임 OS 버전을 명시적으로 지정하지 않으면 기본적으로 TFM(대상 프레임워크 모니커)의 플랫폼 버전으로 설정됩니다.

프로젝트가 Windows만 대상으로 하는 경우 플랫폼 검사 조건을 생략하고 속성을 직접 설정하는 $(SupportedOSPlatformVersion) 것으로 충분합니다.

<PropertyGroup>
   <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

속성에 $(SupportedOSPlatformVersion) 대한 자세한 내용은 이전 OS 버전 지원을 참조하세요.

앱이 이전 OS 버전에서 올바르게 실행되도록 하려면 해당 OS 버전에 없는 API를 호출할 수 없습니다. 그러나 최신 API는 지원하는 OS 버전에서 실행될 때만 호출되도록 해당 API 호출 주위에 가드를 추가할 수 있습니다. 이 작업은 다음 방법으로 수행할 수 있습니다.IsWindowsVersionAtLeast

if (OperatingSystem.IsWindowsVersionAtLeast(10))
{
    // Use the API here
}

파일 제거

Xamarin.Forms UWP 프로젝트에 있는 다음 파일은 WinUI 3 프로젝트에 존재하지 않습니다.

MainPage.xaml 및 MainPage.xaml.cs
AssemblyInfo.cs
Default.rd.xml

따라서 이러한 파일이 WinUI 3 프로젝트에 있는 경우 제거해야 합니다. 이러한 파일에 포함된 모든 필수 비즈니스 논리는 다른 곳으로 이동해야 합니다.

Package.appxmanifest에 대한 변경 내용

마이그레이션된 프로젝트의 Package.appxmanifest 파일을 다음과 같이 변경해야 합니다.

애플리케이션 진입점을 .로 $targetentrypoint$ 설정합니다. 자세한 내용은 대상 진입점을 참조 하세요.
runFullTrust 기능을 추가합니다. 자세한 내용은 완전 신뢰 기능 실행을 참조 하세요.
Windows.Universal 디바이스 패밀리 및 Windows.Desktop 대상 디바이스 패밀리를 추가합니다. 자세한 내용은 유니버설 대상 디바이스 패밀리 및 데스크톱 대상 디바이스 패밀리를 참조하세요.

이러한 변경을 통해 Windows에서 앱에 대한 일반적인 배포 오류가 수정됩니다.

호환되는 Package.appxmanifest 파일의 예는 Package.appxmanifest를 참조하세요.

런타임 동작

.NET 5 이상에서는 다른 플랫폼의 String.IndexOf() 메서드에 대한 동작 변경 내용이 있습니다. 자세한 내용은 .NET 세계화 및 ICU를 참조하세요.

다음 단계

앱 부트스트랩