MAUI Current APIs
Use this skill before changing MAUI app code when API currency matters. The goal
is to inspect the project target first, then select APIs that match that target
instead of generating stale Xamarin.Forms or early MAUI patterns.
Workflow
Inspect the target frameworks and package versions before recommending APIs:
grep -R -n --include="*.csproj" --include="Directory.Build.props" "<TargetFramework" . 2>/dev/null
grep -R -n --include="*.csproj" --include="Directory.Build.props" --include="Directory.Packages.props" \
"Microsoft.Maui.Controls\\|UseMaui\\|MauiVersion" . 2>/dev/null
Identify whether the project targets .NET 8, .NET 9, .NET 10, or multiple
versions. Do not assume net10.0.
Prefer APIs from Microsoft.Maui.* namespaces. Do not add Xamarin.Forms or
Xamarin.Essentials namespaces to MAUI projects.
If replacing an obsolete API, explain the replacement and why it matches the
detected target.
Keep platform-specific code behind #if ANDROID, #if IOS, #if MACCATALYST, #if WINDOWS, or an injected platform service.
Build the changed project for the relevant target framework.
Common Agent Traps
| Avoid |
Prefer |
using Xamarin.Forms; |
using Microsoft.Maui.Controls; |
using Xamarin.Essentials; |
using Microsoft.Maui.ApplicationModel, Microsoft.Maui.Devices, Microsoft.Maui.Storage, or the specific MAUI namespace |
Device.BeginInvokeOnMainThread(...) |
MainThread.BeginInvokeOnMainThread(...) |
Device.StartTimer(...) |
Dispatcher.StartTimer(...) or IDispatcherTimer |
Device.RuntimePlatform for platform behavior |
DeviceInfo.Platform, OnPlatform, or compile-time platform services |
MessagingCenter for new app architecture |
WeakReferenceMessenger, events, interfaces, or another explicit messaging abstraction |
| Old Xamarin.Forms custom renderers for new code |
MAUI handlers, property mappers, or platform services |
| Hard-coded safe area padding |
SafeAreaEdges / safe area APIs for the detected MAUI version |
| Coordinate-based UI automation |
Stable AutomationId plus DevFlow queries |
Application.Current.MainPage = ... for routine navigation |
Shell navigation with registered routes, or set Window.Page explicitly for intentional app reset flows |
Safe Area Guidance
For .NET 10+ safe area work, prefer SafeAreaEdges over legacy iOS-only safe
area patterns. Confirm the target framework before changing safe area code:
<Grid SafeAreaEdges="Container">
...
</Grid>
Use platform-specific fallbacks only when the app targets an older MAUI version
where the newer API is unavailable.
Window and Shell Guidance
- In multi-window code, do not blindly rely on a global main page. Use the
current
Window, Shell.Current, or an injected navigation abstraction that
matches the app's architecture.
- For Shell apps, use registered routes and
GoToAsync instead of manually
replacing root pages unless the app intentionally owns the full window flow.
- For navigation parameters, prefer
IQueryAttributable or [QueryProperty]
and URL-encode route values when building URI strings.
Validation Checklist
- The edited project target framework was inspected.
- No
Xamarin.Forms or Xamarin.Essentials namespace was introduced.
- Replacements are compatible with the detected MAUI version.
- Platform-specific code is isolated behind target-specific files, partial
classes, DI abstractions, or
#if guards.
- The changed target framework builds.
1---2name: maui-current-apis3description: Keep MAUI guidance target-framework-safe. USE FOR: checking TFM, net8 vs net10 API choices, `SafeAreaEdges`, replacing `Application.Current.MainPage`, Xamarin.Forms namespaces, Shell/window APIs, avoiding .NET 10-only APIs on older targets. DO NOT USE FOR: workload discovery, runtime inspection, migration planning.4---56# MAUI Current APIs78Use this skill before changing MAUI app code when API currency matters. The goal9is to inspect the project target first, then select APIs that match that target10instead of generating stale Xamarin.Forms or early MAUI patterns.1112## Workflow13141. Inspect the target frameworks and package versions before recommending APIs:1516 ```bash17 grep -R -n --include="*.csproj" --include="Directory.Build.props" "<TargetFramework" . 2>/dev/null18 grep -R -n --include="*.csproj" --include="Directory.Build.props" --include="Directory.Packages.props" \19 "Microsoft.Maui.Controls\\|UseMaui\\|MauiVersion" . 2>/dev/null20 ```21222. Identify whether the project targets .NET 8, .NET 9, .NET 10, or multiple23 versions. Do not assume `net10.0`.243. Prefer APIs from `Microsoft.Maui.*` namespaces. Do not add `Xamarin.Forms` or25 `Xamarin.Essentials` namespaces to MAUI projects.264. If replacing an obsolete API, explain the replacement and why it matches the27 detected target.285. Keep platform-specific code behind `#if ANDROID`, `#if IOS`, `#if29 MACCATALYST`, `#if WINDOWS`, or an injected platform service.306. Build the changed project for the relevant target framework.3132## Common Agent Traps3334| Avoid | Prefer |35| --- | --- |36| `using Xamarin.Forms;` | `using Microsoft.Maui.Controls;` |37| `using Xamarin.Essentials;` | `using Microsoft.Maui.ApplicationModel`, `Microsoft.Maui.Devices`, `Microsoft.Maui.Storage`, or the specific MAUI namespace |38| `Device.BeginInvokeOnMainThread(...)` | `MainThread.BeginInvokeOnMainThread(...)` |39| `Device.StartTimer(...)` | `Dispatcher.StartTimer(...)` or `IDispatcherTimer` |40| `Device.RuntimePlatform` for platform behavior | `DeviceInfo.Platform`, `OnPlatform`, or compile-time platform services |41| `MessagingCenter` for new app architecture | `WeakReferenceMessenger`, events, interfaces, or another explicit messaging abstraction |42| Old Xamarin.Forms custom renderers for new code | MAUI handlers, property mappers, or platform services |43| Hard-coded safe area padding | `SafeAreaEdges` / safe area APIs for the detected MAUI version |44| Coordinate-based UI automation | Stable `AutomationId` plus DevFlow queries |45| `Application.Current.MainPage = ...` for routine navigation | Shell navigation with registered routes, or set `Window.Page` explicitly for intentional app reset flows |4647## Safe Area Guidance4849For .NET 10+ safe area work, prefer `SafeAreaEdges` over legacy iOS-only safe50area patterns. Confirm the target framework before changing safe area code:5152```xml53<Grid SafeAreaEdges="Container">54 ...55</Grid>56```5758Use platform-specific fallbacks only when the app targets an older MAUI version59where the newer API is unavailable.6061## Window and Shell Guidance6263- In multi-window code, do not blindly rely on a global main page. Use the64 current `Window`, `Shell.Current`, or an injected navigation abstraction that65 matches the app's architecture.66- For Shell apps, use registered routes and `GoToAsync` instead of manually67 replacing root pages unless the app intentionally owns the full window flow.68- For navigation parameters, prefer `IQueryAttributable` or `[QueryProperty]`69 and URL-encode route values when building URI strings.7071## Validation Checklist7273- The edited project target framework was inspected.74- No `Xamarin.Forms` or `Xamarin.Essentials` namespace was introduced.75- Replacements are compatible with the detected MAUI version.76- Platform-specific code is isolated behind target-specific files, partial77 classes, DI abstractions, or `#if` guards.78- The changed target framework builds.
.NET (Microsoft)