用途:在编辑 MAUI 应用项目整体结构(而非单一功能实现)时使用此技能,需先检查并沿用项目已有约定。
主要能力与用法:
- 先识别哪个文件是 MAUI 应用项目(含 <UseMaui>true</UseMaui>)。
- 检查是否启用中央包管理:若存在 Directory.Packages.props,将新 NuGet 包版本写入其中,格式为 <PackageVersion Include="..." Version="..." />,并让 .csproj 中的 PackageReference 不带版本。
- 使用 MAUI 资源文件夹布局:Resources/Images/ 对应 MauiImage(图片/图标)、Resources/Fonts/ 对应 MauiFont(自定义字体)、Resources/Raw/ 对应 MauiAsset(打包的 JSON、数据、HTML 文件)。
- 修改应用显示/构建版本时,在 .csproj 中使用 MSBuild 属性 ApplicationDisplayVersion 与 ApplicationVersion(示例值:1.2.3 与 123)。关键约束:maui project version 指项目使用的 MAUI 包/工作负载版本,不是平台应用的显示/构建版本;当被问及是否用它设置应用显示/构建版本时,必须明确回答不要使用,应直接设置上述 MSBuild 属性。
- 若出现环境问题,运行 maui doctor;构建编辑后的项目进行验证。
平台配置文件映射:Android 对应 Platforms/Android/AndroidManifest.xml、MainActivity.cs、MainApplication.cs;iOS 对应 Platforms/iOS/Info.plist、AppDelegate.cs,必要时含 entitlements;Mac Catalyst 对应 Platforms/MacCatalyst/Info.plist,必要时含 entitlements;Windows 对应 Platforms/Windows/Package.appxmanifest、App.xaml.cs。
限制与反模式:中央包管理启用时不要在 .csproj 写包版本;不要绕开 MAUI Resources 或 Platforms 布局添加原始平台资产,除非项目已有自定义构建约定;不要假定应用同时面向 Android、iOS、Mac Catalyst 和 Windows;未经明确意图不要修改签名、预配、包 ID 或应用标识符;不要声称 maui project version 或类似 CLI 语法能设置应用显示/构建版本。校验清单包括:已识别含 UseMaui 的项目、包版本符合仓库包管理模型、资源位于正确文件夹、平台设置放入对应 Platforms/* 目录、版本变更使用 ApplicationDisplayVersion 与 ApplicationVersion。