.NET MAUI for Beginners: Your First Cross-Platform App

.NET MAUI lets you build native mobile and desktop applications from a shared .NET and C# codebase. A single project can contain shared UI and business logic while still allowing platform-specific code when an application needs it.

What does MAUI provide?

MAUI provides controls, layouts, navigation, platform integration, dependency injection, and project tooling for supported Android, iOS, Windows, and macOS targets.

Simple XAML UI

<VerticalStackLayout Padding="30">
    <Label Text="Hello, MAUI!" />
    <Button Text="Click me" Clicked="OnButtonClicked" />
</VerticalStackLayout>

XAML describes the interface while C# handles application logic and services. Separating the UI description from application behavior keeps simple screens easier to read.

Handle a button event

private void OnButtonClicked(object sender, EventArgs e)
{
    DisplayAlert("MAUI", "Button clicked", "OK");
}

UI events can call application logic in the page's code-behind or in another component/service. As an application grows, shared logic is usually better placed outside the view.

Project structure

A typical MAUI application contains shared code plus platform-specific folders. Shared resources can include pages, models, services, images, fonts, and styles. Platform folders are used when Android, iOS, Windows, or macOS requires behavior that cannot be shared.

Dependency injection

MAUI applications can register services in the application startup code and resolve them through dependency injection. This makes API clients and other application services easier to replace and test than constructing them directly inside every page.

Navigation

Applications normally need a consistent navigation strategy as more pages are added. Start with the navigation approach supported by the application's architecture, then introduce shell or other navigation features when the basic page flow is understood.

Platform-specific code

Shared code should be the default, but platform APIs are sometimes necessary. Keep platform-specific behavior isolated so the rest of the application can remain portable.

Common beginner mistakes

• Putting all application logic directly inside page code-behind.
• Assuming a device-specific API will behave identically on every target.
• Adding complex architecture before understanding layouts, events, navigation, and the application lifecycle.

Start small

Begin with a simple screen, learn layouts and controls, then add navigation and services. A small working project is easier to debug than a new application that introduces every architecture pattern at once.

Next step

Continue with the .NET MAUI Tutorials pillar for practical cross-platform development and Blazor Hybrid topics.