Ruční upgrade Xamarin.Forms aplikace na víceprojektovou aplikaci .NET MAUI

2025-06-16

Upgrade víceprojektové Xamarin.Forms aplikace na víceprojektovou aplikaci .NET Multi-Platform App UI (.NET MAUI) se řídí stejným postupem jako projekt Xamarin.Android a Xamarin.iOS s dalšími kroky pro použití změn v .NET MAUI.

Tento článek popisuje, jak ručně převést projekt knihovny Xamarin.Forms na projekt knihovny .NET MAUI. Než to uděláte, musíte aktualizovat projekty na platformě Xamarin.Forms, aby se staly projekty typu SDK. Projekty ve stylu sady SDK jsou stejný formát projektu používaný všemi úlohami .NET a ve srovnání s mnoha projekty Xamarin jsou mnohem méně podrobné. Informace o aktualizaci projektů aplikací najdete v tématu Upgrade projektů Xamarin.Android, Xamarin.iOS a Xamarin.Mac na projekty .NET, migrace projektů Xamarin.Android, migrace projektů Xamarin Apple a Xamarin.Forms migrace projektů UPW.

Pokud chcete migrovat Xamarin.Forms projekt knihovny do projektu knihovny .NET MAUI, musíte:

Aktualizujte svou Xamarin.Forms aplikaci pro použití Xamarin.Forms 5.
Aktualizujte závislosti aplikace na nejnovější verze.
Ujistěte se, že aplikace stále funguje.
Aktualizujte soubor projektu tak, aby byl ve stylu sady SDK.
Aktualizovat jmenné prostory.
Řešte jakékoliv změny API.
Nakonfigurujte .NET MAUI.
Upgradujte nebo nahraďte nekompatibilní závislosti verzemi .NET 8.
Zkompilujte a otestujte svou aplikaci.

Pro zjednodušení procesu upgradu byste měli vytvořit nový projekt knihovny .NET MAUI se stejným názvem jako Xamarin.Forms projekt knihovny a pak zkopírovat kód, konfiguraci a prostředky. Toto je přístup uvedený níže.

Aktualizujte svou Xamarin.Forms aplikaci

Než upgradujete svou aplikaci Xamarin.Forms na .NET MAUI, měli byste nejprve aktualizovat svou aplikaci Xamarin.Forms tak, aby používala Xamarin.Forms 5 a ujistit se, že stále funguje správně. Kromě toho byste měli aktualizovat závislosti, které vaše aplikace používá, na nejnovější verze.

Toto pomůže zjednodušit zbytek migračního procesu, protože minimalizuje rozdíly v API mezi Xamarin.Forms a .NET MAUI a zajistí, že používáte verze vašich závislostí kompatibilní s .NET, pokud existují.

Vytvoření nového projektu

V sadě Visual Studio vytvořte nový projekt vývojové knihovny tříd .NET MAUI se stejným názvem jako projekt knihovny Xamarin.Forms. Tento projekt bude hostovat kód z Xamarin.Forms projektu knihovny. Otevřením souboru projektu potvrdíte, že máte projekt ve stylu sady .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>

V projektech platformy přidejte odkaz na tento nový projekt knihovny. Následně zkopírujte Xamarin.Forms knihovní soubory do projektu knihovny .NET MAUI.

Změny jmenného prostoru

Jmenné prostory se změnily při přechodu z Xamarin.Forms na .NET MAUI a funkce Xamarin.Essentials jsou nyní součástí .NET MAUI. Pro provedení aktualizací oborů názvů vyhledejte a nahraďte následující obory názvů:

Xamarin.Forms jmenný prostor	Jmenné prostory .NET MAUI
`Xamarin.Forms`	Microsoft.Maui a Microsoft.Maui.Controls
`Xamarin.Forms.DualScreen`	Microsoft.Maui.Controls.Foldable
`Xamarin.Forms.Maps`	Microsoft.Maui.Controls.Maps a 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

