共用方式為

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

  • 發行項

若要將 Xamarin.Forms 應用程式移轉至單一專案 .NET 多平臺應用程式 UI （.NET MAUI） 應用程式，您必須：

  • 更新您的應用程式 Xamarin.Forms 以使用 Xamarin.Forms 5。
  • 將應用程式的相依性更新為最新版本。
  • 確定應用程式仍可運作。
  • 建立 .NET MAUI 應用程式。
  • 將程式代碼和組態從 Xamarin.Forms 應用程式複製到 .NET MAUI 應用程式。
  • 將資源從您的應用程式 Xamarin.Forms 複製到 .NET MAUI 應用程式。
  • 更新命名空間。
  • 解決任何 API 變更。
  • 使用 .NET 8 版本升級或取代不相容的相依性。
  • 編譯及測試您的應用程式。

若要簡化升級程式，您應該建立與應用程式 Xamarin.Forms 同名的新 .NET MAUI 應用程式，然後在程式代碼、組態和資源中複製。 這是以下所述的方法。

更新您的應用程式Xamarin.Forms

將應用程式升級 Xamarin.Forms 至 .NET MAUI 之前，您應該先將應用程式更新 Xamarin.Forms 為使用 Xamarin.Forms 5，並確定它仍能正常執行。 此外，您應該更新應用程式使用至最新版本的相依性。

這有助於簡化移轉程序的其餘部分，因為它會將 與 .NET MAUI 之間的 Xamarin.Forms API 差異降到最低，並確保您在相依性存在時使用 .NET 兼容版本。

建立 .NET MAUI 應用程式

在 Visual Studio 中，使用與您的應用程式 Xamarin.Forms 相同的名稱建立新的 .NET MAUI 應用程式：

在 Visual Studio 中建立 .NET MAUI 應用程式的螢幕快照。

開啟項目檔將會確認您有 .NET SDK 樣式專案。

將程式代碼複製到 .NET MAUI 應用程式

連結 Xamarin.Forms 庫專案的所有跨平臺程式代碼都應該複製到同名資料夾和檔案的 .NET MAUI 應用程式專案中。

自定義轉譯器可以在 .NET MAUI 應用程式中重複使用，或移轉至 .NET MAUI 處理程式。 如需詳細資訊，請參閱 在 .NET MAUI 中重複使用自定義轉譯器，並將 自定義轉譯器移 Xamarin.Forms 轉至 .NET MAUI 處理程式。

效果可以在 .NET MAUI 應用程式中重複使用。 如需詳細資訊，請參閱 重複使用效果。

注意

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

平臺特定程序代碼

.NET MAUI 應用程式專案包含 Platform 資料夾，每個子資料夾都代表 .NET MAUI 可以鎖定的平臺：

平台資料夾螢幕快照。

每個平台的資料夾都包含平臺特定的資源，以及在每個平台上啟動應用程式的程式代碼：

平臺特定的程式代碼螢幕快照。

程式代碼及其包含資料夾，應該從您的 Xamarin.Forms 前端專案複製到下列資料夾：

  • 來自 Xamarin.Forms Android 前端專案的程式代碼應該複製到 .NET MAUI 應用程式專案的 Platform\Android 資料夾。 此外，將和 Xamarin.FormsMainActivity MainApplication 類別的任何自定義程式碼複製到 .NET MAUI 應用程式專案中的相同類別。

  • 來自 iOS Xamarin.Forms 前端專案的程式代碼應該複製到 .NET MAUI 應用程式專案的 Platform\iOS 資料夾。 此外，將 Xamarin.FormsAppDelegate 類別中的任何自定義程式代碼複製到 .NET MAUI 應用程式專案中的相同類別。

    注意

    如需適用於 iOS 之 .NET 的重大變更清單，請參閱 適用於 iOS 的 .NET 重大變更。

  • UWP Xamarin.Forms 前端專案的程式代碼應該複製到 .NET MAUI 應用程式專案的 Platform\Windows 資料夾。 此外，將 Xamarin.FormsApp 類別中的任何自定義程式代碼複製到 .NET MAUI 應用程式專案中的相同類別。

建置時，建置系統只會在針對該特定平台建置時，包含來自每個資料夾的程式碼。 例如，當您為 Android 建置時，平臺\Android 資料夾中的檔案會內建到應用程式套件中，但其他 [平臺] 資料夾中的檔案將不會是 。 此方法會使用多重目標，從單一專案以多個平台為目標。 .NET MAUI 應用程式也可以根據您自己的檔名和資料夾準則進行多重目標設定。 這可讓您建構 .NET MAUI 應用程式專案，讓您不必將平臺程式代碼放入 [平臺] 資料夾的子資料夾中。 如需詳細資訊，請參閱 設定多重目標。

將設定複製到 .NET MAUI 應用程式

每個平台都會使用自己的原生應用程式指令清單檔案來指定應用程式標題、標識碼、版本等資訊。 .NET MAUI 單一專案可讓您在專案檔的單一位置指定此通用應用程式數據。

