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 5 を使用するように Xamarin.Forms アプリを更新します。
  • アプリの依存関係を最新バージョンに更新します。
  • アプリが引き続き動作することを確認します。
  • プロジェクト ファイルを SDK スタイルに更新します。
  • 名前空間を更新します。
  • API の変更に対処します。
  • .NET MAUI を構成します。
  • 互換性のない依存関係を .NET 8 バージョンにアップグレードするか、または置き換えます。
  • アプリをコンパイルしてテストします。

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

Xamarin.Forms アプリを更新する

Xamarin.Forms アプリを .NET MAUI にアップグレードする前に、最初に Xamarin.Forms 5 を使用するように Xamarin.Forms アプリを更新し、引き続き正常に実行されるようにする必要があります。 さらに、アプリが使用する依存関係を最新バージョンに更新する必要があります。

これにより、移行プロセスの残りの部分が簡略化されます。これにより、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 の一部になりました。 名前空間を更新するには、次の名前空間の検索と置換を実行します。

Xamarin.Forms 名前空間 .NET MAUI 名前空間
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 ディレクティブを使用します。 この機能を使用すると、Xamarin.Essentials 名前空間の using ディレクティブを、同等の .NET MAUI 名前空間に置き換えることなく削除できます。

さらに、既定の XAML 名前空間が、Xamarin.Forms の http://xamarin.com/schemas/2014/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" に置き換える必要があります。

Note

アップグレード アシスタントがインストールされていれば、Visual Studio のクイック アクションを使用して、Xamarin.Forms 名前空間を Microsoft.Maui にすばやく更新できます。

API の変更

Xamarin.Forms から .NET MAUI への移行に伴い、一部の API が変更されました。 これには、Xamarin.Essentials が .NET MAUI の一部となることによって発生する重複した機能を削除や、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 名前空間の Microsoft.Maui.Graphics.Color クラスを使用すると、float 値、byte 値、int 値を使用して Color オブジェクトを構築できます。 Microsoft.Maui.Graphics 名前空間にもある Microsoft.Maui.Graphics.Colors クラスは、主に同じ名前の色を提供します。

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

Xamarin.Forms API .NET MAUI App コメント
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 内のすべての数値は、Xamarin.Forms.Color で使用される double ではなく、float です。

Note

Xamarin.Forms とは異なり、Microsoft.Maui.Graphics.Color には System.Drawing.Color への暗黙的な変換はありません。

レイアウトの変更

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

Xamarin.Forms API .NET MAUI App Comments
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>Add 3 つの引数を受け取る Add オーバーロードは、.NET MAUI には存在しません。
Xamarin.Forms.Grid.IGridList<T>.Add 5 つの引数を受け取る 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 API .NET MAUI App Comments
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add 3 つの引数を受け取る 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" });

重要

GridExtensions.Add などの 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 App Comments
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 App コメント
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 には、Microsoft.Maui.Controls.Maps.Map と Microsoft.Maui.ApplicationModel.Map の 2 つの Map 型があります。 Microsoft.Maui.ApplicationModel 名前空間は .NET MAUI の global using ディレクティブの 1 つなので、コードで Microsoft.Maui.Controls.Maps.Map コントロールを使用する場合は、Map を完全修飾して使用するか、エイリアス使用を使用する必要があります。

XAML では、xmlns 名前空間定義を Map コントロールに追加する必要があります。 これは必須ではありませんが、Microsoft.Maui.Controls.Maps 名前空間と Microsoft.Maui.Controls.Shapes 名前空間の両方に存在する Polygon 型と Polyline 型の競合を防ぐことができます。 詳細については、「マップを表示する」をご覧ください。

その他の変更

Xamarin.Forms から .NET MAUI への移行で、その他の少数の API が統合されました。 これらの変更を次の表に示します。

Xamarin.Forms API .NET MAUI App コメント
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 の ネイティブ フォームは .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 MAUI サポートを有効にするには、プロジェクト ファイルに <UseMaui>true</UseMaui> を追加する必要があります。 さらに、WinUI プロジェクト ファイルに <EnableDefaultMauiItems>false</EnableDefaultMauiItems> が追加されていることを確認します。 これにより、既に定義されている 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();
    }
}