Projekty .NET MAUI využívají implicitní global using direktivy. Tato funkce vám umožňuje odstranit using direktivy pro obor Xamarin.Essentials názvů, aniž byste je museli nahrazovat ekvivalentními obory názvů .NET MAUI.

Kromě toho výchozí obor názvů XAML se změnil z http://xamarin.com/schemas/2014/forms v Xamarin.Forms na http://schemas.microsoft.com/dotnet/2021/maui v .NET MAUI. Proto byste měli nahradit všechny výskyty xmlns="http://xamarin.com/schemas/2014/forms" za xmlns="http://schemas.microsoft.com/dotnet/2021/maui".

Poznámka:

Můžete rychle aktualizovat své Xamarin.Forms oborové názvy na Microsoft.Maui pomocí rychlých akcí ve Visual Studio, pokud máte nainstalovaný Upgrade Assistant.

Změny rozhraní API

Některá rozhraní API byla změněna při přechodu z Xamarin.Forms na .NET MAUI. Toto zahrnuje několik důvodů, včetně odstranění duplicitní funkčnosti způsobené tím, že se Xamarin.Essentials stává součástí .NET MAUI, a zajištění, že API budou dodržovat pokyny pro pojmenování v .NET. Následující sekce pojednávají o těchto změnách.

Změny barev

Ve Xamarin.Forms struktura Xamarin.Forms.Color umožňuje konstruovat objekty Color pomocí hodnot double, a poskytuje pojmenované barvy, jako je například Xamarin.Forms.Color.AliceBlue. V .NET MAUI byla tato funkčnost rozdělena na třídu Microsoft.Maui.Graphics.Color a třídu Microsoft.Maui.Graphics.Colors.

Třída Microsoft.Maui.Graphics.Color v názvovém prostoru Microsoft.Maui.Graphics vám umožňuje vytvářet objekty Color pomocí hodnot float, hodnot byte a hodnot int. Třída Microsoft.Maui.Graphics.Colors, která se také nachází v oboru názvů Microsoft.Maui.Graphics, převážně poskytuje stejné pojmenované barvy. Například použijte Colors.AliceBlue k určení AliceBlue barvy.

Následující tabulka zobrazuje změny v API mezi strukturou Xamarin.Forms.Color a třídou Microsoft.Maui.Graphics.Color.

