maui-current-apis

.NET MAUI の現行 API — ガードレールスキル

このスキルは、非推奨、廃止予定、または削除済みの API を使用するコードを生成しないようにします。 .NET MAUI、Blazor Hybrid、または MauiReactor のコードを書く前に、これをお読みください。

推論フレームワーク

MAUI 関連のコードを生成する前に、次の手順に従ってください。

ステップ 1 — ターゲットフレームワークを確認する

プロジェクトの .csproj ファイルを読み、<TargetFramework> または <TargetFrameworks> を探します。

<TargetFramework>net10.0-android</TargetFramework>


<TargetFrameworks>net10.0-android;net10.0-ios;net10.0-maccatalyst;net10.0-windows10.0.19041.0</TargetFrameworks>

バージョン番号（net10.0、net9.0、net8.0）によって、使用できる API が決まります。 必ずプロジェクトファイルに記載されたバージョンをターゲットにしてください。バージョンを決めつけないでください。

ステップ 2 — ライブラリのバージョンを確認する

<PackageReference> エントリと <ItemGroup> をスキャンして、主要なパッケージを確認します。

パッケージ	わかること
Microsoft.Maui.Controls	MAUI のバージョン（明示されている場合）
CommunityToolkit.Maui	ツールキットのバージョン — メジャーバージョン間で API が変わります
CommunityToolkit.Mvvm	MVVM Toolkit のバージョン — WeakReferenceMessenger に必要です
Reactor.Maui	MauiReactor のバージョン — v3 以降は v2 とは異なる API を使用します
Microsoft.AspNetCore.Components.WebView.Maui	Blazor Hybrid のバージョン

MAUI パッケージのバージョンが明示されていない場合、MAUI SDK のバージョンは <TargetFramework> の .NET バージョンと一致します。

ステップ 3 — API が現行か確認する

API を使用する前に、次の点を確認してください。

1. この API は検出したバージョンに存在しますか？ 判断がつかない場合は、新しいパターンを優先してください。
2. これは Xamarin.Forms の API ですか？ MAUI は異なる API サーフェスです。Xamarin.Forms との互換性を決めつけないでください。
3. 以下の非推奨 API の表に載っていますか？ 載っている場合は、代替 API を使用してください。
4. Compatibility 名前空間を使用していますか？ Microsoft.Maui.Controls.Compatibility.* の型は移行支援用であり、新しいコードには推奨されません。

ステップ 4 — 判断ルールを適用する

• 古い形式と新しい形式の両方がある場合は、常に新しい形式の API を使用してください。
• using Xamarin.Forms や using Xamarin.Essentials は生成しないでください。これらは MAUI ではありません。
• 新しいプロジェクトでは、Compatibility 名前空間（Compatibility.RelativeLayout、Compatibility.StackLayout など）を使用しないでください。
• 同期処理を示す名前と非同期処理を示す名前の両方がある場合は、async メソッド名を優先してください（例：DisplayAlert より DisplayAlertAsync）。
• CommunityToolkit やサードパーティの API を使用する前に、プロジェクトの NuGet バージョンを確認してください。

---

非推奨 API の一覧 — .NET MAUI 10

コントロール

❌ 非推奨／削除済み	✅ 代わりに使用	備考
ListView	CollectionView	ListView、EntryCell、ImageCell、SwitchCell、TextCell、ViewCell、Cell はすべて .NET 10 で非推奨です
TableView	CollectionView またはカスタムレイアウト	.NET 10 で非推奨です
Frame	Border	Frame は Xamarin.Forms のレガシーコントロールです。Border は StrokeShape に対応した MAUI の代替コントロールです
Compatibility.RelativeLayout	Grid	移行専用です。.NET 10 のテンプレートから削除されています
Compatibility.StackLayout	VerticalStackLayout／HorizontalStackLayout	Compatibility の StackLayout は Xamarin のレイアウトロジックをラップしています。パフォーマンスを向上させるには、ネイティブの MAUI スタックレイアウトを使用してください

