mcpField
X
xamarin-forms-migration

xamarin-forms-migration

github.com/davidortinau開発17643 回インストール16 週間前に更新
リポジトリ

xamarin-forms-migration について

Xamarin.Forms のプロジェクトを .NET MAUI に移行する開発者向けのガイドです。移行手順、レイアウト上の注意点、非推奨 API の確認方法を扱います。

主な機能

  1. 01単一プロジェクトへのコード移行
  2. 02名前空間と NuGet 依存関係の更新
  3. 03レンダラーからハンドラーへの移行
  4. 04エフェクトからビヘイビアへの置き換え
  5. 05レイアウトと API 互換性の問題調査

活用シーン

  1. 01Xamarin.Forms アプリの移行計画
  2. 02MAUI のレイアウト問題の修正
  3. 03カスタムレンダラーとエフェクトの置き換え

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/davidortinau/maui-skills --skill xamarin-forms-migration

インストール後、Claude Code で/xamarin-forms-migrationを入力して読み込まれたか確認します。

同梱ファイルreferences/forms-migration-api.md

詳細

Xamarin.Forms → .NET MAUI の移行

プロジェクトテンプレート、名前空間の表、API 非推奨項目の表、参照コードについては、references/forms-migration-api.md を参照してください。

⚠️ .NET Upgrade Assistant は使用しないでください。 名前空間の変更、プロジェクトファイルの更新、パッケージの置き換えは直接行ってください。変更をひとまとまり適用するごとにビルドし、コンパイラーエラーを次の修正の手がかりにしてください。

移行ワークフロー

  1. 新しい .NET MAUI プロジェクトを作成します（単一プロジェクトにしてください。マルチプロジェクトでは AOT／ビルドエラーが発生します）
  2. クロスプラットフォームコードとプラットフォームコードを Platforms/<platform>/ にコピーします
  3. 名前空間を更新します（XAML、C#、Essentials。references/forms-migration-api.md を参照）
  4. レイアウト動作の変更に対処します（以下を参照）
  5. レンダラーをハンドラーに移行します（互換用レンダラーは使用しないでください）
  6. エフェクトをビヘイビアに移行します
  7. Microsoft.Maui.Controls.Compatibility パッケージを削除します
  8. NuGet 依存関係を更新します
  9. アプリのデータストアを移行します
  10. bin/、obj/、Resource.designer.cs を削除してビルドし、テストを繰り返します
  11. .NET 10 の非推奨 API 一覧を基準に確認します

方針： 新しいプロジェクトを作成し、そこにコードをコピーしてください。既存のプロジェクトファイルを直接編集しないでください。

重大なレイアウト上の落とし穴

⚠️ 既定の間隔がゼロに変更されました

MAUI では、Xamarin.Forms で 6 に設定されていた間隔がゼロになります。レイアウトは気づかないうちに壊れます。


<Grid>...</Grid>
<StackLayout>...</StackLayout>


<Style TargetType="Grid">
    <Setter Property="ColumnSpacing" Value="6"/>
    <Setter Property="RowSpacing" Value="6"/>
</Style>

現場でのアドバイス： すべてのレイアウト値を明示的に指定してください。プラットフォームの既定値に依存しないでください。

⚠️ *AndExpand は非推奨です — 警告は表示されません

<StackLayout>
    <Label Text="Hello world!"/>
    <Image VerticalOptions="FillAndExpand" Source="dotnetbot.png"/>
</StackLayout>


<Grid RowDefinitions="Auto, *">
    <Label Text="Hello world!"/>
    <Image Grid.Row="1" Source="dotnetbot.png"/>
</Grid>

現場でのアドバイス： レイアウトツリーをフラット化してください。入れ子になった階層を、単一の Grid レイアウトに置き換えてください。

StackLayout 内の ScrollView はスクロールしません

StackLayout 内の ScrollView は、コンテンツ全体の高さまで拡張されるため、スクロールできません。代わりに、制約付きの行を設定した Grid に ScrollView を配置してください。

その他のレイアウト上の落とし穴
問題対処方法
Grid の列／行が宣言されておらず、レイアウトが壊れる常に ColumnDefinitions／RowDefinitions を明示的に追加します
Frame の測定動作が異なるStrokeShape を設定した Border に移行します
BoxView が表示されない（MAUI では既定のサイズが 0×0）WidthRequest／HeightRequest を明示的に設定します
RelativeLayoutGrid に置き換えます（互換性名前空間のみ）