Xamarin.Forms Rozhraní api	Rozhraní .NET MAUI API	Komentář
`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 vlastnost nahrazena metodou v .NET MAUI.
`Xamarin.Forms.Color.Saturation`	Microsoft.Maui.Graphics.Color.GetSaturation	Xamarin.Forms vlastnost nahrazena metodou v .NET MAUI.
`Xamarin.Forms.Color.Luminosity`	Microsoft.Maui.Graphics.Color.GetLuminosity	Xamarin.Forms vlastnost nahrazena metodou v .NET MAUI.
`Xamarin.Forms.Color.Default`		Neexistuje žádný ekvivalent .NET MAUI. Místo toho Microsoft.Maui.Graphics.Color objekty výchozí `null`.
`Xamarin.Forms.Color.Accent`		Neexistuje žádný ekvivalent .NET MAUI.
`Xamarin.Forms.Color.FromHex`	Microsoft.Maui.Graphics.Color.FromArgb	Microsoft.Maui.Graphics.Color.FromHex je zastaralý a bude odstraněn v budoucím vydání.

Kromě toho jsou všechny číselné hodnoty v Microsoft.Maui.Graphics.Colorfloat místo double používaných v Xamarin.Forms.Color.

Poznámka:

Na rozdíl od Xamarin.Forms, Microsoft.Maui.Graphics.Color nemá implicitní konverzi na System.Drawing.Color.

Změny rozvržení

Následující tabulka uvádí rozvržení API, které byly odstraněny při přechodu z Xamarin.Forms na .NET MAUI:

Xamarin.Forms Rozhraní api	Rozhraní .NET MAUI API	Komentáře
`Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add`		Přetížení `Add` , které přijímá tři argumenty, není v .NET MAUI.
`Xamarin.Forms.Grid.IGridList<T>.AddHorizontal`		Neexistuje žádný ekvivalent .NET MAUI.
`Xamarin.Forms.Grid.IGridList<T>.AddVertical`		Neexistuje žádný ekvivalent .NET MAUI.
`Xamarin.Forms.RelativeLayout`	Microsoft.Maui.Controls.Compatibility.RelativeLayout	V .NET MAUI existuje `RelativeLayout` pouze jako kompatibilitní prvek pro uživatele přecházející z Xamarin.Forms. Použijte Grid místo toho nebo přidejte `xmlns` pro kompatibilitu jmenného prostoru.

K přidání dětí do rozložení v kódu v Xamarin.Forms dochází jejich vložením do kolekce rozložení Children.

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

V .NET MAUI je kolekce Children určena pro interní použití .NET MAUI a neměla by být přímo upravována. V kódu by proto měly být děti přidány přímo do rozvržení.

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

Důležité

Jakékoli rozšířené metody uspořádání Add, jako je GridExtensions.Add, jsou vyvolány na rozložení spíše než na kolekci uspořádání Children.

Můžete si všimnout, že při spuštění vaší vylepšené aplikace .NET MAUI se chování rozložení liší. Pro více informací viz Změny chování rozložení z Xamarin.Forms.

Změny vlastního rozložení

Proces vytváření vlastního rozložení v Xamarin.Forms zahrnuje vytvoření třídy, která je odvozena z Layout<View> a přepsání metod VisualElement.OnMeasure a Layout.LayoutChildren. Další informace naleznete v Vytvoření vlastního rozložení v Xamarin.Forms.

V .NET MAUI se třídy rozložení odvozují z abstraktní třídy Layout. Tato třída deleguje křížovou platformu rozvržení a měření na třídu správce rozvržení. Každá třída správce rozložení implementuje rozhraní ILayoutManager, které určuje, že je nutné poskytnout implementace Measure a ArrangeChildren.

Implementace Measure volá IView.Measure na každý pohled v rozvržení a vrací celkovou velikost rozvržení s ohledem na omezení.
Implementace ArrangeChildren určuje, kde by měl být každý náhled umístěn v rámci rozložení, a volá Arrange na každém náhledu s jeho příslušnými hranicemi. Návratová hodnota je skutečná velikost rozvržení.

Pro více informací se podívejte na vlastní rozvržení.

Změny zařízení

Xamarin.Forms má třídu Xamarin.Forms.Device, která vám pomáhá komunikovat se zařízením a platformou, na které aplikace běží. Třída ekvivalentní v .NET MAUI, Microsoft.Maui.Controls.Device, je zastaralá a její funkčnost je nahrazena několika typy.

Následující tabulka ukazuje náhrady .NET MAUI pro funkce ve třídě Xamarin.Forms.Device.

Xamarin.Forms Rozhraní api	Rozhraní .NET MAUI API	Komentáře
`Xamarin.Forms.Device.Android`	Microsoft.Maui.Devices.DevicePlatform.Android
`Xamarin.Forms.Device.iOS`	Microsoft.Maui.Devices.DevicePlatform.iOS
`Xamarin.Forms.Device.GTK`		Neexistuje žádný ekvivalent .NET MAUI.
`Xamarin.Forms.Device.macOS`		Neexistuje žádný ekvivalent .NET MAUI. Místo toho použijte 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`		Neexistuje žádný ekvivalent .NET MAUI.
`Xamarin.Forms.Device.Flags`		Neexistuje žádný ekvivalent .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`		Neexistuje žádný ekvivalent .NET MAUI.
`Xamarin.Forms.Device.GetNamedSize`		Neexistuje žádný ekvivalent .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`		Neexistuje žádný ekvivalent .NET MAUI.
`Xamarin.Forms.Device.SetFlowDirection`	Microsoft.Maui.Controls.Window.FlowDirection
`Xamarin.Forms.Device.StartTimer`	Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer nebo Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed

Změny mapy