若要指定專案的共用應用程式指令清單數據，請在 方案總管 中開啟專案的快捷方式功能表，然後選擇 [屬性]。 然後，您可以在 MAUI 共用>一般中指定應用程式標題、識別碼和版本：

.NET MAUI 應用程式指令清單螢幕快照。

在建置階段，共用應用程式指令清單數據會與原生應用程式指令清單檔案中的平臺特定數據合併，以產生應用程式套件的指令清單檔案。 如需詳細資訊，請參閱 .NET MAUI 中的項目組態 - MAUI 共用。

應用程式 Xamarin.Forms 指令清單中的其餘資料應該複製到 .NET MAUI 應用程式指令清單：

  • 在 Android 上，將 Android 前端專案中AndroidManifest.xml檔案的任何其他資料複製到 .NET MAUI 應用程式專案中的平臺\Android\AndroidManifest.xml 檔案。Xamarin.Forms
  • 在 iOS 上，將 iOS 前端專案中 Info.plist 檔案Xamarin.Forms的任何額外數據複製到 .NET MAUI 應用程式專案中的平臺\iOS\Info.plist 檔案。 此外，將 iOS 前端專案中的 Entitlements.plist 檔案Xamarin.Forms複製到 .NET MAUI 應用程式專案中的 Platform\iOS 資料夾。
  • 在 Windows 上，將 UWP 前端專案中 Package.appxmanifest 檔案Xamarin.Forms的其他數據複製到 .NET MAUI 應用程式專案中的平臺\Windows\Package.appxmanifest 檔案。

將資源複製到 .NET MAUI 應用程式

.NET MAUI 單一專案可讓資源檔儲存在單一位置，同時在每個平臺上取用。 這包括字型、影像、應用程式圖示、啟動顯示畫面、原始資產和 CSS 檔案，以設定 .NET MAUI 應用程式的樣式。

資源檔通常應該放在 .NET MAUI 應用程式專案的 Resources 資料夾中，或 Resources 資料夾的子資料夾，而且必須正確設定其建置動作。 下表顯示每個資源檔案類型的建置動作：

資源 建置動作
應用程式圖示 MauiIcon
字型 MauiFont
影像 MauiImage
啟動顯示畫面 MauiSplashScreen
原始資產 MauiAsset
CSS 檔案 MauiCss

注意

XAML 檔案也會儲存在您的 .NET MAUI 應用程式專案中，並會自動指派 MauiXaml 建置動作。 不過，只有 XAML 資源字典通常會放在 應用程式專案的 Resources 資料夾中。

下列螢幕快照顯示一般 Resources 資料夾，其中包含每個資源類型的子資料夾：

影像和字型資源螢幕快照。

如果資源已新增至正確的 Resources 子資料夾，則會正確設定資源檔的建置動作。

重要

平臺特定資源會覆寫其共用資源對應專案。 例如，如果您的 Android 特定映射位於 Platform\Android\Resources\drawable-xhdpi\logo.png，而且您也提供共用 的 Resources\Images\logo.svg 影像，則可調整向量圖形 （SVG） 檔案將用來產生所需的 Android 映射，但已存在平臺特定影像的 XHDPI 映射除外。

應用程式圖示

您的應用程式Xamarin.Forms圖示應該藉由將影像拖曳至專案的 Resources\AppIcon 資料夾，將其建置動作自動設定為 MauiIcon，將您的應用程式圖示新增至 .NET MAUI 應用程式專案。 在建置階段，應用程式圖示會調整為目標平臺和裝置的正確大小。 應用程式圖示的大小會調整為多個解析度，因為它們有多個用途，包括用來代表裝置上的應用程式，以及應用程式市集中的應用程式。

如需詳細資訊，請參閱 將應用程式圖示新增至 .NET MAUI 應用程式專案。

啟動顯示畫面

Xamarin.Forms如果您的 app 有啟動顯示畫面，則應該將影像拖曳至專案的 Resources\Splash 資料夾，將它新增至 .NET MAUI 應用程式專案，其中其建置動作會自動設定為 MauiSplashScreen。 在建置階段，啟動顯示畫面影像的大小會調整為目標平臺和裝置的正確大小。

如需詳細資訊，請參閱 將啟動顯示畫面新增至 .NET MAUI 應用程式專案。

影像

裝置有一系列的螢幕大小和密度，而且每個平臺都有顯示密度相依影像的功能。 在 中 Xamarin.Forms，密度相依映像通常會放在前端專案中，並採用平臺特定的命名慣例。 有兩種方法可用來將這些映射移轉至 .NET MAUI。

建議的方法是將解決方案中每個映射 Xamarin.Forms 的最高解析度版本複製到 .NET MAUI 應用程式專案，方法是將它拖曳至 專案的 Resources\Images 資料夾，其中其建置動作會自動設定為 MauiImage。 也必須設定 BaseSize 每個點陣圖影像的 屬性，以確保重設大小。 這樣就不需要在每個平臺上有多個版本的每個映像。 在建置階段，任何映像都會調整為符合平臺需求的多個密度相依映射。 如需詳細資訊，請參閱 將映像新增至 .NET MAUI 應用程式專案。

