.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:
- Does this API exist in the detected version? If you're unsure, prefer the newer pattern.
- Is this a Xamarin.Forms API? MAUI is a different API surface — never assume Xamarin.Forms compatibility.
- Is this in the deprecated table below? If so, use the replacement.
- 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() |
MainThread.BeginInvokeOnMainThread() |
Use Microsoft.Maui.ApplicationModel.MainThread |
Device.InvokeOnMainThreadAsync() |
MainThread.InvokeOnMainThreadAsync() |
Same |
Device.OpenUri() |
Launcher.OpenAsync() |
Use Microsoft.Maui.ApplicationModel.Launcher |
Device.StartTimer() |
Dispatcher.StartTimer() or PeriodicTimer |
Use the dispatcher or standard .NET timer |
DependencyService |
Constructor injection via IServiceProvider |
Register services in MauiProgram.cs with builder.Services |
XAML & Markup
| ❌ Deprecated / Removed |
✅ Use Instead |
Notes |
FontImageExtension (XAML markup extension) |
FontImageSource (type) |
Use <FontImageSource> element or property syntax |
Color.FromHex() |
Color.FromArgb() |
FromHex is obsolete |
Safe Area & Layout
| ❌ Deprecated / Removed |
✅ Use Instead |
Notes |
Page.UseSafeArea (iOS platform-specific) |
SafeAreaEdges property |
New in .NET 10; ContentPage defaults to None (edge-to-edge) on all platforms |
Layout.IgnoreSafeArea |
SafeAreaEdges property |
Use the unified safe area API |
Accessibility
| ❌ Deprecated / Removed |
✅ Use Instead |
Notes |
AutomationProperties.Name |
SemanticProperties.Description |
AutomationProperties still works but SemanticProperties is the MAUI-native approach |
AutomationProperties.HelpText |
SemanticProperties.Hint |
Same |
iOS SetAccessibilityHint / SetAccessibilityLabel (Compatibility extensions) |
Microsoft.Maui.Platform.UpdateSemantics() |
Deprecated in .NET 10 |
NuGet Packages
| ❌ Deprecated Package |
✅ Use Instead |
Notes |
Xamarin.Forms |
Microsoft.Maui.Controls |
Completely different API surface |
Xamarin.Essentials |
Built-in MAUI APIs (Microsoft.Maui.Devices, Microsoft.Maui.ApplicationModel, etc.) |
Essentials is merged into MAUI |
Xamarin.CommunityToolkit |
CommunityToolkit.Maui |
Different namespace and API surface |
Microsoft.Toolkit.Mvvm |
CommunityToolkit.Mvvm |
Package was renamed |
MauiReactor-Specific Guidance
MauiReactor v3+ (for .NET MAUI 9/10):
- Hot reload: v3+ uses a feature switch in
.csproj via <RuntimeHostConfigurationOption>. Do NOT use the v2 EnableMauiReactorHotReload() call in MauiProgram.cs.
- API wrappers: MauiReactor auto-generates C# wrappers around MAUI controls. When a MAUI control is deprecated (e.g.,
ListView), the MauiReactor wrapper is also effectively deprecated. Use the MauiReactor wrapper for the replacement control (e.g., CollectionView).
- State management: Use
State<T> and Props<T> — not older RxComponent patterns if they appear in outdated examples.
- Navigation: Use MauiReactor's built-in navigation (
Navigation.PushAsync<PageComponent>()) — do NOT mix in MAUI Shell GoToAsync unless deliberately integrating Shell.
Blazor Hybrid-Specific Guidance
- Use
BlazorWebView — not the legacy WebView — for hosting Razor components.
- Use .NET 10 Razor syntax:
@rendermode directives, [SupplyParameterFromQuery], and the latest component model.
- JS interop: Use
IJSRuntime.InvokeAsync<T>() — not the obsolete synchronous IJSInProcessRuntime patterns for mobile.
- Safe areas: In Blazor Hybrid, use CSS
env(safe-area-inset-*) — do NOT combine XAML SafeAreaEdges and CSS safe area padding on the same element (causes double-padding).
- Web resource interception: .NET 10 adds
WebResourceRequested event on BlazorWebView and HybridWebView for intercepting requests.
Version Detection Cheat Sheet
Reading the TFM
| TFM Pattern |
.NET Version |
net10.0-* |
.NET 10 (latest, current) |
net9.0-* |
.NET 9 |
net8.0-* |
.NET 8 (LTS) |
Reading MAUI SDK Version
If the .csproj uses <UseMaui>true</UseMaui>, the MAUI version matches the TFM:
net10.0 → MAUI 10net9.0 → MAUI 9
Reading MauiReactor Version
Check <PackageReference Include="Reactor.Maui" Version="X.Y.Z" />:
- v3.x → .NET MAUI 9/10 compatible, uses feature-switch hot reload
- v2.x → Legacy, uses
EnableMauiReactorHotReload() builder pattern
Reading CommunityToolkit Version
Check <PackageReference Include="CommunityToolkit.Maui" Version="X.Y.Z" />:
- v11+ → .NET 10 compatible
- v9-10 → .NET 9 compatible
- v5-7 → .NET 8 compatible
Quick Rules
- Read the
.csproj first. Never generate code without knowing the target framework.
- When in doubt, use the newer API. If two ways exist to do something, the newer way is correct.
- Never use
Xamarin.* namespaces. They do not exist in MAUI.
- Never use
Compatibility.* types in new projects. They are migration aids only.
- Check this table before using any
Device.* API. The Device class is fully deprecated.
- Use
*Async method names for animations, alerts, and action sheets in .NET 10+.
- Verify third-party package versions before using their APIs — CommunityToolkit, MauiReactor, and others break between major versions.
1---2name: maui-current-apis3description: 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).4---5
6# .NET MAUI Current APIs — Guardrail Skill
7
8This skill prevents you from generating code that uses deprecated, obsolete, or removed APIs.
9**Read this before writing any .NET MAUI, Blazor Hybrid, or MauiReactor code.**
10
11## Reasoning Framework
12
13Follow these steps **before** generating any MAUI-related code:
14
15### Step 1 — Detect the Target Framework
16
17Read the project's `.csproj` file and find `<TargetFramework>` or `<TargetFrameworks>`:
18
19```xml
20<!-- Single target -->
21<TargetFramework>net10.0-android</TargetFramework>
22
23<!-- Multi-target (typical MAUI project) -->
24<TargetFrameworks>net10.0-android;net10.0-ios;net10.0-maccatalyst;net10.0-windows10.0.19041.0</TargetFrameworks>
25```
26
27The version number (`net10.0`, `net9.0`, `net8.0`) determines which APIs are available.
28**Always target the version in the project file — never assume a version.**
29
30### Step 2 — Detect Library Versions
31
32Scan `<PackageReference>` entries and `<ItemGroup>` for key packages:
33
34| Package | What it tells you |
35|---------|-------------------|
36| `Microsoft.Maui.Controls` | MAUI version (if explicit) |
37| `CommunityToolkit.Maui` | Toolkit version — APIs change between major versions |
38| `CommunityToolkit.Mvvm` | MVVM Toolkit version — needed for `WeakReferenceMessenger` |
39| `Reactor.Maui` | MauiReactor version — v3+ has different APIs than v2 |
40| `Microsoft.AspNetCore.Components.WebView.Maui` | Blazor Hybrid version |
41
42If no explicit MAUI package version is listed, the MAUI SDK version matches the `<TargetFramework>` .NET version.
43
44### Step 3 — Verify API Currency
45
46Before using any API, ask yourself:
47
481. **Does this API exist in the detected version?** If you're unsure, prefer the newer pattern.
492. **Is this a Xamarin.Forms API?** MAUI is a different API surface — never assume Xamarin.Forms compatibility.
503. **Is this in the deprecated table below?** If so, use the replacement.
514. **Am I using the Compatibility namespace?** `Microsoft.Maui.Controls.Compatibility.*` types are migration aids, not recommended for new code.
52
53### Step 4 — Apply Decision Rules
54
55- **Always use the newest form** of an API when both old and new exist.
56- **Never generate `using Xamarin.Forms`** or `using Xamarin.Essentials` — these are not MAUI.
57- **Never use the `Compatibility` namespace** in new projects (`Compatibility.RelativeLayout`, `Compatibility.StackLayout`, etc.).
58- **Prefer `async` method names** when both sync-named and async-named versions exist (e.g., `DisplayAlertAsync` over `DisplayAlert`).
59- **Check the project's NuGet versions** before using CommunityToolkit or third-party APIs.
60
61---
62
63## Deprecated API Table — .NET MAUI 10
64
65### Controls
66
67| ❌ Deprecated / Removed | ✅ Use Instead | Notes |
68|--------------------------|----------------|-------|
69| `ListView` | `CollectionView` | `ListView`, `EntryCell`, `ImageCell`, `SwitchCell`, `TextCell`, `ViewCell`, and `Cell` are all deprecated in .NET 10 |
70| `TableView` | `CollectionView` or custom layout | Deprecated in .NET 10 |
71| `Frame` | `Border` | `Frame` is a Xamarin.Forms legacy control; `Border` is the MAUI replacement with `StrokeShape` support |
72| `Compatibility.RelativeLayout` | `Grid` | Migration-only; removed from templates in .NET 10 |
73| `Compatibility.StackLayout` | `VerticalStackLayout` / `HorizontalStackLayout` | The compatibility `StackLayout` wraps Xamarin layout logic. Use the native MAUI stack layouts for better performance |
74
75### Gestures & Input
76
77| ❌ Deprecated / Removed | ✅ Use Instead | Notes |
78|--------------------------|----------------|-------|
79| `ClickGestureRecognizer` | `TapGestureRecognizer` | Removed in .NET 10 |
80| `Accelerator` | `KeyboardAccelerator` | Removed from `Microsoft.Maui.Controls` in .NET 10 |
81
82### Page & Navigation
83
84| ❌ Deprecated / Removed | ✅ Use Instead | Notes |
85|--------------------------|----------------|-------|
86| `Page.IsBusy` | `ActivityIndicator` | `IsBusy` is obsolete in .NET 10; use an explicit activity indicator |
87| `DisplayAlert()` | `DisplayAlertAsync()` | Sync-named versions deprecated; use async versions |
88| `DisplayActionSheet()` | `DisplayActionSheetAsync()` | Same as above |
89| `MessagingCenter` | `WeakReferenceMessenger` (CommunityToolkit.Mvvm) | Made internal in .NET 10 |
90
91### Animation
92
93| ❌ Deprecated / Removed | ✅ Use Instead | Notes |
94|--------------------------|----------------|-------|
95| `FadeTo()` | `FadeToAsync()` | All animation extension methods renamed to `*Async` in .NET 10 |
96| `RotateTo()`, `ScaleTo()`, `TranslateTo()`, etc. | `RotateToAsync()`, `ScaleToAsync()`, `TranslateToAsync()`, etc. | Same pattern — `RelRotateTo` → `RelRotateToAsync`, `RelScaleTo` → `RelScaleToAsync`, `LayoutTo` → `LayoutToAsync` |
97
98### Device & Platform APIs
99
100| ❌ Deprecated / Removed | ✅ Use Instead | Notes |
101|--------------------------|----------------|-------|
102| `Device.RuntimePlatform` | `DeviceInfo.Platform` | The entire `Device` class is deprecated |
103| `Device.BeginInvokeOnMainThread()` | `MainThread.BeginInvokeOnMainThread()` | Use `Microsoft.Maui.ApplicationModel.MainThread` |
104| `Device.InvokeOnMainThreadAsync()` | `MainThread.InvokeOnMainThreadAsync()` | Same |
105| `Device.OpenUri()` | `Launcher.OpenAsync()` | Use `Microsoft.Maui.ApplicationModel.Launcher` |
106| `Device.StartTimer()` | `Dispatcher.StartTimer()` or `PeriodicTimer` | Use the dispatcher or standard .NET timer |
107| `DependencyService` | Constructor injection via `IServiceProvider` | Register services in `MauiProgram.cs` with `builder.Services` |
108
109### XAML & Markup
110
111| ❌ Deprecated / Removed | ✅ Use Instead | Notes |
112|--------------------------|----------------|-------|
113| `FontImageExtension` (XAML markup extension) | `FontImageSource` (type) | Use `<FontImageSource>` element or property syntax |
114| `Color.FromHex()` | `Color.FromArgb()` | `FromHex` is obsolete |
115
116### Safe Area & Layout
117
118| ❌ Deprecated / Removed | ✅ Use Instead | Notes |
119|--------------------------|----------------|-------|
120| `Page.UseSafeArea` (iOS platform-specific) | `SafeAreaEdges` property | New in .NET 10; `ContentPage` defaults to `None` (edge-to-edge) on all platforms |
121| `Layout.IgnoreSafeArea` | `SafeAreaEdges` property | Use the unified safe area API |
122
123### Accessibility
124
125| ❌ Deprecated / Removed | ✅ Use Instead | Notes |
126|--------------------------|----------------|-------|
127| `AutomationProperties.Name` | `SemanticProperties.Description` | `AutomationProperties` still works but `SemanticProperties` is the MAUI-native approach |
128| `AutomationProperties.HelpText` | `SemanticProperties.Hint` | Same |
129| iOS `SetAccessibilityHint` / `SetAccessibilityLabel` (Compatibility extensions) | `Microsoft.Maui.Platform.UpdateSemantics()` | Deprecated in .NET 10 |
130
131### NuGet Packages
132
133| ❌ Deprecated Package | ✅ Use Instead | Notes |
134|------------------------|----------------|-------|
135| `Xamarin.Forms` | `Microsoft.Maui.Controls` | Completely different API surface |
136| `Xamarin.Essentials` | Built-in MAUI APIs (`Microsoft.Maui.Devices`, `Microsoft.Maui.ApplicationModel`, etc.) | Essentials is merged into MAUI |
137| `Xamarin.CommunityToolkit` | `CommunityToolkit.Maui` | Different namespace and API surface |
138| `Microsoft.Toolkit.Mvvm` | `CommunityToolkit.Mvvm` | Package was renamed |
139
140---
141
142## MauiReactor-Specific Guidance
143
144MauiReactor v3+ (for .NET MAUI 9/10):
145
146- **Hot reload**: v3+ uses a feature switch in `.csproj` via `<RuntimeHostConfigurationOption>`. Do NOT use the v2 `EnableMauiReactorHotReload()` call in `MauiProgram.cs`.
147- **API wrappers**: MauiReactor auto-generates C# wrappers around MAUI controls. When a MAUI control is deprecated (e.g., `ListView`), the MauiReactor wrapper is also effectively deprecated. Use the MauiReactor wrapper for the replacement control (e.g., `CollectionView`).
148- **State management**: Use `State<T>` and `Props<T>` — not older `RxComponent` patterns if they appear in outdated examples.
149- **Navigation**: Use MauiReactor's built-in navigation (`Navigation.PushAsync<PageComponent>()`) — do NOT mix in MAUI Shell `GoToAsync` unless deliberately integrating Shell.
150
151---
152
153## Blazor Hybrid-Specific Guidance
154
155- Use **`BlazorWebView`** — not the legacy `WebView` — for hosting Razor components.
156- Use **.NET 10 Razor syntax**: `@rendermode` directives, `[SupplyParameterFromQuery]`, and the latest component model.
157- **JS interop**: Use `IJSRuntime.InvokeAsync<T>()` — not the obsolete synchronous `IJSInProcessRuntime` patterns for mobile.
158- **Safe areas**: In Blazor Hybrid, use CSS `env(safe-area-inset-*)` — do NOT combine XAML `SafeAreaEdges` and CSS safe area padding on the same element (causes double-padding).
159- **Web resource interception**: .NET 10 adds `WebResourceRequested` event on `BlazorWebView` and `HybridWebView` for intercepting requests.
160
161---
162
163## Version Detection Cheat Sheet
164
165### Reading the TFM
166
167| TFM Pattern | .NET Version |
168|-------------|-------------|
169| `net10.0-*` | .NET 10 (latest, current) |
170| `net9.0-*` | .NET 9 |
171| `net8.0-*` | .NET 8 (LTS) |
172
173### Reading MAUI SDK Version
174
175If the `.csproj` uses `<UseMaui>true</UseMaui>`, the MAUI version matches the TFM:
176- `net10.0` → MAUI 10
177- `net9.0` → MAUI 9
178
179### Reading MauiReactor Version
180
181Check `<PackageReference Include="Reactor.Maui" Version="X.Y.Z" />`:
182- v3.x → .NET MAUI 9/10 compatible, uses feature-switch hot reload
183- v2.x → Legacy, uses `EnableMauiReactorHotReload()` builder pattern
184
185### Reading CommunityToolkit Version
186
187Check `<PackageReference Include="CommunityToolkit.Maui" Version="X.Y.Z" />`:
188- v11+ → .NET 10 compatible
189- v9-10 → .NET 9 compatible
190- v5-7 → .NET 8 compatible
191
192---
193
194## Quick Rules
195
1961. **Read the `.csproj` first.** Never generate code without knowing the target framework.
1972. **When in doubt, use the newer API.** If two ways exist to do something, the newer way is correct.
1983. **Never use `Xamarin.*` namespaces.** They do not exist in MAUI.
1994. **Never use `Compatibility.*` types in new projects.** They are migration aids only.
2005. **Check this table before using any `Device.*` API.** The `Device` class is fully deprecated.
2016. **Use `*Async` method names** for animations, alerts, and action sheets in .NET 10+.
2027. **Verify third-party package versions** before using their APIs — CommunityToolkit, MauiReactor, and others break between major versions.
majiayu000