Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 42 ยท Getting Started

Setting Up and Creating Your First App

Install the .NET SDK and MAUI workload, create a project with Visual Studio or the dotnet CLI, run it on Android, Windows, iOS or macOS, and understand the click-counter template.

To build MAUI apps you install three things: the .NET SDK, the MAUI workload (the extra build tools and platform libraries), and the toolchain of every platform you want to run on. This lesson walks through the setup on Windows and macOS, creates a first app, and explains the click-counter template that every new MAUI project starts with.

MAUI itself does not run on this site. Commands and MAUI code below are read-only. The runnable block at the end is a labelled C# stand-in for the template's click-counter logic.

What to install

You want to run on You need
Windows Windows 10 (version 1809 or later) or Windows 11, Visual Studio 2022 or 2026 with the .NET Multi-platform App UI development workload
Android The Android SDK and an emulator or a phone with USB debugging (Visual Studio installs these for you)
iOS A Mac with Xcode (a Windows machine can connect to it for builds)
macOS (Mac Catalyst) A Mac with Xcode

You can use Visual Studio (Windows, the most complete experience), Visual Studio Code with the C# Dev Kit and .NET MAUI extensions (Windows, macOS, Linux for editing), or JetBrains Rider. All use the same dotnet command underneath.

To check the SDK and install the workload from a terminal:

Terminal
dotnet --version
dotnet workload install maui
dotnet workload list

The first command prints the installed SDK version. The second downloads the MAUI workload (this is several gigabytes the first time). The third lists what is installed. On Windows, dotnet workload install maui installs the Android, iOS, Mac Catalyst and Windows pieces together; on macOS it installs Android, iOS and Mac Catalyst.

If something does not work, run dotnet workload repair and, for Android, check the SDK location and the emulator in Visual Studio's Android Device Manager.

Creating a project

With Visual Studio, choose Create a new project, search for .NET MAUI App, name it and confirm the .NET version. From the command line:

Terminal
dotnet new maui -n HelloMaui
cd HelloMaui
dotnet build -t:Run -f net10.0-android

dotnet new maui uses the template named maui. The -f option (target framework) picks the platform. Typical values are:

  • net10.0-android
  • net10.0-ios
  • net10.0-maccatalyst
  • net10.0-windows10.0.19041.0

The number after net is the .NET version your project uses; use the version your SDK targets. You can also create a MAUI class library with dotnet new mauilib and a Blazor Hybrid app with dotnet new maui-blazor.

Run the app on Windows first when you develop on a Windows PC. It starts quickly, needs no emulator, and is perfect for learning XAML and binding. Add Android once the screens work.

The template app

The template gives you one page with an image, two labels and a button. This is its XAML (shortened, read-only):

XML
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="HelloMaui.MainPage">
    <ScrollView>
        <VerticalStackLayout Padding="30,0" Spacing="25">
            <Label Text="Hello, World!" Style="{StaticResource Headline}" />
            <Label Text="Welcome to .NET MAUI" Style="{StaticResource SubHeadline}" />
            <Button x:Name="CounterBtn"
                    Text="Click me"
                    Clicked="OnCounterClicked"
                    HorizontalOptions="Fill" />
        </VerticalStackLayout>
    </ScrollView>
</ContentPage>

and the code-behind:

C#
namespace HelloMaui;

public partial class MainPage : ContentPage
{
    int count = 0;

    public MainPage() => InitializeComponent();

    private void OnCounterClicked(object? sender, EventArgs e)
    {
        count++;

        CounterBtn.Text = count == 1
            ? $"Clicked {count} time"
            : $"Clicked {count} times";

        SemanticScreenReader.Announce(CounterBtn.Text);
    }
}

Three things to notice:

  1. x:Class="HelloMaui.MainPage" ties the XAML to the C# class of the same name.
  2. x:Name="CounterBtn" creates a field you can use from code-behind.
  3. Clicked="OnCounterClicked" wires the event to a method.

SemanticScreenReader.Announce tells screen readers (TalkBack, VoiceOver, Narrator) about the new text, a good habit for accessibility. We will return to it in the XAML lessons.

Run, debug and Hot Reload

Press F5 in Visual Studio after picking a target (Windows Machine, an Android emulator, or an iOS simulator). The first build is slow; later builds are incremental. While the app runs:

  • XAML Hot Reload applies XAML edits immediately.
  • .NET Hot Reload applies many C# edits without restarting.
  • The Live Visual Tree shows the control tree of the running page, and Live Property Explorer shows properties of the selected control.

Breakpoints, the debugger and the Output window work as in any .NET app. Platform logs appear in the Output window (Android uses Logcat).

The click-counter, as a stand-in

The code-behind above is just C# logic: an integer, a text rule and an event. You can run exactly that logic as a plain console program. The block below is a stand-in: FakeButton imitates the part of MAUI's Button we need (a Text property and a Clicked event) so that the same OnCounterClicked method works unchanged.

C# Stand-in: the click counter logic

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 method body is the same as in the real page. This is the first idea to keep: MAUI code-behind is ordinary C#, and much of your logic can be tested without a UI. In the MVVM chapter you will move this state out of the page entirely.

Common setup problems

  • "Workload not installed": run dotnet workload install maui and restart the IDE.
  • Android emulator will not start: enable hardware acceleration (Hyper-V or the Windows Hypervisor Platform on Windows) and check that virtualisation is on in BIOS.
  • iOS build fails on Windows: pair with a Mac build host and make sure Xcode was opened once to accept its licence.
  • Windows build says "Developer Mode": turn on Developer Mode in Windows settings.
  • Very long first build: normal. Restore and the first compile for each platform take minutes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command installs the MAUI workload?

    Workloads add extra build tools to the .NET SDK. 'dotnet workload install maui' installs the MAUI workload.
  2. 2. What does the -f option select in 'dotnet build -f net10.0-android'?

    -f chooses the target framework. For MAUI each platform has its own target framework moniker.
  3. 3. What connects MainPage.xaml to the MainPage class in C#?

    x:Class names the class; the code-behind is a partial class of that name, and InitializeComponent builds the controls.
  4. 4. What does x:Name give you?

    x:Name generates a field so code-behind can read and change the control, as CounterBtn.Text does.

Summary

  • Install the .NET SDK, the MAUI workload and the toolchains for your target platforms.
  • Create projects with Visual Studio or dotnet new maui; choose a platform with the target framework.
  • The template page shows XAML plus code-behind, x:Class, x:Name and event wiring.
  • Hot Reload and the live visual tree speed up UI work.

Next: Project Structure Explained