链接 .NET MAUI Mac Catalyst 应用

生成应用时，.NET 多平台应用 UI (.NET MAUI) 可以使用名为 ILLink 的链接器来减小应用的整体大小。 ILLink 为此，请分析编译器生成的中间代码，删除未使用的方法、属性、字段、事件、结构和类，以生成仅包含运行应用所需的代码和程序集依赖项的应用。

链接器支持 iOS 和 Mac Catalyst 上的 .NET MAUI 应用的三种模式：

可以为应用的每个生成配置配置链接器行为。

警告

为应用的调试配置启用链接器可能会妨碍调试体验，因为它可能会删除属性访问器，使你能够检查对象的状态。

在 Visual Studio for Mac 中配置链接器行为：

在“解决方案窗口”中，右键单击 .NET MAUI 应用项目，然后选择“属性”。

在 “项目属性” 窗口中，选择“ 生成 > Mac Catalyst > 生成 ”选项卡。

在 “项目属性” 窗口中，确保 “配置” 下拉列表设置为“ 发布 ”，并将 “链接器行为 ”下拉列表设置为所需的链接器行为：

在 “项目属性” 窗口中，单击“ 确定” 按钮。

使用链接器时，它有时会删除你可能已动态调用的代码，甚至间接调用。 可以通过使用 DynamicDependency 属性批注来指示链接器保留成员。 此属性可用于表示对成员的类型和子集或特定成员的依赖关系。

重要

应用未静态链接的每个成员都会被删除。

特性 DynamicDependency 可以应用于构造函数、字段和方法：

在此示例中， DynamicDependency 确保 Helper 保留 方法。 如果没有 属性，链接将删除HelperMyAssembly或完全删除MyAssembly（如果未在其他位置引用）。

特性指定要通过 string 或 通过 DynamicallyAccessedMembers 特性保留的成员。 类型和程序集要么隐含在属性上下文中，要么在属性中显式指定（按照分别表示类型和程序集名称的 Type 或 string）。

类型和成员字符串使用 C# 文档注释 ID 字符串格式的变体，不带成员前缀。 成员字符串不应包含声明类型的名称，并且可能会省略参数以保留指定名称的所有成员。 以下示例演示了有效用法：

可以指定应从链接过程中排除的程序集，同时允许链接其他程序集。

链接所有程序集时，链接器可以通过在项目文件中的标记中设置 TrimmerRootAssembly MSBuild 属性来跳过程序集：

注意

.dll设置 TrimmerRootAssembly MSBuild 属性时不需要扩展。

如果链接器跳过程序集，则它被视为“root”，这意味着将保留它及其所有静态可理解的依赖项。 可以通过向 添加其他 MSBuild 属性来跳过其他TrimmerRootAssembly程序集。

可以向链接器传递一个 XML 说明文件，该文件指定需要保留的程序集、类型和成员。

链接所有程序集时，若要从链接进程中排除成员，请将 TrimmerRootDescriptor 项目文件中标记 中的 MSBuild 属性设置为定义要排除的成员的 XML 文件：

然后，XML 文件使用剪裁器 描述符格式 来定义要从链接中排除的成员：

在此示例中，XML 文件指定由应用动态访问的方法，该方法从链接中排除。

在 XML 中列出程序集、类型或成员时，默认操作为保留，这意味着无论链接器是否认为使用了它们，它们都将保留在输出中。

注意

保留标记不明确包含。 如果未提供下一级别的详细信息，它将包括所有子级。 如果列出不带任何类型的程序集，则将保留该程序集的所有类型和成员。

如果项目中有一个库，或者你是可重用库的开发人员，并且希望链接器将程序集视为可链接程序集，则可以使用 AssemblyMetadata 属性将程序集标记为安全链接器：

或者，可以在程序集的项目文件中的标记中设置true。 这会将程序集标记为“可剪裁”，并为该项目启用剪裁警告。 “可剪裁”意味着程序集被视为与剪裁兼容，在生成程序集时不应有剪裁警告。 在修整的应用中使用时，程序集将在最终输出中删除其未使用的成员。

注意

IsTrimmable如果为程序集设置了 MSBuild 属性，则会替代 特性IsTrimmable。 这样，即使程序集没有 属性，也可以选择进行剪裁，或者禁用对具有 特性的程序集的剪裁。

若要禁用链接，请在项目文件中的标记中设置None，或将链接器行为设置为在 Visual Studio 中不链接。

警告

在程序集的项目文件中的标记中设置false不会禁用 iOS 和 Mac Catalyst 上的 .NET MAUI 应用的链接。