或者，您可以將與密度相依的映像從解決方案Xamarin.Forms複製到 .NET MAUI 應用程式專案之 [平臺}] 資料夾中的相同具名資料夾，並將其組建動作設定為解決方案Xamarin.Forms中使用的組建動作。 下表列出解決方案的 Xamarin.Forms 範例影像位置，以及其在 .NET MAUI 應用程式專案中的對等位置：

Xamarin.Forms 影像位置 .NET MAUI 映射位置 .NET MAUI 平臺映射建置動作
{MyApp.Android}\Resources\drawable-xhdpi\image.png Platforms\Android\Resources\drawable-xhdpi\image.png AndroidResource
{MyApp.iOS}\image.jpg *Platforms\iOS\Resources\image.jpg BundleResource
{MyApp.UWP}\Assets\Images\image.gif *Platform\Windows\Assets\Images\image.gif 內容

假設您已採用與解決方案中使用的 Xamarin.Forms 相同映像命名慣例，系統會根據裝置的功能在運行時間選擇適當的映像。 這種方法的缺點是，每個平臺上仍有多個版本的每個映像。

字型

您可以將解決方案中的任何字Xamarin.Forms型拖曳到 .NET MAUI 應用程式專案的 Resources\Fonts 資料夾中，以將其新增至 .NET MAUI 解決方案，其建置動作會自動設定為 MauiFont。

如需詳細資訊，請參閱 字型。

CSS 檔案

您可以將解決方案中的任何 CSS 檔案Xamarin.Forms拖曳至同名資料夾，並將其建置動作設定為 [屬性] 視窗中的 MauiCss，即可新增至 .NET MAUI 方案。

如需在 .NET MAUI 應用程式中使用 CSS 檔案的詳細資訊，請參閱 使用級聯樣式表來設定應用程式樣式。

原始資產

任何原始資產檔案，例如 HTML、JSON 和視訊，都應該從您的 Xamarin.Forms 解決方案複製到 .NET MAUI 應用程式專案，方法是將它們拖曳到 專案的 Resources\Raw 資料夾，其中其建置動作會自動設定為 MauiAsset。

本地化的資源

在 .NET MAUI 應用程式中，字串會使用與 Xamarin.Forms 應用程式中相同的方法進行當地語系化。 因此，您的 .NET 資源檔 （.resx） 應該從您的 Xamarin.Forms 解決方案複製到 .NET MAUI 解決方案中同名的資料夾。 然後，必須指定 .NET MAUI 應用程式的中性語言。 如需詳細資訊，請參閱 指定應用程式的中性語言。

注意

.NET 資源檔不必放在 .NET MAUI 應用程式專案的 Resources 資料夾中。

在 .NET MAUI 應用程式中，影像會使用與 Xamarin.Forms 應用程式中相同的方法進行當地語系化。 因此，您的當地語系化映像及其所在的資料夾應該從您的 Xamarin.Forms 解決方案複製到 .NET MAUI 應用程式專案：

  • 在 Android 上，當地語系化影像之 .NET MAUI 應用程式專案中的根資料夾是 Platform\Android\Resources。
  • 在 iOS 上，當地語系化影像 .NET MAUI 應用程式專案中的根資料夾是 Platform\iOS\Resources。
  • 在 Windows 上，當地語系化映像之 .NET MAUI 應用程式專案中的根資料夾是 Platform\Windows\Assets\Images。

本地化的映像應該將其組建動作設定為解決方案 Xamarin.Forms 中使用的建置動作。 如需詳細資訊，請參閱 本地化映像。

在 .NET MAUI 應用程式中，應用程式名稱會使用與 Xamarin.Forms 應用程式中相同的方法進行當地語系化：

  • 在 Android 上，本地化的應用程式名稱可以使用平臺\Android\Resources 資料夾中的資料夾型命名慣例來儲存。 應用程式名稱當地語系化資料夾和檔案應該從您的 Xamarin.Forms 解決方案複製到此資料夾。
  • 在iOS上，本地化的應用程式名稱會使用平臺\iOS\Resources 資料夾中的資料夾型命名慣例來儲存。 應用程式名稱當地語系化資料夾和檔案應該從您的 Xamarin.Forms 解決方案複製到此資料夾。
  • 在 Windows 上，當地語系化的應用程式名稱會儲存在應用程式套件指令清單中。

如需詳細資訊，請參閱 本地化應用程式名稱。 如需 .NET MAUI 應用程式本地化的詳細資訊，請參閱 當地語系化。

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 中的原生內嵌，並使用不同的初始化方法和不同的擴充方法，將跨平臺控件轉換成其原生類型。 如需詳細資訊，請參閱 原生內嵌。

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 應用程式。