アプリを Xamarin.Forms .NET MAUI に手動でアップグレードする
アプリを Xamarin.Forms .NET マルチプラットフォーム アプリ UI (.NET MAUI) アプリにアップグレードするには、Xamarin.Android および Xamarin.iOS プロジェクトと同じ手順に従い、.NET MAUI の変更を利用する追加の手順を実行します。
この記事では、ライブラリ プロジェクトを .NET MAUI ライブラリ プロジェクトに手動で移行 Xamarin.Forms する方法について説明します。 これを行う前に、プラットフォーム プロジェクトを Xamarin.Forms SDK スタイルのプロジェクトに更新する必要があります。 SDK スタイルのプロジェクトは、すべての .NET ワークロードで使用されるのと同じプロジェクト形式であり、多くの Xamarin プロジェクトと比較すると、はるかに詳細ではありません。 アプリ プロジェクトの更新の詳細については、「Xamarin.Android、Xamarin.iOS、Xamarin.Mac アプリを .NET、Xamarin.Android プロジェクト移行、Xamarin Apple プロジェクト移行にアップグレードする」を参照してください。
ライブラリ プロジェクトを Xamarin.Forms .NET MAUI ライブラリ プロジェクトに移行するには、次の手順を実行する必要があります。
- プロジェクト ファイルを SDK スタイルに更新します。
- 名前空間を更新します。
- API の変更に対処します。
- .NET MAUI を構成します。
- 互換性のない依存関係を .NET 6 以降のバージョンにアップグレードまたは置き換えます。
- アプリをコンパイルしてテストします。
アップグレード プロセスを簡略化するために、ライブラリ プロジェクトと同じ名前の新しい .NET MAUI ライブラリ プロジェクトを Xamarin.Forms 作成し、コード内でコピーすることをお勧めします。 これは、次に示すアプローチです。
新しいプロジェクトを作成する
Visual Studio で、ライブラリ プロジェクトと同じ名前の新しい .NET MAUI クラス ライブラリ プロジェクトを作成します Xamarin.Forms 。 このプロジェクトは、ライブラリ プロジェクトのコードを Xamarin.Forms ホストします。 プロジェクト ファイルを開くと、.NET SDK スタイルのプロジェクトがあることを確認します。
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net7.0;net7.0-android;net7.0-ios;net7.0-maccatalyst</TargetFrameworks>
<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net7.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);net7.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 。
名前空間の変更
名前空間は . Xamarin.Forms NET MAUI への移行で変更され Xamarin.Essentials 、機能は .NET MAUI の一部になりました。 名前空間を更新するには、次の名前空間の検索と置換を実行します。
.NET MAUI プロジェクトでは、暗黙的な global using ディレクティブを使用します。 これにより、名前空間のXamarin.Essentialsディレクティブを、同等の .NET MAUI 名前空間に置き換えることなく削除usingできます。
さらに、.NET MAUI では、既定の XAML 名前空間が から Xamarin.Forms にhttp://schemas.microsoft.com/dotnet/2021/maui変更http://xamarin.com/schemas/2014/formsされました。 したがって、 のすべての出現箇所を xmlns="http://xamarin.com/schemas/2014/forms" に xmlns="http://schemas.microsoft.com/dotnet/2021/maui"置き換える必要があります。
API の変更
一部の API は、 Xamarin.Forms .NET MAUI への移行で変更されています。 これは、.NET MAUI の一部になることによる Xamarin.Essentials 重複する機能の削除や、API が .NET の名前付けガイドラインに従っていることを確認するなど、複数の理由があります。 以下のセクションでは、これらの変更について説明します。
色の変更
ではXamarin.Forms、 構造体をXamarin.Forms.Color使用して値を使用してオブジェクトをdouble構築Colorし、 などのXamarin.Forms.Color.AliceBlue名前付き色を提供します。 .NET MAUI では、この機能は クラスと Microsoft.Maui.Graphics.Colors クラスにMicrosoft.Maui.Graphics.Color分離されています。
Microsoft.Maui.Graphics.Color名前空間の クラスをMicrosoft.Maui.Graphics使用すると、値、値、byteおよび値を使用してオブジェクトをfloatint構築Colorできます。 名前空間にもMicrosoft.Maui.Graphics含まれる クラスはMicrosoft.Maui.Graphics.Colors、主に同じ名前付き色を提供します。
次の表は、 構造体と クラスの間の API の Xamarin.Forms.Color 変更を Microsoft.Maui.Graphics.Color 示しています。
| 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使用されるのではなくdouble、 ですXamarin.Forms.Color。float
注意
とは異なり 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>.Add | Add 5 つの引数を受け取るオーバーロードは、.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 new Label { Text = "Hello world" });
.NET MAUI では、 Children コレクションは .NET MAUI による内部使用を目的としており、直接操作しないでください。 したがって、コードでは、子をレイアウトに直接追加する必要があります。
Grid grid = new Grid();
grid.Add(new new Label { Text = "Hello world" });
重要
AddなどのGridExtensions.Addレイアウト拡張メソッドは、layouts Children コレクションではなくレイアウトで呼び出されます。
アップグレードされた .NET MAUI アプリを実行すると、レイアウトの動作が異なることがあります。 詳細については、「からのXamarin.Formsレイアウト動作の変更」を参照してください。
カスタム レイアウトの変更
でXamarin.Formsカスタム レイアウトを作成するプロセスでは、 からLayout<View>派生するクラスを作成し、 メソッドと LayoutChildren メソッドをOnMeasureオーバーライドします。 詳細については、「でXamarin.Formsカスタム レイアウトを作成する」を参照してください。
.NET MAUI でカスタム レイアウトを作成するプロセスには、実装をILayoutManager作成し、 メソッドと ArrangeChildren メソッドをオーバーライドするMeasure必要があります。
- オーバーライドはMeasure、レイアウト内のそれぞれにIView対して を呼び出Measureす必要があり、制約を受けた場合はレイアウトの合計サイズを返す必要があります。
- オーバーライドはArrangeChildren、それぞれがIView指定された境界内のどこに配置するかを決定し、適切な境界を持つ各 IView で を呼び出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.Maps 名前空間にMicrosoft.Maui.Controls.Maps移動しました。 一部のプロパティの名前が変更され、一部の型は から Xamarin.Essentials同等の型に置き換えられました。
次の表は、 名前空間の機能 Xamarin.Forms.Maps に対する .NET MAUI の置き換えを示しています。
.NET MAUI には、 と Microsoft.Maui.ApplicationModel.Mapの Microsoft.Maui.Controls.Maps.Map 2 種類Mapがあります。 Microsoft.Maui.ApplicationModel名前空間は .NET MAUI global using のディレクティブの 1 つであるため、コードからコントロールをMicrosoft.Maui.Controls.Maps.Map使用する場合は、使用量を完全に修飾するか、using エイリアスを使用する必要がありますMap。
XAML では、コントロールに xmlns 名前空間定義を追加する Map 必要があります。 これは必須ではありませんが、 と の両方の名前空間に存在する 型と Polyline 型の競合PolygonをMicrosoft.Maui.Controls.MapsMicrosoft.Maui.Controls.Shapes防ぎます。 詳細については、「 マップを表示する」を参照してください。
その他の変更点
.NET MAUI への移行 Xamarin.Forms では、他にも少数の API が統合されています。 次の表に、これらの変更を示します。
ネイティブ フォームの変更
のXamarin.Formsネイティブ フォームは.NET MAUI でネイティブ埋め込みになっており、異なる初期化アプローチとさまざまな拡張メソッドを使用して、クロスプラットフォーム コントロールをネイティブ型に変換します。 詳細については、「 ネイティブ埋め込み」を参照してください。
移行されたアプリをブートストラップする
を .NET MAUI に手動で更新する Xamarin.Forms 場合は、各プラットフォーム プロジェクトのエントリ ポイント クラスを更新し、.NET MAUI アプリのブートストラップを構成する必要があります。
Android プロジェクトの構成
.NET MAUI Android プロジェクトで、 クラスを次の MainApplication コードに一致するように更新します。
using System;
using Android.App;
using Android.Runtime;
using Microsoft.Maui;
using Microsoft.Maui.Hosting;
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);
}
}
}
次に、マニフェスト ファイルを更新して、 が 21 であることを minSdKVersion 指定します。これは、.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;
namespace YOUR_NAMESPACE_HERE.iOS
{
[Register("AppDelegate")]
public partial class AppDelegate : MauiUIApplicationDelegate
{
protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}
}
次に、 Info.plist を更新して MinimumOSVersion 、.NET MAUI で必要な最小 iOS バージョンである 11.0 を更新します。
アプリのエントリ ポイント
.NET MAUI アプリには、1 つのクロスプラットフォーム アプリ エントリ ポイントがあります。 各プラットフォーム エントリ ポイントは、 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();
}
}
AssemblyInfo の変更
通常、AssemblyInfo.cs ファイルで設定されるプロパティは、SDK スタイルのプロジェクトで使用できるようになりました。 AssemblyInfo.cs からすべてのプロジェクトのプロジェクト ファイルに移行し、AssemblyInfo.cs ファイルを削除することをお勧めします。
必要に応じて、AssemblyInfo.cs ファイルを保持し、プロジェクト ファイルの プロパティを にfalse設定GenerateAssemblyInfoできます。
<PropertyGroup>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>
プロパティの GenerateAssemblyInfo 詳細については、「 GenerateAssemblyInfo」を参照してください。
アプリの依存関係を更新する
Xamarin.Forms NuGet パッケージは、.NET ターゲット フレームワーク モニカー (TFM) を使用して再コンパイルされていない限り、.NET 6 以降と互換性がありません。 使用しているパッケージの NuGet の [フレームワーク] タブを確認し、次の表に示す互換性のあるフレームワークのいずれかが一覧表示されていることを確認することで、パッケージが .NET 7 以降と互換性があることを確認できます。
| 互換性のあるフレームワーク | 互換性のないフレームワーク |
|---|---|
| net7.0-android | monoandroid、monoandroid10.0 |
| net7.0-ios | monotouch、xamarinios、xamarinios10 |
| net7.0-maccatalyst | |
| net7.0-windows | uap10.0.16299 |
注意
以下に示す互換性のないフレームワークに依存しない .NET Standard ライブラリは、.NET 6 以降と互換性があります。
NuGet 上のパッケージが、互換性のないフレームワークを含むかどうかにかかわらず、上記のいずれかのnet6新しいフレームワークとの互換性を示している場合、パッケージは互換性があります。 Visual Studio の NuGet パッケージ マネージャーを使用して、互換性のある NuGet パッケージを .NET MAUI ライブラリ プロジェクトに追加できます。
.NET 6 以降と互換性のあるバージョンの NuGet パッケージが見つからない場合は、次の手順を実行する必要があります。
- コードを所有している場合は、.NET TFM を使用してパッケージを再コンパイルします。
- .NET 6 以降のバージョンのパッケージのプレビュー リリースを探します。
- 依存関係を .NET 6 以降と互換性のある代替手段に置き換えます。
コンパイルとトラブルシューティング
依存関係が解決されたら、プロジェクトをビルドする必要があります。 エラーがあれば、次の手順に進みます。
ヒント
- Visual Studio でプロジェクトを開いてビルドする前に、特に .NET バージョンを変更する場合は、すべてのプロジェクトから すべての bin フォルダーと obj フォルダーを削除します。
- Resource.designer.cs で生成されたファイルを Android プロジェクトから削除します。
次の表は、一般的なビルドまたはランタイムの問題を克服するためのガイダンスを示しています。
| 問題 | ヒント |
|---|---|
Xamarin.* 名前空間が存在しません。 |
名前空間を同等の .NET MAUI に更新します。 詳細については、「名前空間の 変更」を参照してください。 |
| API が存在しません。 | API の使用状況を、それに相当する .NET MAUI に更新します。 詳細については、「API の 変更」を参照してください。 |
| アプリはデプロイされません。 | 必要なプラットフォーム プロジェクトが Visual Studio のConfiguration Managerにデプロイするように設定されていることを確認します。 |
| アプリは起動しません。 | 各プラットフォーム プロジェクトのエントリ ポイント クラスとアプリ エントリ ポイントを更新します。 詳細については、「 移行したアプリを Boostrap する」を参照してください。 |
| CollectionView はスクロールしません。 | コンテナーのレイアウトと の測定されたサイズを確認します CollectionView。 既定では、コントロールはコンテナーで許可されているのと同じ容量を占有します。 は Grid 、子を独自のサイズで制限します。 ただし、 StackLayout では、子が境界を超えて領域を占有できるようになります。 |
| BoxView が表示されません。 | のXamarin.Forms既定のBoxViewサイズは 40 x 40 です。 .NET MAUI の の既定の BoxView サイズは0x0です。 と HeightRequest を 40 に設定WidthRequestします。 |
| レイアウトに埋め込み、余白、または間隔がありません。 | .NET MAUI スタイル のリソースに基づいて、プロジェクトに既定値を追加します。 詳細については、「からのXamarin.Forms既定値の変更」を参照してください。 |
| カスタム レイアウトが機能しません。 | .NET MAUI で動作するようにカスタム レイアウト コードを更新する必要があります。 詳細については、「 カスタム レイアウトの変更」を参照してください。 |
| カスタム レンダラーが機能しません。 | レンダラー コードは、.NET MAUI で動作するように更新する必要があります。 詳細については、「 .NET MAUI でカスタム レンダラーを使用する」を参照してください。 |
| 効果が機能しません。 | .NET MAUI で動作するように効果コードを更新する必要があります。 詳細については、「 .NET MAUI で効果を使用する」を参照してください。 |