共用方式為

手動將 Xamarin.Forms 應用程式升級至多專案 .NET MAUI 應用程式

  • 發行項

將多專案應用程式升級至多專案 Xamarin.Forms .NET 多平臺應用程式 UI （.NET MAUI） 應用程式，會遵循與 Xamarin.Android 和 Xamarin.iOS 專案相同的步驟，並採取其他步驟來利用 .NET MAUI 中的變更。

本文說明如何將連結 Xamarin.Forms 庫專案手動移轉至 .NET MAUI 連結庫專案。 執行此動作之前，您必須將平台專案更新 Xamarin.Forms 為 SDK 樣式專案。 SDK 樣式專案是所有 .NET 工作負載所使用的相同專案格式，相較於許多 Xamarin 專案，詳細資訊要少得多。 如需更新應用程式專案的相關信息，請參閱將 Xamarin.Android、Xamarin.iOS 和 Xamarin.Mac 專案升級至 .NET、Xamarin.Android 專案移轉、Xamarin Apple 專案移轉，以及 Xamarin.Forms UWP 專案移轉。

若要將連結 Xamarin.Forms 庫專案移轉至 .NET MAUI 連結庫專案，您必須：

  • 更新您的應用程式 Xamarin.Forms 以使用 Xamarin.Forms 5。
  • 將應用程式的相依性更新為最新版本。
  • 確定應用程式仍可運作。
  • 將您的項目檔更新為 SDK 樣式。
  • 更新命名空間。
  • 解決任何 API 變更。
  • 設定 .NET MAUI。
  • 使用 .NET 8 版本升級或取代不相容的相依性。
  • 編譯及測試您的應用程式。

若要簡化升級程式，您應該建立與連結庫專案同名 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>

在您的平台專案中，新增這個新連結庫項目的參考。 然後將您的連結庫檔案複製到 .NET MAUI 連結 Xamarin.Forms 庫專案。

Namespace變更

從 移至 .NET MAUI 的 Xamarin.Forms 命名空間已變更，而且 Xamarin.Essentials 功能現在是 .NET MAUI 的一部分。 若要進行命名空間更新，請針對下列命名空間執行尋找和取代：

Xamarin.Forms 命名空間 .NET MAUI 命名空間（s）
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 指示詞。 這項功能可讓您移除 using 命名空間的 Xamarin.Essentials 指示詞，而不需要將它們取代為對等的 .NET MAUI 命名空間。

此外，預設 XAML 命名空間已從 http://xamarin.com/schemas/2014/forms 中的 Xamarin.Forms 變更為 http://schemas.microsoft.com/dotnet/2021/maui .NET MAUI。 因此，您應該將所有出現的 xmlns="http://xamarin.com/schemas/2014/forms" 專案取代為 xmlns="http://schemas.microsoft.com/dotnet/2021/maui"。

注意

您可以在 Visual Studio 中使用快速動作，快速將命名空間更新Xamarin.Forms為 ，前提是您已安裝 Upgrade Assistant。Microsoft.Maui

API 變更

從 移至 .NET MAUI 時 Xamarin.Forms ，某些 API 已變更。 這是多個原因，包括移除成為 .NET MAUI 一部分所造成的 Xamarin.Essentials 重複功能，並確保 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.Color命名空間中的 Microsoft.Maui.Graphics 類別可讓您使用float值、byte值和int值來建構Color物件。 類別 Microsoft.Maui.Graphics.Colors 也位於 命名空間中 Microsoft.Maui.Graphics ，基本上會提供相同的具名色彩。 例如，使用 Colors.AliceBlue 來指定 AliceBlue 色彩。

下表顯示 結構與 Microsoft.Maui.Graphics.Color 類別之間的 Xamarin.Forms.Color API 變更：

Xamarin.Forms API .NET MAUI API 註解
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 已經過時，未來版本將會移除。

此外，中的所有 Microsoft.Maui.Graphics.Color 數值都是 float，而不是 double 用於 Xamarin.Forms.Color。

注意

不同於 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 只有作為從 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" });

重要

配置 Add 延伸模組方法，例如 GridExtensions.Add，會在版面配置上叫用，而不是配置 Children 集合。

執行升級的 .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 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中 Map ，控件和相關聯的型別位於 命名空間中 Xamarin.Forms.Maps 。 在 .NET MAUI 中，這項功能已移至 Microsoft.Maui.Controls.Maps 和 Microsoft.Maui.Maps 命名空間。 某些屬性已重新命名，某些型別已取代為 來自 Xamarin.Essentials的對等型別。

下表顯示命名空間中 Xamarin.Forms.Maps 功能的 .NET MAUI 取代專案：

Xamarin.Forms API .NET MAUI API 註解
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 命名空間定義。 雖然這不是必要專案，但它可防止和 Polyline 型別之間Polygon發生衝突，這些類型同時存在於 和 Microsoft.Maui.Controls.Shapes 命名空間中Microsoft.Maui.Controls.Maps。 如需詳細資訊，請參閱 顯示地圖。

其他變更

從 移至 .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.FormsApplyQueryAttributes，方法接受 自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.FormsOrientationStateTrigger.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變成 。

此外，在中 Xamarin.Forms，當應用程式經過背景，然後帶到前景時， Page.OnAppearing 會在Android上呼叫覆寫。 不過，在相同案例中，iOS 和 Windows 上不會呼叫此覆寫。 在 .NET MAUI 中，當應用程式經過背景，然後帶到前景時， OnAppearing() 不會在任何平臺上呼叫覆寫。 相反地，您應該接聽 上的生命週期事件 Window ，以在應用程式返回前景時收到通知。 如需詳細資訊，請參閱 .NET MAUI 視窗。