レンダラーからハンドラーへの移行

⚠️ すべてのレンダラーをハンドラーに移行してください。互換用レンダラーは使用しないでください。親ラッパービューが作成され、パフォーマンスが低下します。

推奨：マッパーメソッドで既存のハンドラーをカスタマイズします。

// ✅ Extend existing handler — no new class needed
Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("NoBorder", (handler, view) =>
{
#if ANDROID
    handler.PlatformView.Background = null;
#elif IOS || MACCATALYST
    handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
#endif
});

まったく新しいネイティブビューを作成する場合は、完全なハンドラーを作成してください（maui-custom-handlers スキルを参照）。

エフェクトからビヘイビアへの移行

⚠️ エフェクトはビヘイビアに変わりました。単に名前を変更するのではなく、再設計が必要です。

新しい開発では、エフェクトよりもビヘイビアまたはハンドラーマッパーによるカスタマイズを優先してください。

⚠️ 互換性パッケージは使用しないでください

Microsoft.Maui.Controls.Compatibility は、連鎖的な非互換性を引き起こします。削除して、レイアウトをネイティブに再構築してください。

廃止された依存関係

  • App Center は廃止されています → Sentry、Azure Monitor などに置き換えてください
  • Visual Studio for Mac は廃止されています → VS Code または Rider を使用してください

Android 固有の警告

  • Android の移行は iOS よりはるかに難しく、UI の不具合が増えることを想定してください
  • OEM 固有の描画差異はエミュレーターで再現できません。実機でテストしてください
  • 影の描画は OEM／API レベルによって異なります。プラットフォーム固有のハンドラーコードで実装してください
  • ハンドラーレベルのプロパティ変更はテーマ切り替え時に自動更新されません。テーマ変更を手動で処理してください

.NET 10 API の最新性に関する警告

移行は、非推奨 API を最初から避ける絶好の機会です。すでに廃止に向かっている MAUI API に Xamarin.Forms のコードを移行しないでください。非推奨 API の全一覧は references/forms-migration-api.md を参照し、maui-current-apis スキルを実行してください。

よくあるトラブルシューティング

問題対処方法
Xamarin.* 名前空間が存在しないMicrosoft.Maui.* の同等の名前空間に更新します
CollectionView がスクロールしないGrid に配置します（サイズを制限するため、StackLayout ではなく）
iOS でポップアップがページの背後に表示されるContentPage から DisplayAlert を使用します
パディング／マージン／間隔が不足している明示的な値または暗黙的なスタイルを追加します
カスタムレンダラーが動作しないハンドラーに移行します
SkiaSharp が動作しないSkiaSharp.Views.Maui パッケージに更新します
App.Properties のデータにアクセスできないPreferences に移行します

クイックチェックリスト

  1. ☐ 新しい .NET MAUI プロジェクト（単一プロジェクト）を作成した
  2. ☐ クロスプラットフォームコードとプラットフォーム固有コードをコピーした
  3. ☐ XAML の名前空間を http://schemas.microsoft.com/dotnet/2021/maui に更新した
  4. ☐ Xamarin.Forms.* → Microsoft.Maui.* の名前空間に置き換えた
  5. ☐ Xamarin.Essentials → 分割された MAUI 名前空間に置き換えた
  6. ☐ Grid の ColumnDefinitions／RowDefinitions を明示的に追加した
  7. ☐ *AndExpand を Grid レイアウトに置き換えた
  8. ☐ 間隔／パディングの値を明示的に追加した（MAUI の既定値は 0）
  9. ☐ レンダラーをハンドラーに移行した（シム化されたレンダラーではなく）
  10. ☐ エフェクトをビヘイビアーまたは MAUI エフェクトに移行した
  11. ☐ Microsoft.Maui.Controls.Compatibility パッケージを削除した
  12. ☐ .NET との互換性に合わせて NuGet の依存関係を更新した
  13. ☐ App.Properties、SecureStorage、VersionTracking のデータを移行した
  14. ☐ bin/、obj/、Resource.designer.cs を削除した
  15. ☐ 実機の Android デバイスでテストした
  16. ☐ パフォーマンスをプロファイリングした
  17. ☐ 非推奨の .NET 10 API がないことを確認した（maui-current-apis スキルを実行）

コメント

Markdown 対応