/maui-current-apis

name: maui-current-apis
description: >
  Always-on guardrail for .NET MAUI API currency. Prevents AI coding agents from
  using deprecated, obsolete, or removed APIs across XAML/C#, Blazor Hybrid, and
  MauiReactor. Includes a reasoning framework for detecting project target framework
  and library versions, plus a curated table of the most common deprecated API traps
  in .NET MAUI 10.
  USE FOR: "deprecated API", "obsolete API", "API migration", "MAUI breaking changes",
  "check API currency", "review MAUI code", "generate MAUI code", "edit MAUI code".
  DO NOT USE FOR: learning new MAUI features (use feature-specific skills),
  performance optimization (use maui-performance), or testing guidance (use maui-unit-testing).

.NET MAUI Current APIs — Guardrail Skill

This skill prevents you from generating code that uses deprecated, obsolete, or removed APIs. **Read this before writing any .NET MAUI, Blazor Hybrid, or MauiReactor code.**

Reasoning Framework

Follow these steps **before** generating any MAUI-related code:

Step 1 — Detect the Target Framework

Read the project's `.csproj` file and find `<TargetFramework>` or `<TargetFrameworks>`:

<!-- Single target -->
<TargetFramework>net10.0-android</TargetFramework>

<!-- Multi-target (typical MAUI project) -->
<TargetFrameworks>net10.0-android;net10.0-ios;net10.0-maccatalyst;net10.0-windows10.0.19041.0</TargetFrameworks>

The version number (`net10.0`, `net9.0`, `net8.0`) determines which APIs are available. **Always target the version in the project file — never assume a version.**

Step 2 — Detect Library Versions

Scan `<PackageReference>` entries and `<ItemGroup>` for key packages:

| Package | What it tells you | |---------|-------------------| | `Microsoft.Maui.Controls` | MAUI version (if explicit) | | `CommunityToolkit.Maui` | Toolkit version — APIs change between major versions | | `CommunityToolkit.Mvvm` | MVVM Toolkit version — needed for `WeakReferenceMessenger` | | `Reactor.Maui` | MauiReactor version — v3+ has different APIs than v2 | | `Microsoft.AspNetCore.Components.WebView.Maui` | Blazor Hybrid version |

If no explicit MAUI package version is listed, the MAUI SDK version matches the `<TargetFramework>` .NET version.

Step 3 — Verify API Currency

Before using any API, ask yourself:

1. **Does this API exist in the detected version?** If you're unsure, prefer the newer pattern. 2. **Is this a Xamarin.Forms API?** MAUI is a different API surface — never assume Xamarin.Forms compatibility. 3. **Is this in the deprecated table below?** If so, use the replacement. 4. **Am I using the Compatibility namespace?** `Microsoft.Maui.Controls.Compatibility.*` types are migration aids, not recommended for new code.

Step 4 — Apply Decision Rules

• **Always use the newest form** of an API when both old and new exist.
• **Never generate `using Xamarin.Forms`** or `using Xamarin.Essentials` — these are not MAUI.
• **Never use the `Compatibility` namespace** in new projects (`Compatibility.RelativeLayout`, `Compatibility.StackLayout`, etc.).
• **Prefer `async` method names** when both sync-named and async-named versions exist (e.g., `DisplayAlertAsync` over `DisplayAlert`).
• **Check the project's NuGet versions** before using CommunityToolkit or third-party APIs.

---

Deprecated API Table — .NET MAUI 10

Controls

| ❌ Deprecated / Removed | ✅ Use Instead | Notes | |--------------------------|----------------|-------| | `ListView` | `CollectionView` | `ListView`, `EntryCell`, `ImageCell`, `SwitchCell`, `TextCell`, `ViewCell`, and `Cell` are all deprecated in .NET 10 | | `TableView` | `CollectionView` or custom layout | Deprecated in .NET 10 | | `Frame` | `Border` | `Frame` is a Xamarin.Forms legacy control; `Border` is the MAUI replacement with `StrokeShape` support | | `Compatibility.RelativeLayout` | `Grid` | Migration-only; removed from templates in .NET 10 | | `Compatibility.StackLayout` | `VerticalStackLayout` / `HorizontalStackLayout` | The compatibility `StackLayout` wraps Xamarin layout logic. Use the native MAUI stack layouts for better performance |

Gestures & Input

| ❌ Deprecated / Removed | ✅ Use Instead | Notes | |--------------------------|----------------|-------| | `ClickGestureRecognizer` | `TapGestureRecognizer` | Removed in .NET 10 | | `Accelerator` | `KeyboardAccelerator` | Removed from `Microsoft.Maui.Controls` in .NET 10 |

Page & Navigation

| ❌ Deprecated / Removed | ✅ Use Instead | Notes | |--------------------------|----------------|-------| | `Page.IsBusy` | `ActivityIndicator` | `IsBusy` is obsolete in .NET 10; use an explicit activity indicator | | `DisplayAlert()` | `DisplayAlertAsync()` | Sync-named versions deprecated; use async versions | | `DisplayActionSheet()` | `DisplayActionSheetAsync()` | Same as above | | `MessagingCenter` | `WeakReferenceMessenger` (CommunityToolkit.Mvvm) | Made internal in .NET 10 |

Animation

| ❌ Deprecated / Removed | ✅ Use Instead | Notes | |--------------------------|----------------|-------| | `FadeTo()` | `FadeToAsync()` | All animation extension methods renamed to `*Async` in .NET 10 | | `RotateTo()`, `ScaleTo()`, `TranslateTo()`, etc. | `RotateToAsync()`, `ScaleToAsync()`, `TranslateToAsync()`, etc. | Same pattern — `RelRotateTo` → `RelRotateToAsync`, `RelScaleTo` → `RelScaleToAsync`, `LayoutTo` → `LayoutToAsync` |

Device & Platform APIs

| ❌ Deprecated / Removed | ✅ Use Instead | Notes | |--------------------------|----------------|-------| | `Device.RuntimePlatform` | `DeviceInfo.Platform` | The entire `Device` class is deprecated | | `Device.BeginInvokeOnMainThread()` | `Dispatcher.Dispatch()` | Use the view's or app's `Dispatcher` property | | `Device.InvokeOnMainThreadAsync()` | `Dispatcher.DispatchAsync()` | Same | | `Device.OpenUri()` | `Launcher.OpenAsync()` | Use `Microsoft.Maui.ApplicationModel.Launcher` | | `Device.StartTimer()` | `Dispatcher.StartTimer()` or `PeriodicTimer` | Use the disp