手動將 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 庫專案。
命名空間變更
從 移至 .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"
。
注意
您可以在 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 ,基本上會提供相同的具名色彩。
下表顯示 結構與 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中 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原生表單已變成 .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您應該將該邏輯移轉至新版本的檔案。
然後將 launch 設定.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 對等專案。 如需詳細資訊,請參閱 命名空間變更。 |
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 應用程式。 |
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應