수동으로 Xamarin.Forms 앱을 다중 프로젝트 .NET MAUI 앱으로 업그레이드하기

다중 프로젝트 앱을 다중 프로젝트 Xamarin.Forms .NET 다중 플랫폼 앱 UI(.NET MAUI) 앱으로 업그레이드하는 과정은 Xamarin.Android 및 Xamarin.iOS 프로젝트와 동일한 단계를 포함하지만, .NET MAUI의 변경 사항을 활용하기 위한 추가 단계도 포함됩니다.

이 문서에서는 수동으로 Xamarin.Forms 라이브러리 프로젝트를 .NET MAUI 라이브러리 프로젝트로 마이그레이션하는 방법을 설명합니다. 이 작업을 수행하려면 먼저 플랫폼 프로젝트를 SDK 스타일 프로젝트로 업데이트 Xamarin.Forms 해야 합니다. SDK 스타일 프로젝트는 모든 .NET 워크로드에서 사용하는 것과 동일한 프로젝트 형식이며, 많은 Xamarin 프로젝트에 비해 자세한 내용은 훨씬 적습니다. 앱 프로젝트를 업데이트하는 방법에 대한 자세한 내용은 Xamarin.Android, Xamarin.iOS 및 Xamarin.Mac 프로젝트를 .NET, Xamarin.Android 프로젝트 마이그레이션, Xamarin Apple 프로젝트 마이그레이션 및 Xamarin.Forms UWP 프로젝트 마이그레이션으로 업그레이드를 참조하세요.

라이브러리 프로젝트를 .NET MAUI 라이브러리 프로젝트로 마이그레이션 Xamarin.Forms 하려면 다음을 수행해야 합니다.

업그레이드 프로세스를 간소화하려면 라이브러리 프로젝트와 동일한 이름의 Xamarin.Forms 새 .NET MAUI 라이브러리 프로젝트를 만든 다음 코드, 구성 및 리소스에 복사해야 합니다. 아래에 설명된 접근 방식입니다.

앱 Xamarin.Forms 업데이트

Xamarin.Forms 앱을 .NET MAUI로 업그레이드하기 전에, 먼저 Xamarin.Forms 앱을 Xamarin.Forms 5를 사용하도록 업데이트하고 여전히 올바르게 실행되는지 확인해야 합니다. 또한 앱에서 사용하는 종속성을 최신 버전으로 업데이트해야 합니다.

이렇게 하면 마이그레이션 프로세스의 나머지 부분을 간소화할 수 있습니다. 이는 .NET MAUI 간의 Xamarin.Forms API 차이를 최소화하고 종속성이 있는 경우 .NET 호환 버전의 종속성을 사용하게 되므로 도움이 됩니다.

새 프로젝트 만들기

Visual Studio에서 라이브러리 프로젝트와 동일한 이름의 Xamarin.Forms 새 .NET MAUI 클래스 라이브러리 프로젝트를 만듭니다. 이 프로젝트는 라이브러리 프로젝트의 코드를 호스트합니다 Xamarin.Forms . 프로젝트 파일을 열면 .NET SDK 스타일 프로젝트가 있는지 확인합니다.

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFrameworks>net8.0;net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
        <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net8.0-windows10.0.19041.0</TargetFrameworks>
        <!-- Uncomment to also build the tizen app. You will need to install tizen by following this: https://github.com/Samsung/Tizen.NET -->
        <!-- <TargetFrameworks>$(TargetFrameworks);net8.0-tizen</TargetFrameworks> -->
        <UseMaui>true</UseMaui>
        <SingleProject>true</SingleProject>
        <ImplicitUsings>enable</ImplicitUsings>

        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">11.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">13.1</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">21.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</SupportedOSPlatformVersion>
        <TargetPlatformMinVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</TargetPlatformMinVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'tizen'">6.5</SupportedOSPlatformVersion>
    </PropertyGroup>

</Project>

플랫폼 프로젝트에서 이 새 라이브러리 프로젝트에 대한 참조를 추가합니다. 그런 다음 Xamarin.Forms 라이브러리 파일을 .NET MAUI 라이브러리 프로젝트에 복사합니다.

