The MAUI Project Structure

Analogy categoryAnalogies

A default MAUI project (created via dotnet new maui or Visual Studio's 'MAUI App' template) has a single .csproj file that multi-targets several TFMs, a Platforms/ folder containing per-platform entry points and manifests, a Resources/ folder for fonts, images, and app icons managed through a unified pipeline, and root-level files like MauiProgram.cs, App.xaml, and AppShell.xaml that bootstrap the app before any page loads. Understanding this layout is essential because MAUI resolves platform-specific behavior by folder convention rather than by separate projects, so misplacing a file (e.g., an Android-only permission edit) in the wrong folder means it silently does nothing.

🏏

Cricket analogy: The MAUI project layout is like a team's dressing room with labeled sections — bowling kit here, batting kit there — since Platforms/Android, Platforms/iOS, and Resources/ each hold specific assets that only apply where the folder convention expects them.

MauiProgram.cs, App.xaml, and AppShell.xaml

MauiProgram.cs contains the CreateMauiApp() static method, the single entry point where you register the App class, configure fonts via ConfigureFonts(), and wire up dependency injection with builder.Services.AddSingleton/AddTransient — this replaces the old per-platform Application startup code Xamarin.Forms required. App.xaml/App.xaml.cs defines the Application subclass and sets the initial page (typically MainPage = new AppShell()), while AppShell.xaml defines a Shell, MAUI's built-in navigation and flyout/tab-bar structure that maps routes to pages via ShellContent and Routing.RegisterRoute, so navigation like Shell.Current.GoToAsync("//details") works without manually managing a NavigationPage stack.

🏏

Cricket analogy: MauiProgram.cs is like the team's pre-match team-sheet submission to the umpires, the one official place where the playing XI (services, fonts, the App class) gets registered before the match (app) can start.

csharp

// MauiProgram.cs
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<WeatherService>();
        builder.Services.AddTransient<MainPage>();

        return builder.Build();
    }
}

The Platforms/ and Resources/ Folders

Platforms/Android holds MainActivity.cs, MainApplication.cs, and AndroidManifest.xml (for permissions like INTERNET or CAMERA); Platforms/iOS holds AppDelegate.cs and Info.plist (for entries like NSCameraUsageDescription); Platforms/Windows holds App.xaml/App.xaml.cs for the WinUI 3 host and Package.appxmanifest for capabilities. The Resources/ folder uses a single-project resource pipeline: Resources/Images holds source images that get resized into per-density Android drawable-* and iOS asset-catalog entries automatically at build time, Resources/Fonts holds .ttf/.otf files referenced by ConfigureFonts(), and Resources/AppIcon holds one source SVG/PNG that generates every platform's icon sizes, replacing the old workflow of manually producing a dozen icon resolutions.

🏏

Cricket analogy: AndroidManifest.xml declaring a CAMERA permission is like a player's central contract listing which formats they're cleared to play; without the declaration listed in the right platform folder, the feature is simply not authorized to run.

Because Resources/Images uses a single-project pipeline, you don't need separate mdpi/hdpi/xhdpi Android drawables or 1x/2x/3x iOS asset catalog entries — just drop one high-resolution source image and reference it by filename (without extension) in XAML, e.g. <Image Source="logo.png" />.

Editing AndroidManifest.xml or Info.plist directly still works, but permission and capability entries added through the .csproj's <ItemGroup> MauiIcon/MauiSplashScreen/MauiImage tags or through Platform-specific partial classes are easy to lose track of — always check both the manifest file and any csproj-level overrides when a permission mysteriously doesn't apply.

A MAUI project has one multi-targeted .csproj instead of separate per-platform head projects.
MauiProgram.cs's CreateMauiApp() is the single startup entry point for DI registration and font configuration.
App.xaml/App.xaml.cs defines the Application subclass; AppShell.xaml defines Shell-based navigation, tabs, and flyout structure.
Platforms/Android, Platforms/iOS, and Platforms/Windows hold OS-specific entry points and manifests (AndroidManifest.xml, Info.plist, Package.appxmanifest).
Resources/Images, Resources/Fonts, and Resources/AppIcon use a single-project pipeline that auto-generates per-platform assets from one source file.
Device permissions (camera, location) must be declared in the platform-specific manifest file before they work in code.
Misplacing platform-specific configuration in the wrong Platforms/ subfolder means it silently has no effect on other platforms.

Practice what you learned

1. Where is the CreateMauiApp() method defined in a MAUI project?

2. Which file declares Android-specific permissions like CAMERA or INTERNET?

3. What does AppShell.xaml primarily provide in a MAUI app?

4. How does the Resources/Images folder simplify asset management compared to older Xamarin.Forms workflows?

5. What happens if a configuration file is placed in the wrong Platforms/ subfolder (e.g., an iOS setting mistakenly placed under Platforms/Android)?

Was this page helpful?

Setting Up the MAUI Environment

XAML Basics

Related Study Notes in Programming

Browse all study notes

Programming

Apache Spark Study Notes

Programming · 30 topics

Programming

Apache Flink Study Notes

Programming · 30 topics

Programming

Hadoop Study Notes

Programming · 30 topics

Programming

Snowflake Study Notes

Programming · 30 topics

Programming

Apache Airflow Study Notes

Programming · 30 topics

Programming

dbt (Data Build Tool) Study Notes

Programming · 30 topics

Topics covered

#Programming#NETMAUIStudyNotes#TheMAUIProjectStructure#MAUI#Project#Structure#MauiProgram#StudyNotes#SkillVeris#ExamPrep

The MAUI Project Structure