.NET MAUI Solution Layout

📦 .NET MAUI Solution Layout (Project Structure)

MAUI uses a single-project structure that multi-targets platforms while sharing most of your app code and assets. Below is a practical map of what lives where, why it matters, and how it all fits together.

🧭 High-level structure

The typical MAUI solution has one .sln (solution) and one primary project (.csproj) that targets Android, iOS, Mac Catalyst, and Windows. Platform-specific files live under a unified Platforms/ folder, while shared UI and assets sit at the root.

├─ 📄 MyMauiApp.sln
└─ 📁 MyMauiApp/                         ← single project (multi-target)
├─ 📄 MyMauiApp.csproj
├─ 📄 MauiProgram.cs                  ← DI + app builder
├─ 📄 App.xaml  / App.xaml.cs          ← app shell & resources
├─ 📁 Views/                         ← pages & screens (XAML/CS)
├─ 📁 ViewModels/                    ← MVVM view models
├─ 📁 Models/                        ← domain/data models
├─ 📁 Services/                      ← data/services/APIs
├─ 📁 Controls/                      ← custom controls
├─ 📁 Helpers/                       ← utilities/extensions
├─ 📁 Resources/                     ← shared assets (fonts, images, styles)
├─ 📁 Platforms/                     ← per-platform code & manifests
├─ 📁 Themes/                        ← color styles, dictionaries
├─ 📁 Tests/                         ← unit/UI tests (optional)
└─ 📄 README.md  / .editorconfig / .gitignore (optional)

🗂️ Top-level files

• 📄 Solution (.sln): Groups projects; usually just one MAUI project unless you separate libraries.
• 📄 Project (.csproj): Defines TargetFrameworks, assets, build settings, NuGet packages, and MSBuild items for MAUI.
• ⚙️ MauiProgram.cs: Entry point for configuring the MAUI app, dependency injection, handlers, and services.
• 🧩 App.xaml / App.xaml.cs: Global resources, styles, Shell configuration, and application lifecycle hooks.
• 🗺️ Shell: Optional AppShell.xaml for navigation structure (tabs, flyouts, routes).

// MauiProgram.cs  (core setup)
using Microsoft.Maui;
using Microsoft.Maui.Controls.Hosting;
using Microsoft.Maui.Hosting;

namespace MyMauiApp;

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

        // Dependency injection
        builder.Services.AddSingleton<MainPage>();
        builder.Services.AddSingleton<MainViewModel>();
        builder.Services.AddTransient<IDataService, DataService>();

        return builder.Build();
    }
}

---

🧱 Common shared folders

🖼️ Resources

• 🖼️ Images: Put PNG/SVG/WEBP in Resources/Images. MAUI auto-generates platform variants (scales/densities) at build.
• 🔤 Fonts: Place TTF/OTF in Resources/Fonts and register in MauiProgram.cs. Use the alias in XAML/C#.
• 🎨 Styles: Resource dictionaries in Resources/Styles or Themes/ for colors, typography, and control styles.
• 🎬 App icons/splash: Resources/AppIcon and Resources/Splash with a single source image; MAUI generates platform-specific outputs.
• 📦 Raw assets: Files in Resources/Raw accessed via FileSystem.OpenAppPackageFileAsync.

🧩 Views, view models, models

• 🧩 Views: XAML page files like MainPage.xaml and code-behind, plus custom controls in Controls/.
• 🧠 ViewModels: MVVM classes with INotifyPropertyChanged; register in DI for constructor injection.
• 📘 Models: Immutable or simple POCOs representing domain/data entities.

🔧 Services and helpers

• 🔌 Services: API clients, repositories, local storage; abstract behind interfaces for testing.
• 🧰 Helpers: Converters, behaviors, extension methods, platform checks.
• 🧭 Navigation: Centralize navigation via Shell routes or an abstraction over INavigation.

---

🖥️ Platforms folder

