Xamarin.Mac/iOS 项目构建属性详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00095/article/details/148861039

Xamarin.Mac/iOS 项目构建属性详解

xamarin-macios Bridges the worlds of .NET with the native APIs of macOS, iOS, tvOS, and watchOS. 项目地址: https://gitcode.com/gh_mirrors/xa/xamarin-macios

Xamarin.Mac/iOS 项目（xamarin/xamarin-macios）为开发者提供了丰富的 MSBuild 构建属性，这些属性可以精细控制项目的构建过程。本文将深入解析这些构建属性，帮助开发者更好地理解和运用它们。

构建属性基础

构建属性是控制项目构建行为的配置项，它们被定义在项目文件（如 MyApp.csproj）的 PropertyGroup 元素中。这些属性影响着从代码编译到最终应用打包的各个环节。

应用图标配置

AppIcon 属性

AppIcon 属性用于指定应用的图标资源：

<PropertyGroup>
    <AppIcon>MyAppIcon</AppIcon>
</PropertyGroup>

对于 iOS、macOS 和 Mac Catalyst 项目，值应指向 .appiconset 资源
对于 tvOS 项目，值应指向 .brandassets 资源
路径相对于资源目录中的 asset catalog

IncludeAllAppIcons 属性

设置为 true 时，会自动包含所有 asset catalog 中的 app 图标：

<PropertyGroup>
    <IncludeAllAppIcons>true</IncludeAllAppIcons>
</PropertyGroup>

应用信息配置

应用版本相关属性

ApplicationDisplayVersion：设置 CFBundleShortVersionString（显示版本号）
ApplicationVersion：设置 CFBundleVersion（构建版本号）
ApplicationId：设置 CFBundleIdentifier（应用唯一标识符）
ApplicationTitle：设置 CFBundleDisplayName（应用显示名称）

这些属性支持 .NET 的"单一项目"模式，简化了多平台项目的配置。

代码签名配置

基本签名配置

EnableCodeSigning：是否启用代码签名（默认为 true）
CodesignKey：指定签名密钥
CodesignProvision：指定使用的 provisioning profile
CodesignEntitlements：指定 entitlements 文件路径（默认为 Entitlements.plist）

签名扩展点

CodesignConfigureDependsOn：在检查签名配置前执行的自定义目标
CodesignDependsOn：在应用签名前执行的自定义目标

示例禁用模拟器构建的代码签名：

<PropertyGroup>
  <CodesignConfigureDependsOn>$(CodesignConfigureDependsOn);DisableCodesignInSimulator</CodesignConfigureDependsOn>
</PropertyGroup>
<Target Name="DisableCodesignInSimulator" Condition="'$(SdkIsSimulator)' == 'true'">
  <PropertyGroup>
    <EnableCodeSigning>false</EnableCodeSigning>
  </PropertyGroup>
</Target>

打包配置

平台特定的打包选项

BuildIpa：为 iOS/tvOS 创建 .ipa 包
CreatePackage：为 macOS/Mac Catalyst 创建 .pkg 包
EnablePackageSigning：是否签名创建的 .pkg 包

打包路径控制

IpaPackageName：指定 .ipa 文件名
IpaPackageDir：指定 .ipa 文件目录
IpaPackagePath：完整指定 .ipa 文件路径

资源处理

BundleOriginalResources 属性

控制资源在库项目中的处理方式：

false（.NET 9 默认）：资源在嵌入前编译
true（.NET 10+ 默认）：嵌入原始资源

原始资源模式的优势：

加速 Windows 上的远程构建
无需 Xcode 即可构建
避免不同 Xcode 版本导致的兼容问题
支持全程序资源冲突检测

运行时配置

异常处理模式

ManagedExceptionHandlingMode：控制托管异常遇到原生帧时的处理方式
- throwobjectivecexception：转换为 Objective-C 异常
- abort：终止进程
- disable：禁用异常拦截
ObjectiveCExceptionHandlingMode：控制 Objective-C 异常遇到托管帧时的处理方式
- throwmanagedexception：转换为托管异常
- abort：终止进程
- disable：禁用异常拦截

诊断支持

EnableDiagnostics 启用诊断功能（如性能分析）：

<PropertyGroup>
  <EnableDiagnostics>true</EnableDiagnostics>
</PropertyGroup>

调试构建默认启用
会增加应用体积
仅适用于 Mono 运行时

构建扩展点

自定义构建步骤

CreateAppBundleDependsOn：在创建 app bundle 前执行自定义目标
CreateIpaDependsOn：在创建 IPA 前执行自定义目标
MaciOSPrepareForBuildDependsOn：在构建早期阶段执行自定义目标

示例添加自定义构建步骤：

<PropertyGroup>
  <CreateAppBundleDependsOn>$(CreateAppBundleDependsOn);MyPreBundleStep</CreateAppBundleDependsOn>
</PropertyGroup>
<Target Name="MyPrePreBundleStep">
  <Message Text="执行自定义预处理步骤" Importance="high"/>
</Target>