Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 42 ยท Getting Started

Project Structure Explained

Tour a .NET MAUI project - the single csproj, Platforms folder, Resources for images, fonts and icons, MauiProgram, App.xaml, AppShell and how resources are processed per platform.

A new MAUI project has a handful of files that every app uses. Knowing what each one does makes the rest of the track easier, because you will keep returning to them: MauiProgram.cs for setup, App.xaml for global resources, AppShell.xaml for navigation, Platforms for native code and Resources for images and fonts.

This lesson is a read-only tour of real project files. The runnable block is a labelled stand-in that imitates how MAUI sorts resource files by their folder.

The folder layout

TEXT
HelloMaui/
  HelloMaui.csproj
  MauiProgram.cs
  App.xaml / App.xaml.cs
  AppShell.xaml / AppShell.xaml.cs
  MainPage.xaml / MainPage.xaml.cs
  Platforms/
    Android/
    iOS/
    MacCatalyst/
    Tizen/
    Windows/
  Properties/
    launchSettings.json
  Resources/
    AppIcon/
    Fonts/
    Images/
    Raw/
    Splash/
    Styles/

In Xamarin.Forms you had one shared project plus one project per platform. In MAUI there is one project. Platform-specific code lives in the Platforms folder and is compiled only when you build for that platform.

The project file

The .csproj is where you choose platforms and settings (read-only, shortened):

XML
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0-android;net10.0-ios;net10.0-maccatalyst</TargetFrameworks>
    <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net10.0-windows10.0.19041.0</TargetFrameworks>

    <OutputType>Exe</OutputType>
    <RootNamespace>HelloMaui</RootNamespace>
    <UseMaui>true</UseMaui>
    <SingleProject>true</SingleProject>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>

    <ApplicationTitle>HelloMaui</ApplicationTitle>
    <ApplicationId>com.companyname.hellomaui</ApplicationId>
    <ApplicationDisplayVersion>1.0</ApplicationDisplayVersion>
    <ApplicationVersion>1</ApplicationVersion>
  </PropertyGroup>

  <ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" />
    <MauiSplashScreen Include="Resources\Splash\splash.svg" />
    <MauiImage Include="Resources\Images\*" />
    <MauiFont Include="Resources\Fonts\*" />
    <MauiAsset Include="Resources\Raw\**" />
  </ItemGroup>
</Project>

Key settings:

  • TargetFrameworks lists the platforms to build. Delete a line to drop a platform; the Windows entry is conditional because Windows apps only build on Windows.
  • UseMaui and SingleProject turn on MAUI and the single-project resource handling.
  • ApplicationId is the unique id (reverse domain style) used by app stores. Change it from the template default.
  • ApplicationDisplayVersion and ApplicationVersion are the user-visible version (1.0) and the build number (an integer that must increase with each store upload).
  • The MauiXxx items tell the build where icons, splash screens, images, fonts and raw assets are.

Resources

Everything in Resources is processed by the build:

Folder Item type What happens
AppIcon MauiIcon An SVG (or foreground and background pair) becomes the launcher icon at every size
Splash MauiSplashScreen A splash image is produced per platform
Images MauiImage SVG and PNG files are resized for each density; file names must be lowercase, start with a letter and use only letters, digits and underscores
Fonts MauiFont Fonts are copied into the app and registered in MauiProgram
Raw MauiAsset Files are packaged unchanged, read at run time with FileSystem.OpenAppPackageFileAsync
Styles MauiXaml Colors.xaml and Styles.xaml, the default theme resources

In XAML you refer to an image by file name without its extension: Source="dotnet_bot" loads Resources/Images/dotnet_bot.svg. Vector SVGs scale without blurring, which is why the template uses them.

The stand-in below mimics the sorting by folder idea. It does not resize any images; it only shows how a build step classifies files and checks a naming rule.

C# Stand-in: classify resource files like the build does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The real build, of course, also converts and packages the files. The takeaway is the convention: folder decides the item type, and image names must be simple.

Platforms folder

Each subfolder holds the native glue for one platform:

  • Android/MainActivity.cs, MainApplication.cs and AndroidManifest.xml (permissions, app label).
  • iOS/AppDelegate.cs, Info.plist and Entitlements.plist.
  • MacCatalyst/ is similar to iOS.
  • Windows/App.xaml, Package.appxmanifest.

You rarely edit these. You change them when you need a permission, a platform-specific setting or a native-only feature (see platform features).

The important code files

  • MauiProgram.cs builds and configures the app (fonts, services, handlers). The next lesson covers it.
  • App.xaml and App.xaml.cs define the Application object: global resources (colors, styles) and the first window.
  • AppShell.xaml declares the app's navigation structure with Shell (see Shell navigation).
  • MainPage.xaml is the first page.
  • Resources/Styles/Colors.xaml and Styles.xaml hold the default theme, merged in App.xaml.

Conditional code for one platform uses preprocessor symbols:

C#
#if ANDROID
    // Android-only code
#elif IOS
    // iOS-only code
#elif WINDOWS
    // Windows-only code
#endif

You can also add files named *.Android.cs or put code in Platforms/Android so only that build compiles them (the default template configures this for you).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many projects does a typical MAUI app have?

    MAUI uses a single project. Platform-specific code lives in Platforms and builds only for that target.
  2. 2. Which project file setting is the unique identifier used by app stores?

    ApplicationId is the package or bundle identifier, for example com.companyname.hellomaui.
  3. 3. Which image file name is valid in Resources/Images?

    Image names must start with a lowercase letter and use only lowercase letters, digits and underscores.
  4. 4. How do you display Resources/Images/dotnet_bot.svg in XAML?

    Use the file name without extension; the build generates platform-specific files from it.

Summary

  • One .csproj lists target platforms, app id, version and resource items.
  • Resources folders map to item types (MauiImage, MauiFont, MauiIcon, MauiAsset...).
  • Platforms holds native glue; MauiProgram.cs, App.xaml and AppShell.xaml are the shared entry points.
  • Use #if ANDROID style symbols for small platform differences.

Next: App Lifecycle and MauiProgram