네임스페이스 변경

네임스페이스가 .NET MAUI로 Xamarin.Forms 이동하는 동안 변경되었으며 Xamarin.Essentials 기능이 이제 .NET MAUI의 일부가 되었습니다. 네임스페이스를 업데이트하려면 다음 네임스페이스에 대해 찾기 및 바꾸기를 수행합니다.

.NET MAUI 프로젝트는 암시적 global using 지시문을 사용합니다. 이 기능을 사용하면 .NET MAUI 네임스페이스로 대체할 필요 없이 Xamarin.Essentials 네임스페이스에 대한 using 지시문을 제거할 수 있습니다.

또한 기본 XAML 네임스페이스가 .NET MAUI에서 http://xamarin.com/schemas/2014/forms에서 http://schemas.microsoft.com/dotnet/2021/maui로 변경되었습니다. 따라서 모든 경우의 xmlns="http://xamarin.com/schemas/2014/forms"를 xmlns="http://schemas.microsoft.com/dotnet/2021/maui"으로 바꿔야 합니다.

API 변경 사항

일부 API는 Xamarin.Forms에서 .NET MAUI로 이동하면서 변경되었습니다. 이는 Xamarin.Essentials가 .NET MAUI의 일부가 됨으로 인해 발생하는 중복 기능을 제거하고, API가 .NET 명명 지침을 따르도록 보장하기 위한 여러 가지 이유 중 일부입니다. 다음 섹션에서는 이러한 변경 내용을 설명합니다.

색 변경

Xamarin.Forms에서 Xamarin.Forms.Color 구조체를 사용하면 double 값을 사용하여 Color 개체를 생성할 수 있으며, Xamarin.Forms.Color.AliceBlue와 같은 이름이 있는 색을 제공합니다. .NET MAUI에서 이 기능은 Microsoft.Maui.Graphics.Color 클래스와 Microsoft.Maui.Graphics.Colors 클래스로 분리되었습니다.

Microsoft.Maui.Graphics 네임스페이스에 있는 Microsoft.Maui.Graphics.Color 클래스를 사용하면 float 값, byte 값 및 int 값을 사용하여 Color 개체를 생성할 수 있습니다. Microsoft.Maui.Graphics.Colors 클래스, 이는 Microsoft.Maui.Graphics 네임스페이스에도 있으며, 주로 동일한 이름의 색상을 제공합니다. 예를 들어 Colors.AliceBlue를 사용하여 AliceBlue 색상을 지정합니다.

다음 표에서는 구조체와 Microsoft.Maui.Graphics.Color 클래스 간의 Xamarin.Forms.Color API 변경 내용을 보여줍니다.

또한 Xamarin.Forms.Color에서 사용된 double 값 대신에 Microsoft.Maui.Graphics.Color의 모든 숫자 값은 float입니다.

레이아웃 변경

다음 표에서는 .NET MAUI로의 이동에서 Xamarin.Forms 제거된 레이아웃 API를 나열합니다.

또한, Xamarin.Forms 코드에서 레이아웃의 Children 컬렉션에 자식을 추가하여 레이아웃에 자식을 포함시킵니다.

Grid grid = new Grid();
grid.Children.Add(new Label { Text = "Hello world" });

.NET MAUI Children 에서 컬렉션은 .NET MAUI에서 내부적으로 사용하기 위한 것이며 직접 조작해서는 안 됩니다. 따라서 코드에서 자식은 레이아웃에 직접 추가되어야 합니다.

Grid grid = new Grid();
grid.Add(new Label { Text = "Hello world" });

업그레이드된 .NET MAUI 앱을 실행할 때 레이아웃 동작이 다르다는 것을 알 수 있습니다. 자세한 내용은 레이아웃 동작 변경 내용을 참조하세요 Xamarin.Forms.

사용자 지정 레이아웃 변경

사용자 지정 레이아웃 Xamarin.Forms를 만들기 위한 절차는 Layout<View>에서 파생된 클래스를 만들고, VisualElement.OnMeasure 및 Layout.LayoutChildren 메서드를 재정의하는 것을 포함합니다. 자세한 내용은 . 에서 사용자 지정 레이아웃 만들기를 참조하세요 Xamarin.Forms.

