將多專案應用程式升級至多專案 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>
在您的平台專案中，加入對這個新函式庫專案的參考。 然後將您的Xamarin.Forms程式庫檔案複製到 .NET MAUI 程式庫專案中。
命名空間變更
從 移至 .NET MAUI 的 Xamarin.Forms 命名空間已變更，而且 Xamarin.Essentials 功能現在是 .NET MAUI 的一部分。 若要進行命名空間更新，請針對下列命名空間執行尋找和取代：
.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"。
備註
您可以在 Xamarin.Forms，快速將命名空間更新Microsoft.Maui為 ，前提是您已安裝 Upgrade Assistant。
API 變更
Step 2: 從 Xamarin.Forms 移至 .NET MAUI 時，某些 API 已經發生了變化。 這是多個原因，包括移除成為 .NET MAUI 一部分所造成的 Xamarin.Essentials 重複功能，並確保 API 遵循 .NET 命名指導方針。 下列各節將討論這些變更。
色彩變更
在 Xamarin.Forms中Xamarin.Forms.Color，結構可讓您使用Color值來建構double物件，並提供具名色彩，例如 Xamarin.Forms.Color.AliceBlue。 在 .NET MAUI 中，這項功能已分成 Microsoft.Maui.Graphics.Color 類別和 Microsoft.Maui.Graphics.Colors 類別。
Microsoft.Maui.Graphics.Color命名空間中的 Microsoft.Maui.Graphics 類別可讓您使用Color值、float值和byte值來建構int物件。
Microsoft.Maui.Graphics.Colors 類別也位於 Microsoft.Maui.Graphics 命名空間內，大致上提供相同名稱的色彩。 例如，使用 Colors.AliceBlue 來指定 AliceBlue 色彩。
下表顯示 結構與 Xamarin.Forms.Color 類別之間的 Microsoft.Maui.Graphics.Color API 變更：
| Xamarin.Forms 應用程式介面 | .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 應用程式介面 | .NET MAUI API | 評論 |
|---|---|---|
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add |
Add接受三個自變數的多載不存在於 .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 應用程式介面 | .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的對等型別。
下表顯示 .NET MAUI 替代方案，用於在 Xamarin.Forms.Maps 命名空間中的功能：
| Xamarin.Forms 應用程式介面 | .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 命名空間定義。 雖然這不是必須的，但它可防止 Polygon 和 Polyline 型別之間的衝突，這些型別同時存在於 Microsoft.Maui.Controls.Maps 和 Microsoft.Maui.Controls.Shapes 命名空間中。 如需詳細資訊，請參閱 顯示地圖。
其他變更
從Xamarin.Forms移至 .NET MAUI 的過程中，部分其他 API 已被合併。 下表顯示這些變更：
| Xamarin.Forms 應用程式介面 | .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變成 。 |
此外，在 Xamarin.Forms 中，當應用程式在 Android 上進入背景並返回前景時，會呼叫 Page.OnAppearing 覆寫。 不過，在相同情境中，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 應用程式具有單一跨平臺應用程式進入點。 每個平台進入點都會在靜態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();
}
}
備註
針對 Xamarin.Forms UWP 專案，您可以在 App 中找到 builder.UseMauiApp<App>() 檔案中的參考 。
如果有需要移轉至 .NET MAUI 的平臺特定服務，請使用 AddTransient(IServiceCollection, Type) 方法，將指定型別的暫時性服務新增至指定的 IServiceCollection。
備註
您可以在 Xamarin.Forms，快速將命名空間更新Microsoft.Maui為 ，前提是您已安裝 Upgrade Assistant。
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 目標框架標記（TFMs）重新編譯。 不過，Android 應用程式可以使用以 monoandroid 和 monoandroidXX.X 架構為目標的 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 等效版本。 如需詳細資訊，請參閱 命名空間變更。 |
| API 不存在。 | 將 API 使用量更新為其 .NET MAUI 對等專案。 如需詳細資訊，請參閱 API 變更。 |
| 應用程式不會部署。 | 確定必要的平臺項目已設定為在Visual Studio的 Configuration Manager 中部署。 |
| 應用程式不會啟動。 | 更新每個平台項目的進入點類別和應用程式進入點。 如需詳細資訊，請參閱 啟動已移轉的應用程式。 |
| CollectionView 不會捲動。 | 檢查容器的佈局以及CollectionView的測量大小。 根據預設，控件會佔用容器所允許的空間。 Grid會限制本身大小的子系。 然而，StackLayout 能夠讓孩子占用超出它界限的空間。 |
| 彈出視窗會顯示在iOS上的頁面底下。 | 在 Xamarin.Forms中，iOS 上的所有快顯視窗都是 UIWindow 實例，但在 .NET MAUI 中，快顯視窗則是透過尋找目前的呈現 ViewController 並使用 PresentViewControllerAsync 來顯示。 在例如 Mopups 的外掛程式中，為了確保您的彈出視窗正確顯示，您應該呼叫 DisplayAlert（或在 .NET 10+ 中使用 DisplayAlertAsync）、DisplayActionSheet（或在 .NET 10+ 中使用 DisplayActionSheetAsync），或者從 DisplayPromptAsync 彈出視窗中的 ContentPage 呼叫 Mopup。 |
| BoxView 未出現。 |
BoxView中Xamarin.Forms的預設大小為 40x40。 .NET MAUI 中的 預設大小 BoxView 為 0x0。 將和 WidthRequest 設定HeightRequest為 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 應用程式。 |