Platform-specific code and manifests live here. Use conditional compilation and partial classes to wire platform features while keeping the shared code clean.

• 🤖 Android: AndroidManifest.xml, MainActivity.cs, MainApplication.cs, platform services (e.g., notifications, permissions), and resource overrides.
• 📱 iOS: Info.plist, AppDelegate.cs, SceneDelegate.cs, entitlements, and iOS-specific implementations.
• 🖥️ Mac Catalyst: Info.plist, AppDelegate.cs, Catalyst-specific configurations (menu items, window behaviors).
• 🪟 Windows: Package.appxmanifest, App.xaml.cs partials, WinUI host, toast notifications, and windowing APIs.

// Example: conditional platform code
#if ANDROID
// Android-specific implementation
#elif IOS
// iOS-specific implementation
#elif WINDOWS
// Windows-specific implementation
#endif

---

🔧 Project file essentials (.csproj)

Your project file defines targets, assets, and MAUI build behaviors. MAUI’s single project uses multi-targeting to build per-platform binaries.

<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst;net8.0-windows10.0.19041.0</TargetFrameworks>
<OutputType>Exe</OutputType>
<UseMaui>true</UseMaui>
<SingleProject>true</SingleProject>
<ApplicationTitle>MyMauiApp</ApplicationTitle>
<Version>1.0.0</Version>
</PropertyGroup>

<ItemGroup>
<MauiImage Include="Resources/Images/.png" />
<MauiSplashScreen Include="Resources/Splash/splash.svg" Color="#ffffff" />
<MauiIcon Include="Resources/AppIcon/appicon.svg" />
<MauiFont Include="Resources/Fonts/.ttf" />
<None Include="Resources/Raw/**" Pack="true" />
</ItemGroup>

<ItemGroup>
<PackageReference Include="CommunityToolkit.Maui" Version="x.y.z" />
</ItemGroup>
</Project>

---

🧭 Navigation and app lifecycle

• 🗺️ Shell navigation: Define routes in AppShell.xaml and navigate via Shell.Current.GoToAsync("route").
• 🔄 Lifecycle: Handle OnStart, OnSleep, OnResume-like behaviors via Application events and platform-specific callbacks.
• 🧩 Dependency injection: Register views, view models, and services in MauiProgram.cs and resolve via constructor injection.

// Register routes (AppShell.xaml.cs)
Routing.RegisterRoute("details", typeof(DetailsPage));

// Navigate
await Shell.Current.GoToAsync("details");

---

🧪 Testing setup (optional)

• 🧪 Unit tests: Separate test project targeting net8.0; mock platform services; test view models and services.
• 🧭 UI tests: Use frameworks like Playwright for Windows (desktop UI) or platform UI test tools; keep IDs consistent for selectors.
• 🧱 Architecture: Favor interfaces and pure logic in shared layer to maximize testability.

---

📐 Naming, organization, and tips

• 📁 Feature-first folders: Group Views/, ViewModels/, Services/ by feature (e.g., Features/Orders/...) for scale.
• 🪄 Partial classes: Split platform-specific bits from shared logic cleanly with partials and #if guards.
• 🖼️ Asset hygiene: Keep SVGs where possible; MAUI auto-generates densities—avoid manual platform duplication.
• 🔐 Permissions: Declare in platform manifests and wrap usage behind a shared service that handles prompts.
• ⚡ Performance: Use compiled bindings, avoid heavy logic in OnAppearing, and cache images/fonts.

---

✅ Quick checklist

• 🎬 Entry wired: MauiProgram.cs sets fonts, handlers, DI.
• 🗺️ Shell set: Routes and navigation organized.
• 🖼️ Resources mapped: Images, fonts, icons, splash in Resources/.
• 🧩 MVVM layered: Views, ViewModels, Services, Models separated.
• 🖥️ Platforms: Manifests and platform-specific code in Platforms/.
• 🧪 Tests: Unit tests for core logic; DI makes mocking easier.