# Xamarin Forms Migration

> >

- **Type:** Skill
- **Install:** `agentstack add skill-davidortinau-maui-skills-xamarin-forms-migration`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [davidortinau](https://agentstack.voostack.com/s/davidortinau)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [davidortinau](https://github.com/davidortinau)
- **Source:** https://github.com/davidortinau/maui-skills/tree/main/plugins/maui-skills/skills/xamarin-forms-migration

## Install

```sh
agentstack add skill-davidortinau-maui-skills-xamarin-forms-migration
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Xamarin.Forms → .NET MAUI Migration

For project templates, namespace tables, API deprecation tables, and reference code, see `references/forms-migration-api.md`.

> ⚠️ **Do not use the .NET Upgrade Assistant.** Apply namespace renames, project file updates, and package replacements directly. Build after each batch of changes and use compiler errors to guide the next round of fixes.

## Migration Workflow

1. Create new .NET MAUI project (**single-project** — multi-project causes AOT/build errors)
2. Copy cross-platform code + platform code into `Platforms//`
3. Update namespaces (XAML + C# + Essentials — see `references/forms-migration-api.md`)
4. Fix layout behavior changes (see below)
5. Migrate renderers → handlers (not shimmed renderers)
6. Migrate effects → behaviors
7. **Remove** `Microsoft.Maui.Controls.Compatibility` package
8. Update NuGet dependencies
9. Migrate app data stores
10. Delete `bin/`/`obj/`/`Resource.designer.cs`, build, test iteratively
11. Verify against .NET 10 deprecated API list

> **Strategy:** Create a new project and copy code into it — don't edit the existing project file in place.

## Critical Layout Pitfalls

### ⚠️ Default Spacing Changed to Zero

MAUI zeroes out spacing that Xamarin.Forms set to 6. Your layouts **will break silently**:

```xml

...
...

    
    

```

> **Field advice:** Specify all layout values explicitly — don't rely on platform defaults.

### ⚠️ `*AndExpand` Is Obsolete — No Silent Warning

```xml

    
    

    
    

```

> **Field advice:** Flatten layout trees. Replace nested hierarchies with single Grid layouts.

### ⚠️ ScrollView in StackLayout Doesn't Scroll

ScrollView inside StackLayout expands to full content height (no scroll). Place `ScrollView` in a `Grid` with a constrained row instead.

### Other Layout Traps

| Issue | Fix |
|-------|-----|
| Grid columns/rows not declared → layout broken | Always add explicit `ColumnDefinitions`/`RowDefinitions` |
| `Frame` measures differently | Migrate to `Border` with `StrokeShape` |
| `BoxView` invisible (default 0×0 in MAUI) | Set explicit `WidthRequest`/`HeightRequest` |
| `RelativeLayout` | Replace with `Grid` (compatibility namespace only) |

## Renderer → Handler Migration

> ⚠️ **Migrate all renderers to handlers. Do NOT use shimmed renderers** — they create parent wrapper views that hurt performance.

**Preferred: Customize existing handlers with mapper methods:**

```csharp
// ✅ Extend existing handler — no new class needed
Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("NoBorder", (handler, view) =>
{
#if ANDROID
    handler.PlatformView.Background = null;
#elif IOS || MACCATALYST
    handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
#endif
});
```

For completely new native views, create a full handler (see **maui-custom-handlers** skill).

## Effects → Behaviors

> ⚠️ **Effects are now Behaviors — this requires redesign, not just renaming.**

For new development, prefer behaviors or handler mapper customizations over effects.

## ⚠️ Do NOT Use the Compatibility Package

`Microsoft.Maui.Controls.Compatibility` causes cascading incompatibilities. Remove it and rebuild layouts natively.

## Retired Dependencies

- **App Center** is retired → Replace with Sentry, Azure Monitor, or similar
- **Visual Studio for Mac** is retired → Use VS Code or Rider

## Android-Specific Warnings

- Android migration is **significantly harder** than iOS — expect more UI bugs
- OEM-specific rendering differences not reproducible on emulators — **test on physical devices**
- Shadow rendering varies across OEMs/API levels — implement in platform-specific handler code
- Handler-level property changes don't auto-update on theme switch — manually handle theme changes

## .NET 10 API Currency Warning

Migration is the perfect time to skip deprecated APIs entirely. Don't migrate Xamarin.Forms code to a MAUI API that's already on its way out. See the full deprecated API table in `references/forms-migration-api.md` and run the **maui-current-apis** skill.

## Common Troubleshooting

| Issue | Fix |
|-------|-----|
| `Xamarin.*` namespace doesn't exist | Update to `Microsoft.Maui.*` equivalent |
| CollectionView doesn't scroll | Place in Grid (not StackLayout) to constrain size |
| Pop-up under page on iOS | Use `DisplayAlert` from the `ContentPage` |
| Missing padding/margin/spacing | Add explicit values or implicit styles |
| Custom renderer broken | Migrate to handler |
| SkiaSharp broken | Update to `SkiaSharp.Views.Maui` package |
| Can't access App.Properties data | Migrate to `Preferences` |

## Quick Checklist

1. ☐ Created new .NET MAUI project (single-project)
2. ☐ Copied cross-platform and platform code
3. ☐ Updated XAML namespace to `http://schemas.microsoft.com/dotnet/2021/maui`
4. ☐ Replaced `Xamarin.Forms.*` → `Microsoft.Maui.*` namespaces
5. ☐ Replaced `Xamarin.Essentials` → split MAUI namespaces
6. ☐ Added explicit Grid `ColumnDefinitions`/`RowDefinitions`
7. ☐ Replaced `*AndExpand` with Grid layouts
8. ☐ Added explicit spacing/padding values (MAUI defaults to 0)
9. ☐ Migrated renderers to handlers (not shimmed renderers)
10. ☐ Migrated effects to behaviors or MAUI effects
11. ☐ Removed `Microsoft.Maui.Controls.Compatibility` package
12. ☐ Updated NuGet dependencies for .NET compatibility
13. ☐ Migrated App.Properties, SecureStorage, VersionTracking data
14. ☐ Deleted `bin/`, `obj/`, and `Resource.designer.cs`
15. ☐ Tested on physical Android device
16. ☐ Profiled performance
17. ☐ Verified no .NET 10 deprecated APIs (run **maui-current-apis** skill)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [davidortinau](https://github.com/davidortinau)
- **Source:** [davidortinau/maui-skills](https://github.com/davidortinau/maui-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-davidortinau-maui-skills-xamarin-forms-migration
- Seller: https://agentstack.voostack.com/s/davidortinau
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.