Guide .NET MAUI

An expert agent for .NET MAUI cross-platform application development, enforcing modern API usage, performance best practices, and platform-specific considerations for iOS, Android, Windows, and macOS applications.

When to Use This Agent

Choose .NET MAUI Guide when:

• Building cross-platform mobile and desktop apps with .NET MAUI
• Migrating from Xamarin.Forms to .NET MAUI
• Implementing platform-specific features with proper abstractions
• Optimizing MAUI app performance and startup time
• Designing MVVM architectures with MAUI-specific patterns

Consider alternatives when:

• Building web applications (use ASP.NET or Blazor agents)
• Developing native iOS/Android apps without cross-platform needs
• Working with Flutter or React Native instead of .NET

Quick Start

Copy
# .claude/agents/guide-dotnet-maui.yml
name: .NET MAUI Guide
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a .NET MAUI expert. Build high-quality cross-platform
  applications following modern .NET MAUI practices.
  CRITICAL RULES:
  - NEVER use ListView (obsolete) → use CollectionView
  - NEVER use TableView (obsolete) → use Grid/VerticalStackLayout
  - NEVER use AndExpand layout options (obsolete)
  - NEVER use BackgroundColor → use Background
  - Always use CommunityToolkit.Mvvm for MVVM patterns

Example invocation:

Copy
claude --agent guide-dotnet-maui "Create a product catalog page
  with CollectionView, pull-to-refresh, infinite scrolling, and
  platform-specific styling for iOS and Android"

Core Concepts

Deprecated vs Modern API Reference

Deprecated (Never Use)	Modern Replacement	Reason
ListView	CollectionView	Better performance, virtualization
TableView	Grid / VerticalStackLayout	More flexible, composable
AndExpand options	Grid with star sizing	Removed in MAUI
BackgroundColor	Background	Supports gradients, brushes
Device.RuntimePlatform	DeviceInfo.Platform	New API surface
Device.BeginInvokeOnMainThread	MainThread.BeginInvokeOnMainThread	Namespace change
Xamarin.Essentials	Microsoft.Maui.Essentials	Integrated in MAUI

MVVM Architecture with CommunityToolkit

Copy
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

public partial class ProductsViewModel : ObservableObject
{
    [ObservableProperty]
    private ObservableCollection<Product> _products = new();

    [ObservableProperty]
    [NotifyPropertyChangedFor(nameof(HasProducts))]
    private bool _isLoading;

    public bool HasProducts => Products.Count > 0;

    [RelayCommand]
    private async Task LoadProductsAsync()
    {
        IsLoading = true;
        var items = await _productService.GetProductsAsync();
        Products = new ObservableCollection<Product>(items);
        IsLoading = false;
    }

    [RelayCommand]
    private async Task RefreshAsync()
    {
        await LoadProductsAsync();
    }
}

Platform-Specific Code Pattern

Copy
// Use partial classes for platform-specific behavior
public partial class CameraService
{
    public partial Task<Stream> CapturePhotoAsync();
}

// Platforms/Android/CameraService.cs
public partial class CameraService
{
    public partial async Task<Stream> CapturePhotoAsync()
    {
        // Android-specific camera implementation
    }
}

// Platforms/iOS/CameraService.cs
public partial class CameraService
{
    public partial async Task<Stream> CapturePhotoAsync()
    {
        // iOS-specific camera implementation
    }
}

Configuration

Parameter	Description	Default
target_frameworks	Target platforms	iOS, Android, Windows
min_ios_version	Minimum iOS deployment target	15.0
min_android_version	Minimum Android API level	24
mvvm_toolkit	MVVM framework	CommunityToolkit.Mvvm
di_container	Dependency injection setup	Built-in MAUI DI
navigation	Navigation pattern	Shell
image_handling	Image loading library	Built-in + caching

Best Practices

1. Use CollectionView for all list displays, never ListView. CollectionView provides built-in virtualization, selection modes, empty views, and layout flexibility that ListView lacks. It supports linear, grid, and custom layouts through a single control. ListView is marked obsolete and will be removed. Migrate existing ListViews proactively rather than waiting for breaking changes.

2. Register services and view models in MauiProgram.cs. Use the built-in dependency injection container for all service and view model registration. Register view models as transient and services as singleton or scoped based on their state requirements. This approach enables constructor injection throughout the app and makes testing straightforward with mock substitution.

3. Optimize startup time by deferring non-critical work. App startup directly impacts user perception. Load only essential UI and data during startup. Defer analytics initialization, background sync, and non-visible content loading until after the first screen renders. Use Loaded events rather than constructors for page initialization work.

4. Handle platform differences through partial classes and handlers. Use #if preprocessor directives sparingly—they make code hard to read and test. Instead, use partial class methods that have platform-specific implementations in the Platforms folders. For UI customization, use Handlers to modify native control behavior without subclassing.

5. Implement proper lifecycle management in view models. Views and view models in MAUI can be created and destroyed as users navigate. Use IDisposable to clean up event subscriptions and timers. Cancel ongoing async operations when the page disappears using CancellationTokenSource. Failing to manage lifecycle causes memory leaks and background work on invisible pages.

Common Issues

CollectionView items don't update when the underlying data changes. Use ObservableCollection<T> and ensure your model implements INotifyPropertyChanged (or uses [ObservableProperty] from CommunityToolkit.Mvvm). Replacing the entire collection reference triggers a full refresh; for individual item updates, modify properties on existing objects rather than replacing them in the collection.

App startup is slow on Android. Android startup involves JIT compilation that doesn't affect iOS (which uses AOT). Enable trimming and AOT compilation in the release configuration. Remove unused NuGet packages, as each assembly adds to startup time. Profile startup with dotnet-trace to identify the slowest initialization code and defer or parallelize it.

Platform-specific styling breaks on different OS versions. Test on the minimum supported OS version, not just the latest. Use OnPlatform and OnIdiom markup extensions for XAML styling differences. Avoid hardcoded dimensions—use relative sizing with Grid star columns and rows. When native controls render differently across platforms, use Handlers to customize the native appearance consistently.