Build Your First .NET MAUI App

.NET MAUI lets you build native applications for multiple platforms from a shared C# codebase. This guide walks through the basic workflow for creating a first application and understanding the files you will work with most often.

🚀 Try this example in the MAUI Playground

1. Create the Project

In Visual Studio, create a new project and select .NET MAUI App. Choose a project name and target the current .NET version installed on your machine.

After the project is created, Visual Studio provides the platform targets, shared application code, XAML resources, and configuration files required by the template.

2. Understand the Project Structure

• MauiProgram.cs — application startup and dependency injection configuration.
• App.xaml — shared application resources and styles.
• App.xaml.cs — application-level startup logic.
• MainPage.xaml — the initial user interface.
• MainPage.xaml.cs — code-behind for the page.
• Platforms — platform-specific Android, Windows, iOS, and Mac Catalyst code.
• Resources — images, fonts, styles, and other application resources.

3. Build a Simple UI

A MAUI page can be created with XAML controls such as VerticalStackLayout, Label, Entry, and Button.

<VerticalStackLayout Padding="30" Spacing="15">
    <Label Text="Hello, MAUI!" FontSize="28" />
    <Entry Placeholder="Enter your name" x:Name="NameEntry" />
    <Button Text="Say Hello" Clicked="OnSayHelloClicked" />
</VerticalStackLayout>

The page's code-behind can respond to the button event and update the interface.

private void OnSayHelloClicked(object sender, EventArgs e)
{
    DisplayAlert("Welcome", $"Hello, {NameEntry.Text}!", "OK");
}

4. Run the Application

Select a supported target such as Windows or an Android emulator and start debugging. The same shared page can be used across supported platforms while platform-specific behavior remains available when required.

5. Where to Go Next

Once the first application runs, the next useful topics are dependency injection, MVVM, navigation, local storage, REST API calls, Blazor Hybrid, and platform-specific APIs.

See the .NET MAUI Tutorials hub for the broader learning roadmap.

Common Beginner Mistakes

• Putting all application logic directly in code-behind.
• Ignoring dependency injection as the project grows.
• Hard-coding platform-specific paths.
• Adding platform-specific code when a shared MAUI API already exists.
• Skipping proper testing on the target platforms.

Conclusion

Your first .NET MAUI application is mainly about understanding the shared project structure and the relationship between XAML, C#, resources, and platform-specific code. From this foundation, you can progressively introduce MVVM, dependency injection, APIs, databases, and Blazor Hybrid.