ジェスチャと入力

❌ 非推奨／削除済み	✅ 代わりに使用	備考
ClickGestureRecognizer	TapGestureRecognizer	.NET 10 で削除されています
Accelerator	KeyboardAccelerator	.NET 10 で Microsoft.Maui.Controls から削除されています

ページとナビゲーション

❌ 非推奨／削除済み	✅ 代わりに使用	備考
Page.IsBusy	ActivityIndicator	.NET 10 で IsBusy は廃止予定です。明示的なアクティビティインジケーターを使用してください
DisplayAlert()	DisplayAlertAsync()	同期処理を示す名前のバージョンは非推奨です。非同期バージョンを使用してください
DisplayActionSheet()	DisplayActionSheetAsync()	上記と同様です
MessagingCenter	WeakReferenceMessenger（CommunityToolkit.Mvvm）	.NET 10 で内部扱いになりました

アニメーション

❌ 非推奨／削除済み	✅ 代わりに使用	備考
FadeTo()	FadeToAsync()	.NET 10 では、すべてのアニメーション拡張メソッドの末尾が *Async に変更されています
RotateTo()、ScaleTo()、TranslateTo() など	RotateToAsync()、ScaleToAsync()、TranslateToAsync() など	同じパターンです。RelRotateTo → RelRotateToAsync、RelScaleTo → RelScaleToAsync、LayoutTo → LayoutToAsync

デバイスとプラットフォームの API

❌ 非推奨／削除済み	✅ 代わりに使用	備考
Device.RuntimePlatform	DeviceInfo.Platform	Device クラス全体が非推奨です
Device.BeginInvokeOnMainThread()	Dispatcher.Dispatch()	ビューまたはアプリの Dispatcher プロパティを使用します
Device.InvokeOnMainThreadAsync()	Dispatcher.DispatchAsync()	同上
Device.OpenUri()	Launcher.OpenAsync()	Microsoft.Maui.ApplicationModel.Launcher を使用します
Device.StartTimer()	Dispatcher.StartTimer() または PeriodicTimer	ディスパッチャーまたは標準の .NET タイマーを使用します
DependencyService	IServiceProvider によるコンストラクターインジェクション	MauiProgram.cs で builder.Services を使用してサービスを登録します

XAML とマークアップ

❌ 非推奨／削除済み	✅ 代わりに使用	備考
FontImageExtension（XAML マークアップ拡張）	FontImageSource（型）	<FontImageSource> 要素またはプロパティ構文を使用します
Color.FromHex()	Color.FromArgb()	FromHex は廃止予定です

セーフエリアとレイアウト

❌ 非推奨／削除済み	✅ 代わりに使用	備考
Page.UseSafeArea（iOS 固有）	SafeAreaEdges プロパティ	.NET 10 で追加されました。すべてのプラットフォームで、ContentPage の既定値は None（端から端まで表示）です
Layout.IgnoreSafeArea	SafeAreaEdges プロパティ	統一されたセーフエリア API を使用します

アクセシビリティ

❌ 非推奨／削除済み	✅ 代わりに使用	備考
AutomationProperties.Name	SemanticProperties.Description	AutomationProperties も引き続き動作しますが、SemanticProperties が MAUI ネイティブのアプローチです
AutomationProperties.HelpText	SemanticProperties.Hint	同上
iOS の SetAccessibilityHint／SetAccessibilityLabel（互換性拡張）	Microsoft.Maui.Platform.UpdateSemantics()	.NET 10 で非推奨になりました

NuGet パッケージ

❌ 非推奨のパッケージ	✅ 代わりに使用	備考
Xamarin.Forms	Microsoft.Maui.Controls	API の構成はまったく異なります
Xamarin.Essentials	組み込みの MAUI API（Microsoft.Maui.Devices、Microsoft.Maui.ApplicationModel など）	Essentials は MAUI に統合されています
Xamarin.CommunityToolkit	CommunityToolkit.Maui	名前空間と API の構成が異なります
Microsoft.Toolkit.Mvvm	CommunityToolkit.Mvvm	パッケージ名が変更されました