また、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();
    }
}

次に、MinimumOSVersion が 11.0 (NET MAUI に必要な最小の iOS バージョン) になるように Info.plist を更新します。

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>

Note

プロジェクトで既存の 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();
}

Note

プロジェクトで App.xaml.cs にビジネス ロジックが含まれている場合、ファイルの新しいバージョンにそのロジックを移行する必要があります。

次に、プロジェクトの Properties フォルダーに launchSettings.json ファイルを追加し、次の 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();
    }
}

Note

Xamarin.Forms UWP プロジェクトの場合、builder.UseMauiApp<App>() の App 参照は、MainPage.xaml.cs ファイルにあります。

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

Note

アップグレード アシスタントがインストールされていれば、Visual Studio のクイック アクションを使用して、Xamarin.Forms 名前空間を 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 ターゲット フレームワーク モニカー (TFM) を使用して再コンパイルされていない限り、.NET 8 と互換性がありません。 ただし、Android アプリでは、monoandroid フレームワークと monoandroidXX.X フレームワークを対象とする NuGet パッケージを使用できます。

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

互換性のあるフレームワーク 互換性のないフレームワーク
net8.0-android、monoandroid、monoandroidXX.X
net8.0-ios monotouch、xamarinios、xamarinios10
net8.0-macos monomac、xamarinmac、xamarinmac20
net8.0-tvos xamarintvos
xamarinwatchos

Note

上記の互換性のないフレームワークに依存していない .NET Standard ライブラリは、引き続き .NET 8 と互換性があります。

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

NuGet パッケージの .NET 8 互換バージョンが見つからない場合は、次の手順を実行する必要があります。

  • コードを所有している場合は、.NET TFM を使用してパッケージを再コンパイルします。
  • .NET 8 バージョンのパッケージのプレビュー リリースを探します。
  • 依存関係を .NET 8 互換の代替手段に置き換えます。

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

依存関係が解決されたら、プロジェクトをビルドする必要があります。 エラーがあれば、次の手順に進みます。

ヒント

  • 特に .NET バージョンを変更する場合は、Visual Studio でプロジェクトを開いてビルドする前に、すべてのプロジェクトからすべての bin フォルダーと obj フォルダーを削除してください。
  • Android プロジェクトから Resource.designer.cs で生成されたファイルを削除します。

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

問題点 ヒント
Xamarin.* 名前空間が存在しません。 名前空間を同等の .NET MAUI に更新します。 詳細については、「名前空間の変更」をご覧ください。
API は、存在しません。 API の使用状況を、同等の .NET MAUI に更新します。 詳細については、「APIの変更」をご覧ください。
アプリはデプロイされません。 Visual Studio の構成マネージャーにデプロイするために必要なプラットフォーム プロジェクトが設定されていることを確認します。
アプリは起動しません。 各プラットフォーム プロジェクトのエントリ ポイント クラスとアプリ エントリ ポイントを更新します。 詳細については、「移行されたアプリをブートストラップする」をご覧ください。
CollectionView はスクロールしません。 コンテナーのレイアウトと CollectionView の測定されたサイズを確認します。 既定では、コントロールはコンテナーが許可する限り多くの領域を占有します。 Grid は、独自のサイズに子を制限します。 ただし、StackLayout を使用すると、子がその境界を超えて領域を占有できます。
iOS のページの下にポップアップが表示されます。 Xamarin.Forms では、iOS 上のすべてのポップアップは UIWindow インスタンスですが、.NET MAUI でポップアップを表示するには、現在の ViewController を見つけて PresentViewControllerAsync でポップアップを表示します。 Mopups などのプラグインでは、ポップアップが正しく表示されるようにするには、Mopup ポップアップ内で使用されている ContentPage から DisplayAlert、DisplayActionSheet、または DisplayPromptAsync を呼び出す必要があります。
BoxView が表示されません。 Xamarin.Forms の BoxView の既定のサイズは 40 x 40 です。 .NET MAUI の BoxView の既定のサイズは 0 x 0 です。 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 アプリにバージョン追跡データを移行する」をご覧ください。

関連項目