原生表單變更

中的Xamarin.Forms原生表單已變成 .NET MAUI 中的原生內嵌，並使用不同的初始化方法和不同的擴充方法，將跨平臺控件轉換成其原生類型。 如需詳細資訊，請參閱 原生內嵌。

啟動已移轉的應用程式

將應用程式手動更新 Xamarin.Forms 為 .NET MAUI 時，您必須在每個平台專案中啟用 .NET MAUI 支援、更新每個平臺專案的進入點類別，然後設定 .NET MAUI 應用程式的啟動載入。

在平台項目中啟用 .NET MAUI

在更新每個平台項目的進入點類別之前，您必須先啟用 .NET MAUI 支援。 您可以將每個平台專案中的 $(UseMaui) 組建屬性設定為 true ，即可達成此目的：

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

重要

您必須將 新增 <UseMaui>true</UseMaui> 至項目檔，才能啟用 .NET MAUI 支援。 此外，請確定您已將 新增 <EnableDefaultMauiItems>false</EnableDefaultMauiItems> 至 WinUI 項目檔。 這將會停止您收到已定義方法的 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);
        }
    }
}

然後，更新您的指令清單檔案以指定 minSdKVersion 為 21，這是 .NET MAUI 所需的最低 Android SDK 版本。 您可以藉由修改 <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();
    }
}

然後，更新 Info.plist ， MinimumOSVersion 使其為 11.0，這是 .NET MAUI 所需的最低 iOS 版本。

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您應該將該邏輯移轉至新版本的檔案。

然後將launchSettings.json檔案新增至專案的 Properties 資料夾，並將下列 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();
    }
}

注意

針對 Xamarin.Forms UWP專案，App您可以在MainPage.xaml.cs檔案中找到中的參考builder.UseMauiApp<App>()。

如果有需要移轉至 .NET MAUI 的平臺特定服務，請使用 AddTransient(IServiceCollection, Type) 方法，將指定型別的暫時性服務新增至指定的 IServiceCollection。

注意

您可以在 Visual Studio 中使用快速動作，快速將命名空間更新Xamarin.Forms為 ，前提是您已安裝 Upgrade Assistant。Microsoft.Maui

AssemblyInfo 變更

通常設定於AssemblyInfo.cs檔案中的屬性現在可在 SDK 樣式專案中取得。 建議您從 AssemblyInfo.cs 移轉至每個專案中的項目檔，以及移除 AssemblyInfo.cs 檔案。

您可以選擇性地保留 AssemblyInfo.cs 檔案，並將項目檔中的 屬性設定 GenerateAssemblyInfo 為 false：

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

如需屬性的詳細資訊 GenerateAssemblyInfo ，請參閱 GenerateAssemblyInfo。

更新應用程式相依性

一般而言， Xamarin.Forms NuGet 套件與 .NET 8 不相容，除非已使用 .NET 目標 Framework Monikers 重新編譯它們。 不過，Android 應用程式可以使用以 和 monoandroidXX.X 架構為目標的 monoandroid NuGet 套件。

您可以查看 NuGet 上的 [Framework] 索引卷標，確認套件與 .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 連結庫專案。

如果您找不到 .NET 8 兼容版本的 NuGet 套件，您應該：

  • 如果您擁有程式代碼，請使用 .NETTFM 重新編譯套件。
  • 尋找 .NET 8 版本的套件預覽版本。
  • 將相依性取代為 .NET 8 兼容替代方案。

編譯和疑難解答

一旦解析相依性，您應該建置專案。 任何錯誤都會引導您進行後續步驟。

提示

  • 在 Visual Studio 中開啟和建置專案之前，請先刪除所有 專案的 bin 和 obj 資料夾，特別是在變更 .NET 版本時。
  • 從 Android 專案刪除Resource.designer.cs產生的檔案。

下表提供克服常見組建或運行時間問題的指引：

問題 提示
Xamarin.* 命名空間不存在。 將命名空間更新為其 .NET MAUI 對等專案。 如需詳細資訊，請參閱 Namespace變更。
API 不存在。 將 API 使用量更新為其 .NET MAUI 對等專案。 如需詳細資訊，請參閱 API 變更。
應用程式不會部署。 確定必要的平臺項目已設定為在Visual Studio的 Configuration Manager 中部署。
應用程式不會啟動。 更新每個平台項目的進入點類別和應用程式進入點。 如需詳細資訊，請參閱 啟動已移轉的應用程式。
CollectionView 不會捲動。 檢查容器配置和的 CollectionView測量大小。 根據預設，控件會佔用容器所允許的空間。 Grid會限制本身大小的子系。 然而，可 StackLayout 讓子系佔用超出其界限的空間。
彈出視窗會顯示在iOS上的頁面底下。 在 Xamarin.Forms中，iOS 上的所有快顯都是 UIWindow 實例，但在 .NET MAUI 彈出視窗中，則會藉由尋找目前的呈現 ViewController 和顯示彈出視窗來顯示 PresentViewControllerAsync。 在拖把之類的外掛程式中，為了確保您的彈出視窗已正確顯示，您應該從ContentPage快顯內Mopup使用的 呼叫DisplayAlert、 DisplayActionSheet或 DisplayPromptAsync 。
BoxView 未出現。 的預設Xamarin.Forms大小BoxView為 40x40。 .NET MAUI 中的 預設大小 BoxView 為 0x0。 將和 HeightRequest 設定WidthRequest為 40。
配置遺漏邊框間距、邊界或間距。 根據 .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。 如需詳細資訊，請參閱 將版本追蹤資料從 Xamarin.Forms 應用程式遷移至 .NET MAUI 應用程式。

另請參閱