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 プロジェクトの移行、XamarinApple プロジェクトの移行、および UWP プロジェクトの移行Xamarin.Formsアップグレードする」を参照してください。

Xamarin.Forms ライブラリ プロジェクトを .NET MAUI ライブラリ プロジェクトに移行するには、次の手順を実行する必要があります。

アップグレード プロセスを簡略化するには、 Xamarin.Forms ライブラリ プロジェクトと同じ名前の新しい .NET MAUI ライブラリ プロジェクトを作成し、コード、構成、およびリソースをコピーする必要があります。 以下に示すアプローチです。

Xamarin.Forms アプリを更新してください

.NET MAUI にあなたの Xamarin.Forms アプリをアップグレードする前に、まず Xamarin.Forms アプリを Xamarin.Forms 5 に更新し、それが正しく動作することを確認してください。 加えて、アプリが使用する依存関係を最新バージョンに更新するべきです。

これにより、Xamarin.Forms と .NET MAUI 間の 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 ライブラリ プロジェクトにコピーします。

名前空間の変更

名前空間はXamarin.Formsから.NET MAUIに移行する過程で変更され、Xamarin.Essentialsの機能は現在.NET MAUIの一部となっています。 名前空間の更新を行うには、以下の名前空間について「検索と置換」を実行してください。

.NET MAUIプロジェクトでは、暗黙のglobal usingディレクティブが使用されます。 この機能により、using 名前空間のディレクティブを削除することができますが、同等の .NET MAUI 名前空間で置き換える必要はありません。

さらに、既定のXAMLネームスペースは、http://xamarin.com/schemas/2014/formsのXamarin.Formsから.NET MAUIのhttp://schemas.microsoft.com/dotnet/2021/mauiに変更されました。 したがって、すべてのxmlns="http://xamarin.com/schemas/2014/forms"をxmlns="http://schemas.microsoft.com/dotnet/2021/maui"に置き換える必要があります。

API の変更

一部のAPIは、Xamarin.Formsから.NET MAUIに移行する際に変更されました。 複数の理由があります。Xamarin.Essentials が .NET MAUI の一部になることで重複機能が削除され、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名前空間にも含まれる Microsoft.Maui.Graphics.Colors クラスは、主に同じ名前付き色を提供します。 例えば、Colors.AliceBlue を使用して AliceBlue 色を指定します。

次の表は、Xamarin.Forms.Color 構造体と Microsoft.Maui.Graphics.Color クラスの間のAPIの変更を示しています。

さらに、Microsoft.Maui.Graphics.Colorで使用されているfloatではなく、すべての数値がdoubleになっています。

レイアウトの変更

次の表は、Xamarin.Forms から .NET MAUI への移行で削除されたレイアウト API を一覧表示しています。

この他に、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" });

アップグレードされた.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 の置換を示しています。

.NET MAUIには2つのMapタイプがあります - Microsoft.Maui.Controls.Maps.MapとMicrosoft.Maui.ApplicationModel.Map. .NET MAUI の Microsoft.Maui.ApplicationModel 名前空間は 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では、アプリがバックグラウンドで実行された後、フォアグラウンドに移動すると、Android で Page.OnAppearing オーバーライドが呼び出されます。 しかし、このオーバーライドは同じシナリオではiOSやWindowsでは呼び出されません。 .NET MAUIでは、アプリがバックグラウンド化されてからフォアグラウンドに戻ったときにOnAppearing()オーバーライドはどのプラットフォームでも呼び出されません。 代わりに、アプリがフォアグラウンドに戻ったときに通知を受け取るために、 Window のライフサイクル イベントをリッスンする必要があります。 詳細については、.NET MAUI windows を参照してください。

ネイティブ形式の変更

ネイティブフォームは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>

パッケージ参照を追加する

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

また、MauiAppCompatActivityから継承するようにMainActivity クラスを更新します。

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 バージョン) であることを指定します。 これは、<manifest> ノードの子である<uses-sdk /> ノードを変更することで実現できます。

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

iOS プロジェクトの構成

.NET MAUI iOS プロジェクトで、MauiUIApplicationDelegateから継承するように AppDelegate クラスを更新します。

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

次に、 launchSettings.json ファイルをプロジェクトの Properties フォルダーに追加し、次の JSON をファイルに追加します。

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

アプリケーションの開始地点

.NET MAUI アプリには、1 つのクロスプラットフォーム アプリ エントリ ポイントがあります。 各プラットフォーム エントリ ポイントは、静的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();
    }
}

.NET MAUI に移行する必要があるプラットフォーム固有のサービスがある場合は、 AddTransient(IServiceCollection, Type) メソッドを使用して、指定した型の一時的なサービスを指定した IServiceCollectionに追加します。

アセンブリ情報の変更

通常、AssemblyInfo.cs ファイルで設定されるプロパティは、現在、SDKスタイルのプロジェクトで使用可能です。 各プロジェクトでAssemblyInfo.csからプロジェクトファイルに移行し、AssemblyInfo.csファイルを削除することをお勧めします。

オプションとして、AssemblyInfo.cs ファイルを保持し、プロジェクトファイルで GenerateAssemblyInfo プロパティを false に設定することができます。

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

GenerateAssemblyInfo プロパティの詳細については、GenerateAssemblyInfo を参照してください。

アプリの依存関係を更新する

一般に、Xamarin.FormsNuGet パッケージは、.NET のターゲット フレームワーク モニカー (TFMs) を使用して再コンパイルされていない限り、.NET 8 と互換性がありません。 ただし、AndroidアプリはmonoandroidおよびmonoandroidXX.XフレームワークをターゲットとしたNuGetパッケージを使用できます。

パッケージが .NET 8 と互換性があることを確認するには、使用しているパッケージの Frameworks タブを NuGet で確認し、次の表に示されている互換性のあるフレームワークのいずれかがリストされていることを確認してください。

上記の互換フレームワークのいずれかと互換性があると示しているNuGetのパッケージがあれば、それに含まれる非互換フレームワークにかかわらず、そのパッケージは互換性があります。 Visual StudioのNuGetパッケージマネージャーを使用して、互換性のあるNuGetパッケージを.NET MAUIライブラリプロジェクトに追加することができます。

.NET 8に対応したNuGetパッケージのバージョンが見つからない場合は、次の手順を実行してください。

• コードの所有者である場合、パッケージを.NET TFMsで再コンパイルしてください。
• パッケージの .NET 8 バージョンのプレビューリリースを探してください。
• 依存関係を .NET 8 と互換性のある代替に置き換えます。

コンパイルとトラブルシューティング

依存関係が解決されたら、プロジェクトをビルドする必要があります。 エラーがある場合は、次のステップに進む手がかりとなります。

以下の表は、一般的なビルドまたはランタイムの問題を解決するためのガイダンスを提供します。

こちらも参照ください

• .NET Framework から .NET への移植
• .NET アップグレード アシスタント