Maui Project Structure

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

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.