maui-current-apis

name	maui-current-apis
description	Keep MAUI guidance on current, target-framework-safe APIs. USE FOR: inspecting `TargetFramework`/TFM, net8 vs net10 choices, `SafeAreaEdges` vs `On<iOS>().SetUseSafeArea`, replacing `Application.Current.MainPage`, Xamarin.Forms namespaces, Shell/window APIs, avoiding .NET 10-only output on older targets. DO NOT USE FOR: workload discovery, runtime inspection, or migration planning.

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

1. 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
   

2. Identify whether the project targets .NET 8, .NET 9, .NET 10, or multiple versions. Do not assume net10.0.

3. Prefer APIs from Microsoft.Maui.* namespaces. Do not add Xamarin.Forms or Xamarin.Essentials namespaces to MAUI projects.

4. If replacing an obsolete API, explain the replacement and why it matches the detected target.

5. Keep platform-specific code behind #if ANDROID, #if IOS, #if MACCATALYST, #if WINDOWS, or an injected platform service.

6. 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.