다음을 통해 공유

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

  • 아티클

다중 프로젝트 앱을 다중 프로젝트 Xamarin.Forms .NET 다중 플랫폼 앱 UI(.NET MAUI) 앱으로 업그레이드하면 Xamarin.Android 및 Xamarin.iOS 프로젝트와 동일한 단계를 수행하며 .

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

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

  • 5를 사용하도록 Xamarin.Forms 앱을 업데이트합니다Xamarin.Forms.
  • 앱의 종속성을 최신 버전으로 업데이트합니다.
  • 앱이 계속 작동하는지 확인합니다.
  • 프로젝트 파일을 SDK 스타일로 업데이트합니다.
  • 네임스페이스를 업데이트합니다.
  • API 변경 내용을 해결합니다.
  • .NET MAUI를 구성합니다.
  • 호환되지 않는 종속성을 .NET 8 버전으로 업그레이드하거나 대체합니다.
  • 앱을 컴파일하고 테스트합니다.

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

앱 Xamarin.Forms 업데이트

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

이렇게 하면 마이그레이션 프로세스의 나머지 부분을 간소화할 수 있습니다. 이는 .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>

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

네임스페이스 변경

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

Xamarin.Forms 네임스페이스 .NET MAUI 네임스페이스
Xamarin.Forms Microsoft.Maui 및 Microsoft.Maui.Controls
Xamarin.Forms.DualScreen Microsoft.Maui.Controls.Foldable
Xamarin.Forms.Maps Microsoft.Maui.Controls.Maps 및 Microsoft.Maui.Maps
Xamarin.Forms.PlatformConfiguration Microsoft.Maui.Controls.PlatformConfiguration
Xamarin.Forms.PlatformConfiguration.AndroidSpecific Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific
Xamarin.Forms.PlatformConfiguration.AndroidSpecific.AppCompat Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific.AppCompat
Xamarin.Forms.PlatformConfiguration.TizenSpecific Microsoft.Maui.Controls.PlatformConfiguration.TizenSpecific
Xamarin.Forms.PlatformConfiguration.WindowsSpecific Microsoft.Maui.Controls.PlatformConfiguration.WindowsSpecific
Xamarin.Forms.PlatformConfiguration.iOSSpecific Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific
Xamarin.Forms.Shapes Microsoft.Maui.Controls.Shapes
Xamarin.Forms.StyleSheets Microsoft.Maui.Controls.StyleSheets
Xamarin.Forms.Xaml Microsoft.Maui.Controls.Xaml

.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 Xamarin.Forms 으로 변경되었습니다. 따라서 모든 항목을 xmlns="http://xamarin.com/schemas/2014/forms" .으로 xmlns="http://schemas.microsoft.com/dotnet/2021/maui"바꿔야 합니다.

참고 항목

업그레이드 도우미가 설치된 경우 Visual Studio에서 빠른 작업을 사용하여 네임스페이스를 Microsoft.Maui 빠르게 업데이트 Xamarin.Forms 할 수 있습니다.

API 변경

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

색 변경

에서 Xamarin.Forms구조체를 Xamarin.Forms.Color 사용하면 값을 사용하여 double 개체를 생성 Color 할 수 있으며 명명된 색(예: Xamarin.Forms.Color.AliceBlue.)을 제공합니다. .NET MAUI에서 이 기능은 클래스 및 Microsoft.Maui.Graphics.Colors 클래스로 Microsoft.Maui.Graphics.Color 구분되었습니다.

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

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