.NET MAUI에서 레이아웃 클래스는 추상 Layout 클래스에서 파생됩니다. 이 클래스는 플랫폼 간 레이아웃 및 측정값을 레이아웃 관리자 클래스에 위임합니다. 각 레이아웃 관리자 클래스는 인터페이스를 ILayoutManager 구현하며, 이 인터페이스는 해당 Measure 인터페이스와 ArrangeChildren 구현을 제공해야 한다고 지정합니다.

• Measure 구현은 레이아웃의 각 뷰에 IView.Measure을 호출하고, 제약 조건이 지정된 레이아웃의 총 크기를 반환합니다.
• 구현은 ArrangeChildren 각 뷰를 레이아웃 범위 내에 배치해야 하는 위치를 결정하고 적절한 범위를 가진 각 뷰를 호출 Arrange 합니다. 반환 값은 레이아웃의 실제 크기입니다.

자세한 내용은 사용자 지정 레이아웃을 참조하세요.

디바이스 변경 내용

Xamarin.Forms 에는 Xamarin.Forms.Device 앱이 실행되는 디바이스 및 플랫폼과 상호 작용하는 데 도움이 되는 클래스가 있습니다. .NET MAUI Microsoft.Maui.Controls.Device의 해당 클래스는 더 이상 사용되지 않으며 해당 기능은 여러 형식으로 대체됩니다.

다음 표에서는 Xamarin.Forms.Device 클래스의 기능을 대체할 .NET MAUI 항목을 보여줍니다.

지도 변경

Xamarin.Forms에서 Map 컨트롤과 관련 형식은 Xamarin.Forms.Maps 네임스페이스에 있습니다. .NET MAUI에서 이 기능은 Microsoft.Maui.Controls.Maps 및 Microsoft.Maui.Maps 네임스페이스로 이동되었습니다. 일부 속성의 이름이 바뀌었으며 일부 형식은 Xamarin.Essentials의 동등한 형식으로 대체되었습니다.

다음 표는 Xamarin.Forms.Maps 네임스페이스의 기능을 위한 .NET MAUI 대체 기능들을 보여줍니다.

.NET MAUI에는 두 종류의 Map 형식이 있으며 - Microsoft.Maui.Controls.Maps.Map 유형과 Microsoft.Maui.ApplicationModel.Map 유형이 있습니다. Microsoft.Maui.ApplicationModel 네임스페이스는 .NET MAUI의 global using 지시문 중 하나이므로 코드에서 Microsoft.Maui.Controls.Maps.Map 컨트롤을 사용할 때는 사용을 완전히 수식하거나 별칭을 사용하여 해야 합니다.

XAML에서는 컨트롤에 xmlns 대한 Map 네임스페이스 정의를 추가해야 합니다. 필수는 아니지만, Microsoft.Maui.Controls.Maps와 Microsoft.Maui.Controls.Shapes 네임스페이스 모두에 존재하는 Polygon 유형과 Polyline 유형 간의 충돌을 방지합니다. 자세한 내용은 지도 표시를 참조하세요.

기타 변경 사항

.NET MAUI로 이동하는 Xamarin.Forms 동안 소수의 다른 API가 통합되었습니다. 다음 표에서는 이러한 변경 내용을 보여줍니다.

또한, Android에서 앱이 백그라운드로 갔다가 다시 포그라운드로 돌아올 때 Xamarin.Forms 재정의가 호출됩니다. 그러나 이 재정의는 동일한 시나리오에서 iOS 및 Windows에서 호출되지 않습니다. .NET MAUI OnAppearing() 에서 앱이 백그라운드로 이동된 다음 포그라운드로 이동할 때 어떤 플랫폼에서도 재정의가 호출되지 않습니다. 대신 앱이 포그라운드로 돌아오는 경우 알림을 받을 수 있도록 Window의 수명 주기 이벤트를 청취해야 합니다. 자세한 내용은 .NET MAUI 창을 참조하세요.

기본 양식 변경