---

MauiReactor 固有のガイダンス

.NET MAUI 9／10 向けの MauiReactor v3 以降：

• ホットリロード：v3 以降では、.csproj の <RuntimeHostConfigurationOption> を使った機能スイッチを使用します。MauiProgram.cs で v2 の EnableMauiReactorHotReload() 呼び出しを使用しないでください。
• API ラッパー：MauiReactor は、MAUI コントロールの C# ラッパーを自動生成します。MAUI コントロール（例：ListView）が非推奨になると、MauiReactor のラッパーも実質的に非推奨になります。代替コントロール（例：CollectionView）には、MauiReactor のラッパーを使用してください。
• 状態管理：古いサンプルに記載されている場合でも、従来の RxComponent パターンではなく、State<T> と Props<T> を使用してください。
• ナビゲーション：MauiReactor の組み込みナビゲーション（Navigation.PushAsync<PageComponent>()）を使用してください。Shell を意図的に統合する場合を除き、MAUI Shell の GoToAsync を併用しないでください。

---

Blazor Hybrid 固有のガイダンス

• Razor コンポーネントのホスティングには、従来の WebView ではなく、BlazorWebView を使用してください。
• .NET 10 の Razor 構文を使用してください：@rendermode ディレクティブ、[SupplyParameterFromQuery]、最新のコンポーネントモデル。
• JS 相互運用：IJSRuntime.InvokeAsync<T>() を使用してください。モバイル向けの古い同期型 IJSInProcessRuntime パターンは使用しないでください。
• セーフエリア：Blazor Hybrid では、CSS の env(safe-area-inset-*) を使用してください。同じ要素に XAML の SafeAreaEdges と CSS のセーフエリア用パディングを併用しないでください（パディングが二重に適用されます）。
• Web リソースのインターセプト：.NET 10 では、リクエストをインターセプトするための BlazorWebView と HybridWebView の WebResourceRequested イベントが追加されています。

---

バージョン検出の早見表

TFM の確認

TFM のパターン	.NET のバージョン
net10.0-*	.NET 10（最新、現行）
net9.0-*	.NET 9
net8.0-*	.NET 8（LTS）

MAUI SDK のバージョン確認

.csproj で <UseMaui>true</UseMaui> を使用している場合、MAUI のバージョンは TFM と一致します：

• net10.0 → MAUI 10
• net9.0 → MAUI 9

MauiReactor のバージョン確認

<PackageReference Include="Reactor.Maui" Version="X.Y.Z" /> を確認してください：

• v3.x → .NET MAUI 9/10 と互換性があり、機能スイッチ方式のホットリロードを使用します
• v2.x → レガシー版で、EnableMauiReactorHotReload() ビルダーパターンを使用します

CommunityToolkit のバージョン確認

<PackageReference Include="CommunityToolkit.Maui" Version="X.Y.Z" /> を確認してください：

• v11+ → .NET 10 と互換性があります
• v9-10 → .NET 9 と互換性があります
• v5-7 → .NET 8 と互換性があります

---

クイックルール

1. まず .csproj を確認してください。 対象フレームワークを把握せずにコードを生成してはいけません。
2. 迷った場合は、新しい API を使用してください。 何かを行う方法が 2 通りある場合は、新しい方法が正しい方法です。
3. Xamarin.* 名前空間は使用しないでください。 MAUI には存在しません。
4. 新しいプロジェクトでは Compatibility.* 型を使用しないでください。 これらは移行支援専用です。
5. Device.* API を使用する前に、この表を確認してください。 Device クラスは完全に非推奨です。
6. .NET 10 以降では、アニメーション、アラート、アクションシートに *Async というメソッド名を使用してください。
7. サードパーティ製パッケージの API を使用する前に、バージョンを確認してください。 CommunityToolkit、MauiReactor などは、メジャーバージョン間で互換性が失われます。