文档

Unity 引擎

Unity 引擎

使用Annotations保留代码

使用 C# Attributes或 XML的Annotations来指定 Unity 链接器不应剥离代码的哪些部分。
阅读时间9 分钟最后更新于 6 天前

您可以使用Annotations来防止 Unity 链接器剥离代码的指定的部分。如果应用程序产生当 Unity 执行 Static 分析时不存在的运行时代码,例如,通过反射,这将很有帮助。Annotations为 Unity 链接器提供了有关不应剥离的代码模式的General指导,或者提供了不剥离指定的已定义代码部分的指令。
您可以使用两种广泛的方法来注释代码,使其免受 Managed 代码剥离过程的影响:
  • Root Annotations 将代码的某些部分标识为根。Unity 链接器不会剥离标记为根的Any代码。根 Annotations 使用起来不太复杂,但也可能导致 Unity 链接器保留一些应该剥离的代码。
  • 依赖关系 Annotations 定义了代码元素之间的连接。与根 Annotations 相比,依赖关系 Annotations 可以减少不必要的代码保留。
每种技术都可以更好地Control Unity 链接器在较高剥离级别剥离的代码amount,并减少重要代码被剥离的可能性。When代码通过反射引用Other代码时,Annotations特别有用,因为 Unity 链接器并不总是能够检测到反射的用途。
保留使用反射的代码或在运行时时生成Other代码,从而显著降低执行应用程序程序When发生意外行为的可能性。有关 Unity 链接器可以识别的反射模式的示例,请参阅 Unity 中级语言链接器反射测试套件。

根Annotations

根Annotations会力 Unity 链接器将代码元素视为根元素,在代码剥离过程中不会剥离这些根元素。您可以使用两种类型的根Annotations,具体取决ON否需要使用构造函数或程序集来保留各个类型:
  • 保留属性:将各个类型注释为根以保留它们。
  • Link.xml:将程序集和这些程序集中的Any类型或Other代码Entities作为根进行注释以保留它们。

使用 Preserve 属性注释根

使用
[Preserve]
属性可以从 Unity 链接器的 Static 分析中单独排除指定的代码部分。要使用此属性注释一段代码,请在要保留的代码第一部分之前添加
[Preserve]
。以下列表描述了使用
[Preserve]
属性注释不同代码元素时 Unity 链接器保留哪些 Entities:
  • 程序集:保留程序程序集中使用和定义的All类型。要将
    [Preserve]
    属性分配给程序集,请将属性声明放在程序集中包含的任何 C# 文件中的 Any 命名空间 Declarations 之前。
  • Type(类型):保留类或类型及其默认构造函数函数。
  • "method":保留 方法、声明方法的类型、方法返回的类型及其 All Arguments 的类型。
  • 属性保留属性性、声明属性性的类型、属性的类型以及获取和设置属值的方法。
  • 字段保留Field、Field类型和声明Field的类型。
  • 事件:保留事件、声明事件的类型、类型、事件返回的类型、
    [add]
    访问器和
    [remove]
    访问器。
  • delegate保留委托类型以及委托调用的All方法。
如果要同时保留类型及其默认构造函数,请使用
[Preserve]
属性。如果要保持其中一个 Other 而不是同时保持这两个,请使用
link.xml
文件。
您可以在 Any 程序集和 Any 命名空间中定义
[Preserve]
属性。您可以使用
PreserveAttribute
类、创建其子类或创建自己的类。例如:
类 Foo{ [保留] public void PreservedMethod(){}}
您可以在 Project 中包含名为
link.xml
的 .xml 文件,以保留指定程序集或程序集部分的列表。
link.xml
文件必须存在于项目的
Assets
Folder 或
Assets
Folder 的子目录中,并且必须在文件中包含
<linker>
标签。Unity 链接器将
link.xml
文件中保留的任何程序集、类型或成员视为根类型。
您可以在 Project 中使用任何数量的
link.xml
文件。因result,您可以为每个插件提供单独的保留Declarations。不能在包中包含
link.xml
文件,但可以从非包
link.xml
文件引用包程序集。
ON 如何格式化
link.xml
文件的信息,请参阅 Link XML 格式参考。

依赖关系关系Annotations

依赖关系 Annotations 定义各种代码元素之间的依赖关系。这些 Annotations 可用于保留 Unity 链接器无法静态分析的代码模式,例如反射。这些Annotations还确保在没有元件使用这些代码元素When不会错误地保留这些代码元素。可以使用两种方法来 Change Unity 链接器处理代码元素的方式:
  • 注释属性:这些Attributes指示 Unity 链接器应保留特定的代码模式,例如从注释类型派生的Any类型。
  • AlwaysLinkAssemblyAttribute:使用此属性可指示 Unity 链接器应处理程序程序集,即使Project中的AnyOther程序集均未引用该程序集。

注释Attributes

[Preserve]
属性适用于始终需要 API 的情况。OtherAttributes可用于更General的保留。例如,您可以通过使用
[RequireImplementorsAttribute]
注释接口来保留实现特定接口的所有类型。
要注释指定的编码模式,请使用以下一个或多个 Attributes:
  • 将实现此接口的All类型标记为依赖项。
  • 将从此类型派生的所有类型标记为依赖项。
  • 将 ON 类型的接口实现标记为依赖项。
  • 将类型的All成员标记为依赖项。
  • 将自定义Attributes标记为依赖项。
您可以通过各种方式组合这些Attributes,从而更精确地Control Unity 链接器如何保留代码。

AlwaysLinkAssembly 属性

[AlwaysLinkAssembly]
属性强制 Unity 链接器搜索程序集,无论程序集是否被版本中包含的另一个程序集引用。只能将属性性Apply于程序程序集。
该属性不会直接在程序集内保留代码。相反,此属性指示 Unity 链接器将根标记规则应用于程序集。如果没有代码元素与程序程序集的根标RulesMatch,Unity 链接器仍会从版本中删除程序程序集。
ON 使用此属性可以预编译或包程序集,这些程序集包含一个或多个具有
[RuntimeInitializeOnLoadMethod]
属性的方法,但可能不包含项目中 Any 场景中直接或间接使用的类型。
如果程序集定义
[assembly: AlwaysLinkAssembly]
,并且也被版本中包含的另一个程序集引用,则该属性对输出没有特效。

其他资源