MAUI Development Documentation

Introduction to .NET MAUI

.NET MAUI (Multi-platform App UI) is an open-source framework for creating native cross-platform applications for iOS, Android, macOS, and Windows from a single, shared C# codebase. It's the evolution of Xamarin.Forms, bringing together the best of Xamarin with modern .NET development practices.

MAUI simplifies the development of native mobile and desktop applications by providing a single API that targets all platforms. This means you can write your UI and application logic once and deploy it everywhere, significantly reducing development time and effort while maintaining a native look and feel.

Key Benefits:

  • Single Project: Manage all your platform-specific code and assets within a single project structure.
  • Native Performance: Compiles to native UI elements, ensuring optimal performance and user experience.
  • Modern .NET: Built on .NET 6 and later, leveraging the latest language features and performance improvements.
  • Extensible: Easily extend MAUI with custom renderers and handlers for platform-specific features.
  • Rich Ecosystem: Access the vast .NET ecosystem of libraries and tools.

This documentation will guide you through the essential concepts and practices for developing applications with .NET MAUI.

Getting Started

To begin developing with .NET MAUI, you'll need to set up your development environment. This typically involves installing Visual Studio with the .NET MAUI workload.

Prerequisites:

  • Visual Studio 2022 (version 17.3 or later)
  • .NET MAUI workload
  • (Optional) Xcode for macOS/iOS development
  • (Optional) Android SDK and emulator for Android development

You can create your first MAUI project from the Visual Studio template: 

dotnet new maui -n MyMauiApp

This command creates a new MAUI project named "MyMauiApp" in your current directory.

To learn more about setting up your environment, please refer to the official .NET MAUI setup guide.

Architecture

.NET MAUI follows a layered architecture designed for cross-platform development.

The core of MAUI consists of:

  • MAUI Base Class Library (BCL): Provides the common abstractions and APIs for UI elements, data binding, navigation, and more.
  • Platform Abstractions: Interfaces and abstract classes that define platform-specific behaviors.
  • Platform Renderers/Handlers: Platform-specific implementations that translate MAUI UI controls into native UI controls.

This architecture allows you to write platform-agnostic code in the BCL, which is then mapped to native controls on each target platform.

MAUI Architecture Diagram

UI Concepts

.NET MAUI uses XAML (Extensible Application Markup Language) for defining user interfaces. XAML provides a declarative way to create your UI, separating presentation from application logic.

Common UI Elements:

  • ContentPage: Represents a single screen in your application.
  • StackLayout: Arranges child elements in a vertical or horizontal stack.
  • Grid: Arranges child elements in rows and columns.
  • Button, Label, Entry, Image, ListView: Fundamental controls for user interaction and display.

Here's a simple XAML example: 

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MyMauiApp.MainPage"
             Title="My First MAUI App">

    <ScrollView>
        <VerticalStackLayout
            Spacing="25"
            Padding="30,0"
            VerticalOptions="Center">

            <Image
                Source="dotnet_logo.png"
                SemanticProperties.Description="Cute dot net bot waving"
                HeightRequest="200"
                HorizontalOptions="Center" />

            <Label
                Text="Hello, .NET MAUI!"
                SemanticProperties.HeadingLevel="Level1"
                FontSize="32"
                HorizontalOptions="Center" />

            <Button
                Text="Click me"
                SemanticProperties.Hint="Counts the number of times you click"
                Clicked="OnCounterClicked"
                HorizontalOptions="Center" />

        </VerticalStackLayout>
    </ScrollView>

</ContentPage>

You can also define your UI entirely in C# code.

Data Binding

Data binding is a powerful mechanism that establishes a connection between UI elements and data sources. It allows you to synchronize data between your UI and your application's logic automatically, reducing boilerplate code and improving responsiveness.

MAUI supports various binding modes:

  • OneWay: Changes in the source update the target.
  • TwoWay: Changes in the source update the target, and changes in the target update the source.
  • OneWayToSource: Changes in the target update the source.
  • OneTime: The initial value of the target is set from the source, but subsequent changes are not synchronized.

Example of Two-Way Binding: 

<Entry Text="{Binding UserName, Mode=TwoWay}" />

This binds the Text property of the Entry control to a property named UserName in the data context, with changes flowing in both directions.

Networking

.NET MAUI provides access to the .NET networking stack, allowing you to easily consume web services, download files, and perform other network operations.

You can use classes from the System.Net.Http namespace, such as HttpClient, to make HTTP requests. 

using System.Net.Http;
using System.Threading.Tasks;

public class ApiService
{
    private readonly HttpClient _httpClient;

    public ApiService()
    {
        _httpClient = new HttpClient();
        // Configure base address or other defaults if needed
        // _httpClient.BaseAddress = new Uri("https://api.example.com/");
    }

    public async Task<string> GetDataAsync(string endpoint)
    {
        try
        {
            HttpResponseMessage response = await _httpClient.GetAsync(endpoint);
            response.EnsureSuccessStatusCode(); // Throws an exception if the status code is not successful
            return await response.Content.ReadAsStringAsync();
        }
        catch (HttpRequestException e)
        {
            // Handle exceptions
            Console.WriteLine($"Error fetching data: {e.Message}");
            return null;
        }
    }
}

Remember to handle potential network errors and ensure your application has the necessary permissions to access the network.

Deployment

Deploying your .NET MAUI application involves packaging it for each target platform.

Android: You can create an APK (Android Package) or an AAB (Android App Bundle) for distribution.

iOS: Applications are deployed via Xcode, typically creating an IPA file.

macOS: Applications can be packaged as .app bundles or distributed through the Mac App Store.

Windows: Applications can be packaged as MSIX packages or deployed as standalone executables.

Visual Studio provides robust tools for managing the build and deployment process for each platform.

Advanced Topics

As you progress, you'll explore more advanced topics such as:

  • Custom UI controls and handlers
  • Navigation patterns (Shell, NavigationPage)
  • Platform-specific APIs and integration
  • Performance optimization
  • Testing strategies
  • MVVM (Model-View-ViewModel) design pattern

The .NET MAUI community is vibrant, with extensive resources and support available online.