네이티브 양식은 .NET MAUI에서 네이티브 임베딩이 되었으며, 플랫폼 간 컨트롤을 네이티브 형식으로 변환하기 위해 다른 초기화 접근 방식과 확장 메서드를 사용합니다. 자세한 내용은 네이티브 포함을 참조하세요.

마이그레이션된 앱 부트스트랩

앱을 .NET MAUI로 수동으로 업데이트 Xamarin.Forms 하는 경우 각 플랫폼 프로젝트에서 .NET MAUI 지원을 사용하도록 설정하고 각 플랫폼 프로젝트의 진입점 클래스를 업데이트한 다음 .NET MAUI 앱의 부트스트래핑을 구성해야 합니다.

플랫폼 프로젝트에서 .NET MAUI 사용

각 플랫폼 프로젝트의 진입점 클래스를 업데이트하기 전에 먼저 .NET MAUI 지원을 사용하도록 설정해야 합니다. 이 작업은 각 플랫폼 프로젝트에서 $(UseMaui) 빌드 속성을 true로 설정하여 수행할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <UseMaui>true</UseMaui>
  </PropertyGroup>
</Project>

패키지 참조 추가

.NET 8에서 .NET MAUI는 .NET 워크로드 및 여러 NuGet 패키지로 제공됩니다. 이 방법의 장점은 프로젝트를 특정 버전에 쉽게 고정하는 동시에 미공개 또는 실험적 빌드를 쉽게 미리 볼 수 있다는 점입니다.

각 프로젝트 파일에 있는 <ItemGroup> 요소에 다음의 명시적인 패키지 참조를 추가해야 합니다.

<PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
<PackageReference Include="Microsoft.Maui.Controls.Compatibility" Version="$(MauiVersion)" />

설치한 .NET MAUI 버전에서 $(MauiVersion) 변수가 참조됩니다. 각 프로젝트 파일에 $(MauiVersion) 빌드 속성을 추가하여 이를 재정의할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <UseMaui>True</UseMaui>
        <MauiVersion>8.0.3</MauiVersion>
    </PropertyGroup>
</Project>

Android 프로젝트 구성

.NET MAUI Android 프로젝트에서 아래 코드와 MainApplication 일치하도록 클래스를 업데이트합니다.

using System;
using Android.App;
using Android.Runtime;
using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Application]
    public class MainApplication : MauiApplication
    {
        public MainApplication(IntPtr handle, JniHandleOwnership ownership) : base(handle, ownership)
        {
        }

        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

또한 MainActivity 클래스가 MauiAppCompatActivity로부터 상속받도록 업데이트하십시오.

using System;
using Microsoft.Maui;
using Android.App;
using Android.Content.PM;
using Android.Runtime;
using Android.OS;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Activity(Label = "MyTitle", Icon = "@mipmap/icon", Theme = "@style/MainTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize)]
    public class MainActivity : MauiAppCompatActivity
    {
        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);
        }
    }
}

그런 다음 매니페스트 파일을 업데이트하여 .NET MAUI에 필요한 최소 Android SDK 버전인 21을 지정 minSdKVersion 합니다. <uses-sdk /> 노드는 <manifest> 노드의 자식이므로 이를 수정하여 이 작업을 수행할 수 있습니다.

<uses-sdk android:minSdkVersion="21" android:targetSdkVersion="32" />

iOS 프로젝트 구성

