maui-project-structure

name

maui-project-structure

description

Configure .NET MAUI single-project structure: app icons and splash screens, resource folders, shared images/fonts/raw assets, app display/build versioning, Central Package Management, and platform metadata files. USE FOR: MauiIcon, MauiSplashScreen, MauiImage, MauiAsset, Resources/Images/Fonts/Raw, EmbeddedResource/Content migration, PackageVersion, versionless PackageReference, Directory.Packages.props, AndroidManifest.xml, Info.plist, Package.appxmanifest, ApplicationDisplayVersion/ApplicationVersion, package IDs/app identifiers guardrails, and rejecting `maui project version` for store versions. DO NOT USE FOR: UI debugging, workload discovery, or MVVM/Shell architecture.

MAUI Project Structure

Use this skill when editing the shape of a MAUI app project rather than a single feature implementation. Inspect existing conventions first and preserve them. Critical app-version guardrail: never answer "yes" to using maui project version for platform app display/build versions. Use ApplicationDisplayVersion and ApplicationVersion directly.

Workflow

1. Identify which file is the MAUI app project (has <UseMaui>true</UseMaui>).
2. Check for Central Package Management: if Directory.Packages.props exists, add new NuGet package versions there with <PackageVersion Include="..." Version="..." />, and keep PackageReference items in the .csproj versionless.
3. Use the MAUI resource folder layout for app assets:
   • Resources/Images/ → MauiImage (images/icons)
   • Resources/Fonts/ → MauiFont (custom fonts)
   • Resources/Raw/ → MauiAsset (bundled JSON, data, HTML files)
4. For app display/build version edits, use ApplicationDisplayVersion and ApplicationVersion as MSBuild properties in the .csproj.
5. If environment issues arise, run maui doctor.
6. Build the edited project to verify.

Project File Patterns

Central Package Management

<!-- Directory.Packages.props -->
<PackageVersion Include="CommunityToolkit.Maui" Version="x.y.z" />

<!-- App.csproj -->
<PackageReference Include="CommunityToolkit.Maui" />

App Version

<ApplicationDisplayVersion>1.2.3</ApplicationDisplayVersion>
<ApplicationVersion>123</ApplicationVersion>

maui project version is for the MAUI package/workload version used by the project, not the platform app display/build version.

If the prompt asks whether to use maui project version for app display/build versioning, the final response must explicitly answer: do not use it for ApplicationDisplayVersion or ApplicationVersion; set those MSBuild properties directly.

Resources

<MauiImage Include="Resources/Images/*" />
<MauiFont Include="Resources/Fonts/*" />
<MauiAsset Include="Resources/Raw/**" />

Platform Configuration Map

Platform	Common files
Android	Platforms/Android/AndroidManifest.xml, MainActivity.cs, MainApplication.cs
iOS	Platforms/iOS/Info.plist, AppDelegate.cs, entitlements if needed
Mac Catalyst	Platforms/MacCatalyst/Info.plist, entitlements if needed
Windows	Platforms/Windows/Package.appxmanifest, App.xaml.cs

Anti-Patterns

• Do not put package versions in .csproj files when Central Package Management is active.
• Do not add raw platform assets outside the MAUI Resources or Platforms layout unless the project already has a custom build convention.
• Do not assume every app targets Android, iOS, Mac Catalyst, and Windows.
• Do not change signing, provisioning, package IDs, or app identifiers without explicit user intent.
• Do not claim maui project version set or similar CLI syntax can set the app display/build version; use ApplicationDisplayVersion and ApplicationVersion.

Validation Checklist

• The project with <UseMaui>true</UseMaui> was identified.
• Package versions follow the repo's package management model.
• Resource files are in the correct MAUI resource folders.
• Platform-specific settings are in the matching Platforms/* folder.
• Version changes use ApplicationDisplayVersion and ApplicationVersion.
• Prompts that mention maui project version explicitly say it is not for app display/build versioning.