Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 42 ยท Getting Started

What Is .NET MAUI?

Learn what .NET MAUI is, which platforms it targets, how one C# codebase becomes Android, iOS, macOS and Windows apps, and what you can run on this site.

.NET MAUI (Multi-platform App UI) is Microsoft's framework for building native apps for Android, iOS, macOS and Windows from a single C# project. You describe screens in XAML (an XML-based markup language) or in plain C#, you write logic in C#, and the framework turns your controls into the real controls of each operating system: a Button becomes an Android MaterialButton, an iOS UIButton and a WinUI Button.

MAUI is the successor of Xamarin.Forms. It keeps the same ideas (pages, layouts, data binding, MVVM) but merges everything into one project with one set of resources, runs on modern .NET, and replaces the old "renderers" with lighter objects called handlers. If you already know C# (see the C# tutorial), this track teaches you the rest.

Honesty note. .NET MAUI needs the .NET SDK with mobile workloads, Android or Apple toolchains, and a real device or emulator. None of that can run in a browser or on this site's code runner. In this track, the real MAUI code (XAML and C# you would put in a MAUI project) is shown in read-only blocks, and I only show output when I am certain of it. Next to it you get runnable C# stand-ins that are labelled as such: small programs that demonstrate the underlying ideas (property change notification, layout math, commands, dependency injection) with plain C#. A stand-in is not MAUI; it shows how the idea works inside MAUI.

One codebase, four platforms

A MAUI app targets these platforms:

Platform Native toolkit used underneath Built on
Android Android views .NET for Android
iOS UIKit .NET for iOS
macOS UIKit through Mac Catalyst .NET for Mac Catalyst
Windows WinUI 3 Windows App SDK

Linux is not an official target. Building for iOS and macOS needs a Mac (a Windows machine can pair with one for iOS builds), while Android and Windows can be built on Windows.

flowchart TD
    A["Your code<br/>XAML + C#"] --> B["MAUI controls<br/>Button, Label, Entry"]
    B --> C["Handlers"]
    C --> D["Android views"]
    C --> E["UIKit (iOS, macOS)"]
    C --> F["WinUI 3"]

Your code talks to MAUI controls; handlers translate them to each platform's native controls.

What a MAUI app looks like

Here is a complete page, read-only. A label, a button and a click handler:

XML
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="HelloApp.MainPage">
    <VerticalStackLayout Padding="24" Spacing="12">
        <Label x:Name="Greeting" Text="Hello, MAUI!" FontSize="24" />
        <Button Text="Click me" Clicked="OnClicked" />
    </VerticalStackLayout>
</ContentPage>
C#
namespace HelloApp;

public partial class MainPage : ContentPage
{
    private int count;

    public MainPage() => InitializeComponent();

    private void OnClicked(object? sender, EventArgs e)
    {
        count++;
        Greeting.Text = $"Clicked {count} time(s)";
    }
}

The XAML file declares the page's structure; the C# file (called code-behind) is a partial class that finishes the same class. InitializeComponent() builds the controls described in the XAML. You will study each part in the next lessons: XAML basics, layouts and data binding.

The idea behind handlers

Every MAUI control (Button, Label...) is a cross-platform virtual view: it holds properties like Text and TextColor but draws nothing itself. For each control MAUI creates a handler that owns the real native control and copies property values to it. A mapper is the table that says "when Text changes, call this code to update the native control".

The stand-in below shows the pattern with plain C#. A VirtualButton holds a property; a mapper table updates a fake "native" widget for each platform.

C# Stand-in: the handler and mapper pattern

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The real MAUI mapper is more refined (it is static, can be customised per control, and batches updates), but the flow is the same: view property changes, handler pushes the value to the native control. Later, in the platform features chapter, you will customise handlers for your own needs.

What MAUI gives you

  • Pages and navigation: ContentPage, NavigationPage, TabbedPage, FlyoutPage and Shell, a single place to define app structure and URL-like routes.
  • Layouts: VerticalStackLayout, HorizontalStackLayout, Grid, FlexLayout, AbsoluteLayout.
  • Controls: labels, buttons, entries, pickers, sliders, switches, CollectionView, Image, WebView, maps and more.
  • Data binding and MVVM: connect UI properties to your objects, and commands to buttons.
  • Platform APIs: one set of interfaces for connectivity, geolocation, sensors, secure storage, file picking, sharing and more.
  • Resources: one Resources folder for images, fonts, app icon, splash screen and raw files. MAUI resizes and converts them for each platform.
  • Hot Reload: change XAML or C# while the app runs and see the effect without a full rebuild.
  • Blazor Hybrid: host web UI built with Razor components inside a native app.

When to choose MAUI

MAUI suits business apps, internal tools, forms-over-data apps and companion apps where one C# team wants to share code. It is less suited to games (use an engine such as Godot or Unity) or to apps that need a pixel-identical custom look on every platform at the cost of native feel. Compared with other options: Flutter and React Native use other languages; Uno Platform is another C#/XAML option; a web app (PWA) needs no store at all. The right choice depends on your team's skills.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does .NET MAUI produce when you build for Android?

    MAUI handlers map each cross-platform control to the native Android control, so the result is a normal native app.
  2. 2. Which framework is MAUI the successor of?

    MAUI evolved from Xamarin.Forms, merging platform projects into one single project.
  3. 3. What is the job of a handler?

    A handler owns the native control and copies property values from the virtual view to it, using a mapper.
  4. 4. Which platform is NOT an official MAUI target?

    MAUI targets Android, iOS, macOS (Mac Catalyst) and Windows. Linux is not officially supported.

Summary

  • .NET MAUI builds native Android, iOS, macOS and Windows apps from one C# project.
  • UI is written in XAML or C#; handlers turn MAUI controls into native controls.
  • It succeeds Xamarin.Forms and runs on modern .NET.
  • The real framework cannot run on this site, so MAUI code is read-only and the runnable examples are labelled C# stand-ins.

Next: Setting Up and Creating Your First App