.NET MAUI iOS 프로젝트에서 AppDelegate 클래스를 MauiUIApplicationDelegate로부터 상속하도록 업데이트합니다.

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Maui;
using Foundation;
using UIKit;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.iOS
{
    [Register("AppDelegate")]
    public partial class AppDelegate : MauiUIApplicationDelegate
    {
        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

그런 다음, .NET MAUI에 필요한 최소 iOS 버전인 11.0이 되도록 MinimumOSVersionInfo.plist를 업데이트합니다.

UWP 프로젝트 구성

.NET MAUI WinUI 3 프로젝트에서 아래 코드와 일치하도록 App.xaml 을 업데이트합니다.

<?xml version="1.0" encoding="utf-8"?>
<maui:MauiWinUIApplication
    x:Class="YOUR_NAMESPACE_HERE.WinUI.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:maui="using:Microsoft.Maui"
    xmlns:local="using:YOUR_NAMESPACE_HERE.WinUI">
    <maui:MauiWinUIApplication.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                <!-- Other merged dictionaries here -->
            </ResourceDictionary.MergedDictionaries>
            <!-- Other app resources here -->
        </ResourceDictionary>
    </maui:MauiWinUIApplication.Resources>
</maui:MauiWinUIApplication>

또한 아래 코드와 일치하도록 App.xaml.cs 업데이트합니다.

using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.WinUI;

public partial class App : MauiWinUIApplication
{
    public App()
    {
        InitializeComponent();
    }

    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

그런 다음 프로젝트의 Properties 폴더에 launchSettings.json 파일을 추가하고 파일에 다음 JSON을 추가합니다.

{
  "profiles": {
    "Windows Machine": {
      "commandName": "MsixPackage",
      "nativeDebugging": true
    }
  }
}

앱 진입점

.NET MAUI 앱에는 단일 플랫폼 간 앱 진입점이 있습니다. 각 플랫폼 진입점은 정적 MauiProgram 클래스에서 CreateMauiApp 메서드를 호출하고 MauiApp을 반환합니다.

따라서 다음 코드가 포함된 새 MauiProgram 클래스를 추가합니다.

namespace YOUR_NAMESPACE_HERE;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>();

        return builder.Build();
    }
}

.NET MAUI로 마이그레이션해야 하는 플랫폼별 서비스가 있는 경우 이 메서드를 사용하여 AddTransient(IServiceCollection, Type) 지정된 형식의 임시 서비스를 지정된 IServiceCollection형식에 추가합니다.

AssemblyInfo의 변경 사항

일반적으로 AssemblyInfo.cs 파일에 설정된 속성은 이제 SDK 스타일 프로젝트에서 사용할 수 있습니다. 모든 프로젝트의 프로젝트 파일로 AssemblyInfo.cs 마이그레이션하고 AssemblyInfo.cs 파일을 제거하는 것이 좋습니다.

필요에 따라 AssemblyInfo.cs 파일을 유지하고 프로젝트 파일의 GenerateAssemblyInfo 속성을 다음으로 false설정할 수 있습니다.

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

속성에 대한 GenerateAssemblyInfo 자세한 내용은 GenerateAssemblyInfo를 참조하세요.

앱 종속성 업데이트

일반적으로 Xamarin.Forms NuGet 패키지는 .NET TFM(대상 프레임워크 모니커)을 사용하여 다시 컴파일되지 않는 한 .NET 8과 호환되지 않습니다. 그러나 Android 앱은 monoandroid 및 monoandroidXX.X 프레임워크를 대상으로 하는 NuGet 패키지를 사용할 수 있습니다.

사용 중인 패키지에 대한 NuGet의 프레임워크 탭을 살펴보고 다음 표에 표시된 호환 가능한 프레임워크 중 하나가 나열되어 있는지 확인하여 패키지가 .NET 8과 호환되는지 확인할 수 있습니다.

NuGet의 패키지가 위의 호환되는 프레임워크 중 하나와 호환성을 나타내는 경우, 비록 호환되지 않는 프레임워크를 포함하더라도 그 패키지는 호환됩니다. Visual Studio에서 NuGet 패키지 관리자를 사용하여 호환되는 NuGet 패키지를 .NET MAUI 라이브러리 프로젝트에 추가할 수 있습니다.

NuGet 패키지의 .NET 8 호환 버전을 찾을 수 없는 경우 다음을 수행해야 합니다.

• 코드를 소유한 경우 .NET TFM을 사용하여 패키지를 다시 컴파일합니다.
• .NET 8 버전의 패키지 미리 보기 릴리스를 확인하십시오.
• 종속성을 .NET 8 호환 대안으로 대체합니다.

컴파일 및 문제 해결

종속성이 확인되면 프로젝트를 빌드해야 합니다. 오류가 발생하면 다음 단계를 안내해 드립니다.

다음 표에서는 일반적인 빌드 또는 런타임 문제를 해결하기 위한 지침을 제공합니다.

참고하십시오

• .NET Framework에서 .NET으로 포팅
• .NET 업그레이드 도우미