Introduction to .NET MAUI: Build One App for Every Platform

Introduction to .NET MAUI
This post is part 1 of 11 in the series Mastering .NET MAUI: From Beginner to Pro

Did you know Microsoft quietly glued “all the things” together so you can ship a single codebase to Android, iOS, macOS, and Windows—without the hair‑pulling build scripts we used to write? If that prospect makes your architect’s heart beat faster, welcome to .NET MAUI, the successor to Xamarin.Forms and the cross‑platform UI stack that has finally grown up.

What exactly is .NET MAUI?

.NET Multi‑platform App UI (MAUI) is Microsoft’s official, open‑source framework for building native mobile and desktop apps with C# and XAML from one shared project. Under the hood it offers:

  • Single‑project system that multi‑targets Android, iOS, macOS, and Windows
  • .NET Hot Reload for on‑device tweaks
  • First‑class access to every platform API when you need to drop to native code

What’s in the box?

PillarWhy it matters to you
Single ProjectOne .csproj, shared resources, per‑platform folders only when required. Goodbye, Franken‑solution.
Native UIEach control renders as its real native counterpart—no web views in sight.
Hot ReloadEdit XAML/C# on a running device and see changes instantly—perfect for UX polish.
ToolingVisual Studio 2022/2025, VS Code w/ CLI templates, and a rapidly growing ecosystem.

Why should you care?

Xamarin.Forms sunset & future‑proofing

Xamarin.Forms went out of support in May 2024. MAUI is the officially blessed migration path, shares the same mental model, and is actively serviced on the monthly .NET cadence.

Performance & size gains in .NET 9

The .NET 9 wave focused almost exclusively on MAUI reliability: hundreds of bug fixes, revamped CollectionView/CarouselView, and Native AOT + aggressive trimming that can halve cold‑start time on Android.

Ship everywhere, faster

Nailing parity across four OSes used to require four dev teams (or a mountain of conditional compilation). MAUI’s single‑project, multi‑targeting build pipeline does the grunt work so you stay in feature land.

Familiar patterns

MVVM, dependency‑injection, and .NET Standard libraries all work out of the box, meaning the jump from WPF/Blazor to MAUI feels refreshingly boring—in the best possible way.

How to get started (the 20‑minute tour)

Prerequisites

  • Windows 11 + Visual Studio 2022 v17.10 or macOS 14 + VS for Mac 17.8
  • .NET SDK 9.0 Preview (or 8.0 LTS if you need production today)
  • Emulators / real devices for your target platforms

CLI Quick‑start

dotnet new maui -n HelloMaui
cd HelloMaui
dotnet build -t:Run -f net9.0-ios

Exploring the single‑project anatomy

HelloMaui/
 ├─ Platforms/
 │   ├─ Android/      # Android‑only tweaks (e.g., MainActivity.cs)
 │   ├─ iOS/
 │   ├─ MacCatalyst/
 │   └─ Windows/
 ├─ Resources/        # One place for fonts, images, splash, raw assets
 ├─ MainPage.xaml
 └─ MauiProgram.cs    # DI container & root services

From Zero to “Wow”: your first page

Here’s a bite‑sized counter app demonstrating data binding, commands, and MVVM—all in ~40 lines:

MainPage.xaml

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             x:Class="HelloMaui.MainPage"
             xmlns:local="clr-namespace:HelloMaui">
    <ContentPage.BindingContext>
        <local:MainPageViewModel/>
    </ContentPage.BindingContext>

    <VerticalStackLayout Spacing="25" Padding="30">
        <Label Text="Welcome to .NET MAUI!"
               FontSize="32" HorizontalOptions="Center"/>
        <Button Text="{Binding ClickMeText}"
                Command="{Binding IncrementCommand}" />
        <Label Text="{Binding CounterDisplay}"
               FontSize="18" HorizontalOptions="Center"/>
    </VerticalStackLayout>
</ContentPage>

MainPageViewModel.cs

public class MainPageViewModel : ObservableObject
{
    private int _count;
    public string ClickMeText => "Click me";
    public string CounterDisplay => $"Clicked {_count} time(s)";

    public IRelayCommand IncrementCommand => new RelayCommand(() =>
    {
        _count++;
        OnPropertyChanged(nameof(CounterDisplay));
    });
}

Run on Android, swap the target to -f net9.0-windows, and you’ll see the exact UI pop on Windows—same code, native look & feel.

MAUI ecosystem cheat sheet

  • Community Toolkit – drop‑in Snackbar, Popup, MediaElement, and more.
  • Syncfusion / DevExpress / Grial – 130+ polished enterprise controls (DataGrid, PDF viewer, Charts).
  • Essentials API – geolocation, secure storage, sensors—wrapped in a single Microsoft.Maui.Essentials namespace.
  • Native AOT – turn on a single MSBuild flag and watch your Android APK shrink by 30 %.

Tip: run dotnet workload update monthly—the MAUI team ships hotfixes on the normal .NET servicing train.

Common pitfalls (& how I learned them the hard way)

GotchaQuick Fix
VS Android designer shows blank page after Hot ReloadClear the Android device’s Data & Cache for your app; broken resource hash will be rebuilt.
Windows build size explodesEnable PublishTrimmed=true and PublishAot=true only for Release; tool chain is slow but worth it.
iOS linker strips your reflection codeAdd [Preserve(AllMembers = true)] or wildcard linker config in Properties\LinkerConfiguration.xml.

FAQ: Getting started with .NET MAUI

Do I need a Mac to build for iOS?

Yes, but you can pair to a networked Mac from Windows Visual Studio—no keyboard swapping required.

Is Blazor Hybrid the same thing?

Think of Blazor Hybrid as MAUI hosting a WebView that renders Razor components. You still get native menus, notifications, and packaging.

How long will MAUI 8.0 be supported?

.NET 8 is an LTS release, so MAUI 8 receives critical fixes until November 2026. .NET 9/10 are STS (18‑month) cadences.

Can I reuse existing Xamarin.Forms pages?

In most cases, yes. Run the official Upgrade Assistant, then migrate to the single‑project layout and address namespace changes.

Conclusion: Your cross‑platform playground awaits

With a mature single‑project system, native controls, and the performance TLC baked into .NET 9, MAUI finally delivers on the “write once, ship everywhere” dream—minus the compromises. Ready to ditch four codebases for one? Spin up that dotnet new maui today and share your first impressions in the comments below!

Leave a Reply

Your email address will not be published. Required fields are marked *