Xamarin.Forms API .NET MAUI API Comment(설명)
Xamarin.Forms.Color.R Microsoft.Maui.Graphics.Color.Red
Xamarin.Forms.Color.G Microsoft.Maui.Graphics.Color.Green
Xamarin.Forms.Color.B Microsoft.Maui.Graphics.Color.Blue
Xamarin.Forms.Color.A Microsoft.Maui.Graphics.Color.Alpha
Xamarin.Forms.Color.Hue Microsoft.Maui.Graphics.Color.GetHue Xamarin.Forms 속성이 .NET MAUI의 메서드로 대체되었습니다.
Xamarin.Forms.Color.Saturation Microsoft.Maui.Graphics.Color.GetSaturation Xamarin.Forms 속성이 .NET MAUI의 메서드로 대체되었습니다.
Xamarin.Forms.Color.Luminosity Microsoft.Maui.Graphics.Color.GetLuminosity Xamarin.Forms 속성이 .NET MAUI의 메서드로 대체되었습니다.
Xamarin.Forms.Color.Default 동등한 .NET MAUI가 없습니다. 대신 개체의 기본값은 Microsoft.Maui.Graphics.Color .입니다 null.
Xamarin.Forms.Color.Accent 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.Color.FromHex Microsoft.Maui.Graphics.Color.FromArgb Microsoft.Maui.Graphics.Color.FromHex 는 사용되지 않으며 향후 릴리스에서 제거될 예정입니다.

또한 a의 모든 숫자 값은 .에 Microsoft.Maui.Graphics.Color 사용되는 Xamarin.Forms.Color값이 아닌 double 값입니다float.

참고 항목

와 달리 Xamarin.Forms암시 Microsoft.Maui.Graphics.Color 적 변환 System.Drawing.Color은 없습니다.

레이아웃 변경

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

Xamarin.Forms API .NET MAUI API 설명
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add Add 3개의 인수를 허용하는 오버로드는 .NET MAUI에 없습니다.
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.Grid.IGridList<T>.AddVertical 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.RelativeLayout Microsoft.Maui.Controls.Compatibility.RelativeLayout .NET MAUI에서는 RelativeLayout .NET MAUI에서 Xamarin.Forms마이그레이션하는 사용자에 대한 호환성 제어로만 존재합니다. 대신 사용 Grid 하거나 호환성 네임스페이 xmlns 스에 대한 네임스페이스를 추가합니다.

또한 자식을 레이아웃 컬렉션에 추가하여 코드의 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" });

Important

레이아웃 확장 메서드와 같은 GridExtensions.Add모든 Add 레이아웃 확장 메서드는 레이아웃 컬렉션이 아닌 레이아웃에서 호출됩니다Children.

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

사용자 지정 레이아웃 변경 내용

사용자 지정 레이아웃 Xamarin.Forms 을 만드는 프로세스에는 파생Layout<View>되는 클래스를 만들고 메서드 Layout.LayoutChildren 와 메서드를 재정의 VisualElement.OnMeasure 하는 과정이 포함됩니다. 자세한 내용은 .에서 사용자 지정 레이아웃 만들기를 참조 하세요 Xamarin.Forms.

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

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

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

디바이스 변경 내용

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

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

Xamarin.Forms API .NET MAUI API 설명
Xamarin.Forms.Device.Android Microsoft.Maui.Devices.DevicePlatform.Android
Xamarin.Forms.Device.iOS Microsoft.Maui.Devices.DevicePlatform.iOS
Xamarin.Forms.Device.GTK 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.Device.macOS 동등한 .NET MAUI가 없습니다. 대신 Microsoft.Maui.Devices.DevicePlatform.MacCatalyst을 사용합니다.
Xamarin.Forms.Device.Tizen Microsoft.Maui.Devices.DevicePlatform.Tizen
Xamarin.Forms.Device.UWP Microsoft.Maui.Devices.DevicePlatform.WinUI
Xamarin.Forms.Device.WPF 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.Device.Flags 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.Device.FlowDirection Microsoft.Maui.ApplicationModel.AppInfo.RequestedLayoutDirection
Xamarin.Forms.Device.Idiom Microsoft.Maui.Devices.DeviceInfo.Idiom
Xamarin.Forms.Device.IsInvokeRequired Microsoft.Maui.Dispatching.Dispatcher.IsDispatchRequired
Xamarin.Forms.Device.OS Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.RuntimePlatform Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.BeginInvokeOnMainThread Microsoft.Maui.ApplicationModel.MainThread.BeginInvokeOnMainThread
Xamarin.Forms.Device.GetMainThreadSynchronizationContextAsync Microsoft.Maui.ApplicationModel.MainThread.GetMainThreadSynchronizationContextAsync
Xamarin.Forms.Device.GetNamedColor 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.Device.GetNamedSize 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.Device.Invalidate Microsoft.Maui.Controls.VisualElement.InvalidateMeasure
Xamarin.Forms.Device.InvokeOnMainThreadAsync Microsoft.Maui.ApplicationModel.MainThread.InvokeOnMainThreadAsync
Xamarin.Forms.Device.OnPlatform Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.OpenUri Microsoft.Maui.ApplicationModel.Launcher.OpenAsync
Xamarin.Forms.Device.SetFlags 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.Device.SetFlowDirection Microsoft.Maui.Controls.Window.FlowDirection
Xamarin.Forms.Device.StartTimer Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer 또는 Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed

지도 변경 내용

에서 Xamarin.Forms컨트롤 및 연결된 형식은 네임스페이스에 Xamarin.Forms.Maps Map 있습니다. .NET MAUI에서 이 기능은 네임스페이스 및 Microsoft.Maui.Maps 네임스페이 Microsoft.Maui.Controls.Maps 스로 이동되었습니다. 일부 속성의 이름이 바뀌었고 일부 형식은 해당 형식으로 Xamarin.Essentials바뀝니다.

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

Xamarin.Forms API .NET MAUI API Comment(설명)
Xamarin.Forms.Maps.Map.HasScrollEnabled Microsoft.Maui.Controls.Maps.Map.IsScrollEnabled
Xamarin.Forms.Maps.Map.HasZoomEnabled Microsoft.Maui.Controls.Maps.Map.IsZoomEnabled
Xamarin.Forms.Maps.Map.TrafficEnabled Microsoft.Maui.Controls.Maps.Map.IsTrafficEnabled
Xamarin.Forms.Maps.Map.MoveToLastRegionOnLayoutChange 동등한 .NET MAUI가 없습니다.
Xamarin.Forms.Maps.Pin.Id Microsoft.Maui.Controls.Maps.Pin.MarkerId
Xamarin.Forms.Maps.Pin.Position Microsoft.Maui.Controls.Maps.Pin.Location
Xamarin.Forms.Maps.MapClickedEventArgs.Position Microsoft.Maui.Controls.Maps.MapClickedEventArgs.Location
Xamarin.Forms.Maps.Position Microsoft.Maui.Devices.Sensors.Location 형식의 멤버가 형식 Xamarin.Forms.Maps.Position 으로 Microsoft.Maui.Devices.Sensors.Location 변경되었습니다.
Xamarin.Forms.Maps.Geocoder Microsoft.Maui.Devices.Sensors.Geocoding 형식의 멤버가 형식 Xamarin.Forms.Maps.Geocoder 으로 Microsoft.Maui.Devices.Sensors.Geocoding 변경되었습니다.

.NET MAUI에는 두 Map 가지 형식이 Microsoft.Maui.Controls.Maps.Map 있습니다 Microsoft.Maui.ApplicationModel.Map. Microsoft.Maui.ApplicationModel 네임스페이스는 .NET MAUI의 global using 지시문 중 하나이므로 코드에서 컨트롤을 Microsoft.Maui.Controls.Maps.Map 사용하는 경우 사용량을 정규화 Map 하거나 사용 별칭을 사용해야 합니다.

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

기타 변경 사항

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