V Xamarin.Forms jsou řízení Map a související typy v jmenném prostoru Xamarin.Forms.Maps. V .NET MAUI se tato funkce přesunula do jmenných prostorů Microsoft.Maui.Controls.Maps a Microsoft.Maui.Maps. Některé vlastnosti byly přejmenovány a některé typy byly nahrazeny ekvivalentními typy z Xamarin.Essentials.

Následující tabulka ukazuje náhrady .NET MAUI pro funkce v oboru názvů Xamarin.Forms.Maps:

Xamarin.Forms Rozhraní api	Rozhraní .NET MAUI API	Komentář
`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`		Neexistuje žádný ekvivalent .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	Členové typu `Xamarin.Forms.Maps.Position` se změnili na typ Microsoft.Maui.Devices.Sensors.Location.
`Xamarin.Forms.Maps.Geocoder`	Microsoft.Maui.Devices.Sensors.Geocoding	Členové typu `Xamarin.Forms.Maps.Geocoder` se změnili na typ Microsoft.Maui.Devices.Sensors.Geocoding.

.NET MAUI má dva Map typy - Microsoft.Maui.Controls.Maps.Map a Microsoft.Maui.ApplicationModel.Map. Vzhledem k tomu, že Microsoft.Maui.ApplicationModel prostor názvů je jednou z direktiv .NET MAUI global using, při použití ovládacího prvku Microsoft.Maui.Controls.Maps.Map z kódu budete muset zcela zpřesnit své použití Map nebo použít alias using.

V XAML by měla být přidána definice oboru názvů xmlns pro ovládací prvek Map. I když to není vyžadováno, zabrání se tím kolizi mezi typy Polygon a Polyline, které existují v obou jmenných prostorech Microsoft.Maui.Controls.Maps a Microsoft.Maui.Controls.Shapes. Pro více informací si přečtěte Display a map.

Další změny

Malý počet dalších API byl konsolidován při přechodu z Xamarin.Forms na .NET MAUI. Následující tabulka ukazuje tyto změny:

Xamarin.Forms Rozhraní api	Rozhraní .NET MAUI API	Komentáře
`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	V Xamarin.Forms metoda `ApplyQueryAttributes` přijímá argument `IDictionary<string, string>`. V .NET MAUI metoda `ApplyQueryAttributes` přijímá argument `IDictionary<string, object>`.
`Xamarin.Forms.MenuItem.Icon`	Microsoft.Maui.Controls.MenuItem.IconImageSource	`Xamarin.Forms.MenuItem.Icon` je základní třída pro `Xamarin.Forms.ToolbarItem`, a proto se `ToolbarItem.Icon` stává `ToolbarItem.IconImageSource`.
`Xamarin.Forms.OrientationStateTrigger.Orientation`	Microsoft.Maui.Controls.OrientationStateTrigger.Orientation	Ve Xamarin.Forms je vlastnost `OrientationStateTrigger.Orientation` typu `Xamarin.Forms.Internals.DeviceOrientation`. V .NET MAUI je vlastnost `OrientationStateTrigger.Orientation` typu 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 je základní třída pro Microsoft.Maui.Controls.ToolbarItem, a proto se `ToolbarItem.Name` stává `ToolbarItem.Text`.

Kromě toho, v Xamarin.Forms, je předání řízení Page.OnAppearing vyvoláno na Androidu, když se aplikace přesune na pozadí a poté se vrátí na popředí. Nicméně tento přepsání není na iOS a Windows ve stejném scénáři voláno. V .NET MAUI se přepis OnAppearing() nevolá na žádné platformě, když je aplikace převedena na pozadí a poté opět přivedena do popředí. Místo toho byste měli sledovat události životního cyklu na Window, abyste byli upozorněni, když se aplikace vrátí na popředí. Další informace naleznete v .NET MAUI windows.

Změny nativních formulářů

Native forms v Xamarin.Forms se staly nativním vložením do .NET MAUI a používají jiný přístup k inicializaci a různé rozšiřovací metody k převodu multiplatformních ovládacích prvků na jejich nativní typy. Pro více informací se podívejte na Native embedding.

Inicializace migrované aplikace

Při ruční aktualizaci Xamarin.Forms aplikace na .NET MAUI budete muset povolit podporu .NET MAUI v každém projektu platformy, aktualizovat třídu vstupního bodu každého projektu platformy a pak nakonfigurovat spuštění aplikace .NET MAUI.

Povolení .NET MAUI v projektech platformy

Než aktualizujete třídu vstupního bodu každého projektu platformy, musíte nejprve povolit podporu .NET MAUI. Toho lze dosáhnout nastavením $(UseMaui) vlastnosti sestavení na true v každém projektu platformy:

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

Důležité

Pokud chcete povolit podporu .NET MAUI, musíte ho přidat <UseMaui>true</UseMaui> do souboru projektu. Kromě toho se ujistěte, že jste přidali <EnableDefaultMauiItems>false</EnableDefaultMauiItems> do souboru projektu WinUI. Tím přestanete dostávat chyby sestavení týkající se InitializeComponent již definované metody.

Přidání odkazů na balíčky

V .NET 8 se .NET MAUI dodává jako úloha .NET a několik balíčků NuGet. Výhodou tohoto přístupu je, že umožňuje snadno připnout projekty na konkrétní verze a zároveň vám umožní snadno zobrazit náhled nerelevidovaných nebo experimentálních buildů.

Do každého souboru projektu byste měli přidat následující explicitní odkazy na <ItemGroup> balíčky:

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

Na $(MauiVersion) proměnnou odkazuje verze rozhraní .NET MAUI, kterou jste nainstalovali. Můžete to změnit přidáním vlastnosti sestavení $(MauiVersion) do každého souboru projektu.

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

Konfigurace projektu Androidu

V projektu .NET MAUI pro Android aktualizujte třídu MainApplication, aby odpovídala následujícímu kódu:

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();
    }
}

Také aktualizujte třídu MainActivity tak, aby dědila z 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);
        }
    }
}

Potom aktualizujte soubor manifestu tak, aby určil, že minSdKVersion je 21, což je minimální verze sady Android SDK vyžadovaná rozhraním .NET MAUI. Toho lze dosáhnout úpravou <uses-sdk /> uzlu, což je podřízená položka <manifest> uzlu:

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

Konfigurace projektu pro iOS

V projektu .NET MAUI pro iOS upravte třídu AppDelegate, aby dědila z 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();
    }
}

Pak aktualizujte Info.plist tak, aby MinimumOSVersion byl 11.0, což je minimální verze iOS vyžadovaná rozhraním .NET MAUI.

Konfigurace projektu UPW

V projektu .NET MAUI WinUI 3 aktualizujte App.xaml tak, aby odpovídal následujícímu kódu:

<?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>

Poznámka:

Pokud váš projekt obsahoval prostředky ve stávajícím souboru App.xaml , měli byste je migrovat do nové verze souboru.

Aktualizujte také App.xaml.cs tak, aby odpovídaly následujícímu kódu:

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();
}

Poznámka:

Pokud váš projekt zahrnul obchodní logiku do App.xaml.cs měli byste tuto logiku migrovat do nové verze souboru.

Potom do složky Vlastnosti projektu přidejte soubor launchSettings.json a do souboru přidejte následující JSON:

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

Vstupní bod aplikace

.NET MAUI aplikace mají jediný multiplatformní vstupní bod aplikace. Každý vstupní bod platformy volá metodu CreateMauiAppMauiProgram statické třídy a vrátí hodnotu MauiApp.

Proto přidejte novou třídu s názvem MauiProgram , která obsahuje následující kód:

namespace YOUR_NAMESPACE_HERE;

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

        return builder.Build();
    }
}

Poznámka:

Pro Xamarin.Forms projekty App UWP najdete odkaz v builder.UseMauiApp<App>() souboru MainPage.xaml.cs.

Pokud existují služby specifické pro platformu, které je třeba migrovat do .NET MAUI, použijte metodu AddTransient(IServiceCollection, Type) k přidání přechodné služby zadaného typu do zadaného IServiceCollection.

Poznámka:

Můžete rychle aktualizovat své Xamarin.Forms oborové názvy na Microsoft.Maui pomocí rychlých akcí ve Visual Studio, pokud máte nainstalovaný Upgrade Assistant.

Změny v AssemblyInfo

Vlastnosti, které jsou obvykle nastaveny v souboru AssemblyInfo.cs, jsou nyní dostupné ve vašem projektu stylu SDK. Doporučujeme je přesunout z AssemblyInfo.cs do souboru projektu v každém projektu a následně odstranit soubor AssemblyInfo.cs.

Volitelně můžete ponechat soubor AssemblyInfo.cs a nastavit vlastnost GenerateAssemblyInfo ve vašem projektovém souboru na false.

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

Pro více informací o vlastnosti GenerateAssemblyInfo, podívejte se na GenerateAssemblyInfo.

Aktualizujte závislosti aplikace

Obecně platí, že Xamarin.Forms balíčky NuGet nejsou kompatibilní s .NET 8, pokud nebyly znovu zkompilovány pomocí .NET cílového rámce označení (TFM). Android aplikace však mohou používat balíčky NuGet cílené na rámce monoandroid a monoandroidXX.X.

Můžete potvrdit, že balíček je kompatibilní s .NET 8, když se podíváte na kartu Frameworks na NuGet pro balíček, který používáte, a zkontrolujete, zda obsahuje některý z kompatibilních frameworků uvedených v následující tabulce:

Kompatibilní rámce	Nepodporované frameworky
net8.0-android, monoandroid, monoandroidXX.X
net8.0-ios	monotouch, xamarinios, xamarinios10
net8.0-macos	monomac, xamarinmac, xamarinmac20
net8.0-tvos	xamarintvos
	xamarinwatchos

Poznámka:

Knihovny .NET Standard, které nemají závislosti na nekompatibilních rámcích uvedených výše, jsou stále kompatibilní s .NET 8.

Pokud balíček na NuGet naznačuje kompatibilitu s některým z výše uvedených kompatibilních rámců, bez ohledu na to, zda také obsahuje nekompatibilní rámce, pak je balíček kompatibilní. Kompatibilní balíčky NuGet lze přidat do vašeho knihovního projektu .NET MAUI pomocí správce balíčků NuGet v programu Visual Studio.

Pokud nemůžete najít verzi balíčku NuGet kompatibilní s .NET 8, měli byste:

Překompilujte balíček s .NET TFMs, pokud vlastníte kód.
Hledejte ukázkovou verzi balíčku .NET 8.
Nahraďte závislost alternativou kompatibilní s .NET 8.

Kompilovat a odstraňovat problémy

Jakmile jsou vyřešeny vaše závislosti, měli byste sestavit svůj projekt. Jakékoli chyby vás nasměrují k dalším krokům.

Návod

Před otevřením a sestavováním projektů v sadě Visual Studio odstraňte všechny složky bin a obj , zejména při změně verzí .NET.
Odstraňte automaticky generovaný soubor Resource.designer.cs z Android projektu.

Následující tabulka poskytuje návod pro překonání běžných problémů s kompilací nebo běhovými problémy.

Problém	Návod
`Xamarin.*` jmenný prostor neexistuje.	Aktualizujte obor názvů na jeho ekvivalent pro .NET MAUI. Pro více informací se podívejte na Změny názvového prostoru.
Rozhraní API neexistuje.	Aktualizujte použití API na jeho ekvivalent v .NET MAUI. Pro více informací se podívejte na změny API.
Aplikace se nenasadí.	Zajistěte, aby byl požadovaný projekt platformy nastaven k nasazení ve Správci konfigurace Visual Studio.
Aplikace se nespustí.	Aktualizujte třídu vstupního bodu každého platformního projektu a vstupní bod aplikace. Pro více informací viz Bootstrap vaší migrované aplikace.
CollectionView se neposouvá.	Zkontrolujte rozložení kontejneru a naměřenou velikost CollectionView. Ve výchozím nastavení bude ovládací prvek zabírat tolik místa, kolik kontejner umožňuje. Prvek Grid omezuje své děti na vlastní velikost. Navíc StackLayout umožňuje dětem zabírat místo i mimo jeho hranice.
Vyskakovací okno se zobrazuje pod stránkou na iOS.	V Xamarin.Forms jsou všechny vyskakovací okna na iOS instance `UIWindow`, ale v .NET MAUI jsou vyskakovací okna zobrazena nalezením aktuálního prezentujícího `ViewController` a zobrazením vyskakovacího okna pomocí `PresentViewControllerAsync`. V pluginech, jako je Mopups, abyste zajistili správné zobrazení vašich vyskakovacích oken, měli byste zavolat DisplayAlert (nebo DisplayAlertAsync ve verzi .NET 10+), DisplayActionSheet (nebo DisplayActionSheetAsync ve verzi .NET 10+), nebo DisplayPromptAsync z ContentPage, který se používá uvnitř `Mopup` vyskakovacího okna.
BoxView se nezobrazuje.	Výchozí velikost BoxView v Xamarin.Forms je 40x40. Výchozí velikost BoxView v .NET MAUI je 0x0. Nastavte `WidthRequest` a `HeightRequest` na 40.
Rozvržení postrádá odsazení, okraje nebo mezery.	Přidejte výchozí hodnoty do svého projektu na základě stylového zdroje .NET MAUI. Pro více informací se podívejte na Výchozí změny hodnot z Xamarin.Forms.
Vlastní rozvržení nefunguje.	Kód vlastního rozvržení je třeba aktualizovat, aby fungoval v .NET MAUI. Pro více informací viz Úpravy vlastního rozložení.
Vlastní vykreslovač nefunguje.	Kód rendereru potřebuje aktualizaci, aby pracoval s .NET MAUI. Pro více informací viz Use custom renderers in .NET MAUI.
Efekt nefunguje.	Kód efektu je nutné aktualizovat, aby fungoval v .NET MAUI. Pro více informací viz Použití efektů v .NET MAUI.
SkiaSharp kód nefunguje.	SkiaSharp kód potřebuje drobné úpravy, aby fungoval v .NET MAUI. Pro více informací si prohlédněte Reuse SkiaSharp code in .NET MAUI.
Nelze získat přístup k dříve vytvořeným údajům o vlastnostech aplikace.	Migrujte data vlastností aplikace do preferencí .NET MAUI. Pro více informací se podívejte na Přesuňte data ze slovníku vlastností aplikace Xamarin.Forms do preferencí .NET MAUI.
Nelze získat přístup k dříve vytvořeným datům v zabezpečeném úložišti.	Přesuňte data bezpečného úložiště do .NET MAUI. Pro více informací se podívejte na Migrujte ze Xamarin.Essentials zabezpečeného úložiště na zabezpečené úložiště .NET MAUI.
Nelze získat přístup k dříve vytvořeným datům pro sledování verzí.	Přeneste data sledování verzí do .NET MAUI. Pro více informací si přečtěte Jak migrovat data o sledování verzí z aplikace Xamarin.Forms do aplikace .NET MAUI.

Sdílet prostřednictvím

Ruční upgrade Xamarin.Forms aplikace na víceprojektovou aplikaci .NET MAUI

Aktualizujte svou Xamarin.Forms aplikaci

Vytvoření nového projektu

Změny jmenného prostoru

Změny rozhraní API

Změny barev

Změny rozvržení

Změny vlastního rozložení

Změny zařízení

Změny mapy

Další změny

Změny nativních formulářů

Inicializace migrované aplikace

Povolení .NET MAUI v projektech platformy

Přidání odkazů na balíčky

Konfigurace projektu Androidu

Konfigurace projektu pro iOS

Konfigurace projektu UPW

Vstupní bod aplikace

Změny v AssemblyInfo

Aktualizujte závislosti aplikace

Kompilovat a odstraňovat problémy

Viz také

Váš názor

Další materiály