📦 How the .NET MAUI Project Structure Works – A Beginner's Guide

.NET MAUI (Multi-platform App UI) is the evolution of Xamarin.Forms, designed to simplify cross-platform development by unifying Android, iOS, macOS, and Windows apps into a single project structure.

Unlike Xamarin, where developers needed to juggle multiple projects per platform, .NET MAUI introduces a cleaner and more maintainable single-project approach. This blog will walk you through the entire structure of a MAUI project in detail, breaking down each part so you understand exactly what's happening under the hood.

Join our exclusive WhatsApp group for Xamarin and .NET MAUI developers to connect with experts, share insights, and get help with your projects. Whether you're a beginner or an experienced developer, this group is the perfect place to enhance your skills and collaborate with the community.

Please, support my blog by clicking on our sponsors ad!

📁 Solution Explorer: First Look


- MyMauiApp
  - Dependencies
  - Platforms
    - Android
    - iOS
    - MacCatalyst
    - Windows
  - Resources
    - Fonts
    - Images
    - Raw
    - Styles
  - App.xaml
  - App.xaml.cs
  - MainPage.xaml
  - MainPage.xaml.cs
  - MauiProgram.cs
  - MyMauiApp.csproj

🧭 1. Platforms Folder

The Platforms folder is where platform-specific code resides. Each subfolder (Android, iOS, etc.) contains code, configurations, and entry points required to make your app run on that platform.

🔹 Android

MainActivity.cs: The main entry point for Android.
MainApplication.cs: Used for application-level events.
AndroidManifest.xml: Declares app permissions, icons, splash screen config, etc.

🔹 iOS

AppDelegate.cs: Handles app lifecycle events.
Info.plist: Configuration file for iOS, where you set permissions like camera, location, etc.

🔹 MacCatalyst

Used for building native macOS apps using the same MAUI codebase.

🔹 Windows

App.xaml.cs and MainWindow.xaml.cs: Entry point and window handling for Windows.

Tip: You typically don’t need to touch these unless you're writing platform-specific features like camera access or notification handling.

🎨 2. Resources Folder

The Resources folder holds your app’s shared assets like fonts, images, styles, and raw files.

🔹 Fonts

Place custom fonts here and register them in MauiProgram.cs.


.ConfigureFonts(fonts =>
{
    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
});

🔹 Images

Add shared images (icons, logos, etc.) here. .NET MAUI will automatically resize and process them for different screen densities across platforms.

🔹 Raw

Store raw files like JSON, XML, MP3, PDFs, etc.


var file = await FileSystem.OpenAppPackageFileAsync("myfile.json");

🔹 Styles


<Style TargetType="Label">
    <Setter Property="FontSize" Value="14"/>
    <Setter Property="TextColor" Value="Gray"/>
</Style>

Table of Contents for .Net Maui

🔧 3. App.xaml and App.xaml.cs

🔹 App.xaml

Contains global-level XAML resources like themes, colors, styles.

🔹 App.xaml.cs

Sets the root page in the app lifecycle.


public partial class App : Application
{
    public App()
    {
        InitializeComponent();
        MainPage = new AppShell(); // or MainPage = new MainPage();
    }
}

🧱 4. MainPage.xaml and MainPage.xaml.cs

This is your app’s default starting UI screen.


<ContentPage>
    <VerticalStackLayout>
        <Label Text="Hello, .NET MAUI!" />
        <Button Text="Click me" Clicked="OnClicked"/>
    </VerticalStackLayout>
</ContentPage>


private void OnClicked(object sender, EventArgs e)
{
    // Handle click
}

🛠️ 5. MauiProgram.cs

This is the entry configuration file for your app.


public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

        builder.Services.AddSingleton<MyApiService>();

        return builder.Build();
    }
}

📦 6. Dependencies

This section holds all NuGet packages your project uses.

Examples:

CommunityToolkit.Maui
Microsoft.Maui.Controls
SQLite-net
Firebase

Add packages via NuGet Manager or CLI:


dotnet add package CommunityToolkit.Maui

📄 7. MyMauiApp.csproj

The .csproj file defines target frameworks, SDKs, and resources.


<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net7.0-android;net7.0-ios;net7.0-maccatalyst;net7.0-windows10.0.19041.0</TargetFrameworks>
    <UseMaui>true</UseMaui>
    <SingleProject>true</SingleProject>
  </PropertyGroup>

  <ItemGroup>
    <MauiImage Include="Resources\Images\logo.png" />
    <MauiFont Include="Resources\Fonts\OpenSans-Regular.ttf" Alias="OpenSansRegular" />
  </ItemGroup>
</Project>

🔐 8. AppShell.xaml (Optional)

If you're using Shell navigation, define it here.


<Shell>
    <TabBar>
        <ShellContent Title="Home" ContentTemplate="{DataTemplate local:HomePage}" />
        <ShellContent Title="Settings" ContentTemplate="{DataTemplate local:SettingsPage}" />
    </TabBar>
</Shell>

🛎️ Key Benefits of MAUI’s Single Project Structure

Feature	Benefit
Unified Codebase	No need to maintain separate projects for Android, iOS, Windows
Centralized Resources	All fonts, images, styles in one place
Simplified Deployment	Use one build process for all platforms
Shared Dependency Injection	Register services once in `MauiProgram.cs`
Platform-Specific Access	Still possible via `#if` or `Platforms` folder

❓ Interview Questions (Leave Your Answers in the Comments!)

What file is responsible for bootstrapping the .NET MAUI application?
Where should custom fonts be placed and how are they registered?
What is the purpose of MauiProgram.cs?
How does .NET MAUI manage platform-specific code?
What is the role of App.xaml vs App.xaml.cs?
How is Shell navigation different from traditional page navigation?
Explain how images are managed and resized in .NET MAUI.
Where can you define global styles in a .NET MAUI app?
How do you add a third-party NuGet package in your MAUI project?
What is the function of the .csproj file in a MAUI app?

📝 Your Turn!
Drop your answers in the comments and share what you’ve learned. Let’s chat below!

Previous Next