Xamarin.Forms API .NET MAUI API 설명
Xamarin.Forms.Application.Properties Microsoft.Maui.Storage.Preferences
Xamarin.Forms.Button.Image Microsoft.Maui.Controls.Button.ImageSource
Xamarin.Forms.Frame.OutlineColor Microsoft.Maui.Controls.Frame.BorderColor
Xamarin.Forms.IQueryAttributable.ApplyQueryAttributes Microsoft.Maui.Controls.IQueryAttributable.ApplyQueryAttributes 에서 Xamarin.Forms메서드는 ApplyQueryAttributes 인수를 IDictionary<string, string> 허용합니다. .NET MAUI에서 메서드는 ApplyQueryAttributes 인수를 IDictionary<string, object> 허용합니다.
Xamarin.Forms.MenuItem.Icon Microsoft.Maui.Controls.MenuItem.IconImageSource Xamarin.Forms.MenuItem.Icon는 에 대한 Xamarin.Forms.ToolbarItem기본 클래스이므로 ToolbarItem.Icon .가 됩니다.ToolbarItem.IconImageSource
Xamarin.Forms.OrientationStateTrigger.Orientation Microsoft.Maui.Controls.OrientationStateTrigger.Orientation 에서 Xamarin.Forms속성은 OrientationStateTrigger.Orientation 형식 Xamarin.Forms.Internals.DeviceOrientation입니다. .NET MAUI OrientationStateTrigger.Orientation 에서 속성은 형식 DisplayOrientation입니다.
Xamarin.Forms.OSAppTheme Microsoft.Maui.ApplicationModel.AppTheme
Xamarin.Forms.Span.ForegroundColor Microsoft.Maui.Controls.Span.TextColor
Xamarin.Forms.ToolbarItem.Name Microsoft.Maui.Controls.MenuItem.Text Microsoft.Maui.Controls.MenuItem.Text는 에 대한 Microsoft.Maui.Controls.ToolbarItem기본 클래스이므로 ToolbarItem.Name .가 됩니다.ToolbarItem.Text

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

네이티브 양식 변경

네 Xamarin.Forms 이티브 양식은 .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>

Important

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

패키지 참조 추가

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

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

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

변수는 $(MauiVersion) 설치한 .NET MAUI 버전에서 참조됩니다. 각 프로젝트 파일에 빌드 속성을 추가하여 이를 재정의 $(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 합니다. 노드의 <manifest> 자식인 노드를 <uses-sdk /> 수정하여 이 작업을 수행할 수 있습니다.

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

iOS 프로젝트 구성

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

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이 되도록 MinimumOSVersion Info.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 에 리소스가 포함된 경우 새 버전의 파일로 마이그레이션해야 합니다.

또한 아래 코드와 일치하도록 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();
}

참고 항목

프로젝트에 비즈니스 논리 가 App.xaml.cs 포함된 경우 해당 논리를 새 버전의 파일로 마이그레이션해야 합니다.

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

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

앱 진입점

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

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

namespace YOUR_NAMESPACE_HERE;

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

        return builder.Build();
    }
}

참고 항목

UWP 프로젝트의 경우 Xamarin.Forms 참조 builder.UseMauiApp<App>() 는 App MainPage.xaml.cs 파일에서 찾을 수 있습니다.

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

참고 항목

업그레이드 도우미가 설치된 경우 Visual Studio에서 빠른 작업을 사용하여 네임스페이스를 Microsoft.Maui 빠르게 업데이트 Xamarin.Forms 할 수 있습니다.

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과 호환되는지 확인할 수 있습니다.

호환되는 프레임워크 호환되지 않는 프레임워크
net8.0-android, monoandroid, monoandroidXX.X
net8.0-ios monotouch, xamarinios, xamarinios10
net8.0-macos monomac, xamarinmac, xamarinmac20
net8.0-tvos xamarintvos
xamarinwatchos

참고 항목

위에 나열된 호환되지 않는 프레임워크에 대한 종속성이 없는 .NET Standard 라이브러리는 여전히 .NET 8과 호환됩니다.

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

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

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

컴파일 및 문제 해결

종속성이 확인되면 프로젝트를 빌드해야 합니다. 모든 오류는 다음 단계를 안내합니다.

팁

  • 특히 .NET 버전을 변경할 때 Visual Studio에서 프로젝트를 열고 빌드하기 전에 모든 프로젝트에서 모든 bin 및 obj 폴더를 삭제합니다.
  • Android 프로젝트에서 생성된 Resource.designer.cs 파일을 삭제합니다.

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

