Сохранение кода с помощью аннотаций

С помощью аннотаций можно запретить Unity linker вырезать определённые фрагменты вашего кода. Это помогает, когда приложение формирует код во время выполнения, которого ещё нет на момент статического анализа, — например, через отражение. Аннотации либо предоставляют общее руководство для линкера Unity о том, какие шаблоны кода не следует удалять, либо инструкции не удалять определенный, определенный раздел кода.

Существуют два общих подхода, которые можно использовать для аннотации кода, чтобы сохранить его от управляемого процесса удаления кода:

Корневые аннотации идентифицируют части вашего кода как корни. Линкер Unity не удаляет никакой код, помеченный как корень. Корневые аннотации менее сложны в использовании, но могут также привести к тому, что линкер Unity сохранит некоторый код, который он должен удалить.
Аннотации зависимостей определяют связи между элементами кода. Аннотации зависимостей могут уменьшить ненужное сохранение кода по сравнению с корневыми аннотациями.

Каждый из этих методов обеспечивает больший контроль над количеством кода, который линкер Unity удаляет на более высоких уровнях удаления, и снижает вероятность удаления жизненно важного кода. Аннотации особенно полезны, когда ваш код ссылается на другой код через отражение, потому что линкер Unity не всегда может обнаружить использование отражения.

Сохраняйте код, который использует отражение или генерирует другой код во время выполнения, чтобы значительно уменьшить вероятность неожиданного поведения при выполнении приложения. Примеры шаблонов отражения, которые может распознавать линкер Unity, см. в Набор тестов рефлексии компоновщика промежуточного языка Unity.

Корневые аннотации

Корневые аннотации заставляют линкер Unity рассматривать элементы кода как корни, которые не удаляются в процессе удаления кода. Существует два типа корневых аннотаций, которые можно использовать, в зависимости от того, нужно ли сохранить отдельные типы с их конструкторами или сборками:

Preserve Attribute: Аннотирует отдельные типы как корни для их сохранения.
Link.xml: Аннотирует сборки и любые типы или другие кодовые объекты в этих сборках как корни для их сохранения.

Аннотирование корней с помощью атрибута Preserve

Используйте [Preserve] атрибут, чтобы по отдельности исключить конкретные фрагменты вашего кода из статического анализа Unity linker. Чтобы пометить фрагмент кода этим атрибутом, добавьте [Preserve] непосредственно перед первой частью кода, который вы хотите сохранить. В следующем списке описано, какие объекты Unity linker сохраняет, когда вы аннотируете различные элементы кода с [Preserve] атрибут:

Сборка: Сохраняет все типы, используемые и определенные в сборке. Чтобы назначить сборке атрибут [Preserve], поместите объявление атрибута в любой файл C#, включенный в сборку, перед любыми объявлениями пространств имен.
Тип: сохраняет класс или тип и его конструктор по умолчанию.
Метод: Сохраняет метод, тип, объявляющий метод, тип, возвращаемый методом, и типы всех его аргументов.
Имущество: Сохраняет свойство, тип, объявляющий свойство, тип значения свойства и методы, которые получают и устанавливают значение свойства.
Поле: Сохраняет поле, тип поля и тип, который объявляет поле.
Мероприятие: Сохраняет событие, тип, объявляющий событие, тип, тип, возвращаемый событием, доступный объект [add] и доступный объект [remove].
делегат: Сохраняет тип делегирования и все методы, которые вызывает делегирование.

Используйте атрибут [Preserve], если вы хотите сохранить и тип, и его конструктор по умолчанию. Если вы хотите сохранить один или другой, но не оба, используйте файл link.xml.

Вы можете определить [Preserve] атрибут в любой сборке и в любом пространстве имен. Вы можете использовать PreserveAttribute класс, создайте его подкласс или напишите собственный класс. Например:

class Foo
{
    [Preserve]
    public void PreservedMethod(){}
}

Аннотировать корни с помощью файла Link XML

Вы можете включить в свой проект файл .xml с именем link.xml для сохранения списка конкретных сборок или частей сборок. Файл link.xml должен находиться в папке Assets или в подкаталоге папки Assets в вашем проекте и должен включать в себя тег <linker>. Линкер Unity рассматривает любую сборку, тип или элемент, сохраненный в файле link.xml, как корневой тип.

Вы можете использовать любое количество файлов link.xml в вашем проекте. В результате, вы можете предоставить отдельные заявления о сохранении для каждого плагина. Вы не можете включить файл link.xml в пакет, но вы можете ссылаться на сборки пакета из непакетных файлов link.xml.

Информацию о форматировании файла link.xml см. в Ссылка XML Справочная информация по форматированию.

Аннотации зависимостей

Аннотации зависимости определяют зависимости между различными элементами кода. Эти аннотации полезны для сохранения шаблонов кода, которые Unity linker не может статически анализировать, таких как отражение. Эти аннотации также обеспечивают, что эти элементы кода не будут ошибочно сохранены, когда ни один корневой элемент их не использует. Есть два метода, которые вы можете использовать, чтобы изменить то, как Unity linker обрабатывает элементы кода:

Атрибуты аннотации: Эти атрибуты указывают, что линкер Unity должен сохранять определенный шаблон кода, например, любой тип, который происходит от аннотированного типа.
AlwaysLinkAssemblyAttribute: Используйте этот атрибут, чтобы указать, что линкер Unity должен обрабатывать сборку, даже если на нее не ссылаются другие сборки в вашем Project.

Атрибуты аннотации

[Preserve] атрибут удобен там, где API нужен всегда. Другие атрибуты полезны для более общих случаев сохранения. Например, можно сохранить все типы, реализующие определённый интерфейс, пометив этот интерфейс атрибутом [RequireImplementorsAttribute].

Чтобы аннотировать конкретные шаблоны кодирования, используйте один или несколько из следующих атрибутов:

RequireImplementorsAttribute: помечает все типы, реализующие этот интерфейс, как зависимости.
RequireDerivedAttribute: Помечает все типы, которые производятся от этого типа, как зависимости.
RequiredInterfaceAttribute: Помечает реализации интерфейсов у типов как зависимости.
RequiredMemberAttribute: Помечает все члены типа как зависимости.
RequireAttributeUsagesAttribute: Помечает пользовательские атрибуты как зависимости.

Вы можете комбинировать эти атрибуты различными способами, чтобы более точно управлять тем, как линкер Unity сохраняет ваш код.

Атрибут AlwaysLinkAssembly

Атрибут [AlwaysLinkAssembly] заставляет линкер Unity искать сборку независимо от того, указывается ли на сборку в другой сборке, включенной в сборку. Этот атрибут можно применить только к сборке.

Атрибут не сохраняет код непосредственно в сборке. Вместо этого этот атрибут указывает Unity линкер для применения Правила маркировки корней Если ни один кодовый элемент не соответствует правилам корневой маркировки для сборки, Unity linker по-прежнему удаляет сборку из сборки.

Используйте этот атрибут для предкомпилированных или пакетных сборок, которые содержат один или несколько методов с атрибутом [RuntimeInitializeOnLoadMethod], но которые могут не содержать типы, используемые прямо или косвенно в любых сценах проекта.

Если сборка определяет [assembly: AlwaysLinkAssembly] и на нее также ссылается другая сборка, включенная в сборку, атрибут не влияет на выход.