문제 팁
Xamarin.* 네임스페이스가 없습니다. 네임스페이스를 해당 .NET MAUI로 업데이트합니다. 자세한 내용은 네임스페이스 변경 내용을 참조하세요.
API가 없습니다. API 사용량을 해당 .NET MAUI로 업데이트합니다. 자세한 내용은 API 변경 내용을 참조 하세요.
앱은 배포되지 않습니다. 필요한 플랫폼 프로젝트가 Visual Studio의 Configuration Manager에 배포되도록 설정되어 있는지 확인합니다.
앱이 시작되지 않습니다. 각 플랫폼 프로젝트의 진입점 클래스 및 앱 진입점을 업데이트합니다. 자세한 내용은 마이그레이션된 앱 부트스트랩을 참조하세요.
CollectionView 은 스크롤되지 않습니다. 컨테이너 레이아웃 및 측정된 크기를 확인합니다 CollectionView. 기본적으로 컨트롤은 컨테이너에서 허용하는 만큼의 공간을 차지합니다. 자 Grid 식의 크기를 제한합니다. 그러나 StackLayout 자식은 경계를 넘어 공간을 차지 할 수 있습니다.
iOS의 페이지 아래에 팝업이 표시됩니다. 에서 Xamarin.FormsiOS의 모든 팝업은 UIWindow 인스턴스이지만 .NET MAUI 팝업은 현재 프레젠테이션 ViewController 을 찾고 팝업 PresentViewControllerAsync을 표시하여 표시됩니다. Mopups와 같은 플러그 인에서 팝업이 올바르게 표시되도록 하려면 호출하거나 팝업 내에서 Mopup 사용되는 플러그 인에서 ContentPage 호출 DisplayPromptAsync DisplayAlertDisplayActionSheet해야 합니다.
BoxView 표시되지 않습니다. in Xamarin.Forms 의 BoxView 기본 크기는 40x40입니다. .NET MAUI의 BoxView 기본 크기는 0x0. HeightRequest 40으로 설정합니다WidthRequest.
레이아웃에 안쪽 여백, 여백 또는 간격이 없습니다. .NET MAUI 스타일 리소스를 기반으로 프로젝트에 기본값을 추가합니다. 자세한 내용은 기본값 변경 내용을 참조 하세요 Xamarin.Forms.
사용자 지정 레이아웃이 작동하지 않습니다. .NET MAUI에서 작동하려면 사용자 지정 레이아웃 코드를 업데이트해야 합니다. 자세한 내용은 사용자 지정 레이아웃 변경 내용을 참조 하세요.
사용자 지정 렌더러가 작동하지 않습니다. 렌더러 코드는 .NET MAUI에서 작동하도록 업데이트해야 합니다. 자세한 내용은 .NET MAUI에서 사용자 지정 렌더러 사용을 참조 하세요.
효과가 작동하지 않습니다. .NET MAUI에서 작동하려면 효과 코드를 업데이트해야 합니다. 자세한 내용은 .NET MAUI의 효과 사용을 참조 하세요.
SkiaSharp 코드가 작동하지 않습니다. SkiaSharp 코드는 .NET MAUI에서 작동하려면 사소한 업데이트가 필요합니다. 자세한 내용은 .NET MAUI의 코드 재사용 SkiaSharp 을 참조하세요.
이전에 만든 앱 속성 데이터에 액세스할 수 없습니다. 앱 속성 데이터를 .NET MAUI 기본 설정으로 마이그레이션합니다. 자세한 내용은 앱 속성 사전에서 Xamarin.Forms .NET MAUI 기본 설정으로 데이터 마이그레이션을 참조하세요.
이전에 만든 보안 스토리지 데이터에 액세스할 수 없습니다. 보안 스토리지 데이터를 .NET MAUI로 마이그레이션합니다. 자세한 내용은 보안 스토리지에서 Xamarin.Essentials .NET MAUI 보안 스토리지로 마이그레이션을 참조하세요.
이전에 만든 버전 추적 데이터에 액세스할 수 없습니다. 버전 추적 데이터를 .NET MAUI로 마이그레이션합니다. 자세한 내용은 앱에서 .NET MAUI 앱으로 Xamarin.Forms 버전 추적 데이터 마이그레이션을 참조하세요.

참고 항목