Определения сборки

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

Сборка — это библиотека кода C#, содержащая скомпилированные классы и структуры, определенные вашими скриптами, а также определяющие ссылки на другие сборки. Общие сведения о сборках в C# см. в разделе Сборки в .NET.

По умолчанию Unity компилирует почти все ваши игровые сценарии в предопределенную сборку Assembly-CSharp.dll. (Unity также создает несколько небольших специализированных предопределенных сборок.)

Этот порядок приемлем для небольших проектов, но имеет некоторые недостатки, когда вы добавляете в проект больше кода:

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

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

На приведенной выше диаграмме показано, как можно разделить код проекта на несколько сборок. Поскольку Main ссылается на Stuff, а не наоборот, вы знаете, что любые изменения кода в Main не могут повлиять на код в Материал. Точно так же, поскольку Library не зависит ни от каких других сборок, вам будет проще повторно использовать код из Library в другом проекте.

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

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

См. также:

Определение сборок

Чтобы организовать код проекта в сборки, создайте папку для каждой нужной сборки и переместите сценарии, которые должны принадлежать каждой сборке, в соответствующую папку. Затем создайте ресурсы определения сборки, чтобы указать свойства сборки.

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

Чтобы включить сценарии из не дочерней папки в существующую сборку, создайте ресурс "Ссылка на сборку" в не дочерней папке и задайте для него ссылку на ресурс "Определение сборки", определяющий целевую сборку. Например, вы можете объединить скрипты из всех папок редактора в вашем проекте в их собственную сборку, независимо от того, где эти папки расположены.

Unity компилирует сборки в порядке, определяемом их зависимостями
См. в Словарь; вы не можете указать порядок, в котором происходит компиляция.

Ссылки и зависимости

Когда один тип (например, класс или структура) использует другой тип, первый тип зависит от второго. Когда Unity компилирует сценарий, он также должен иметь доступ к любым типам или другому коду, от которого зависит сценарий. Точно так же, когда скомпилированный код запускается, он должен иметь доступ к скомпилированным версиям своих зависимостей. Если два типа находятся в разных сборках, сборка, содержащая зависимый тип, должна объявить ссылку на сборку, содержащую тип, от которого она зависит.

Вы можете управлять ссылками между сборками, используемыми в вашем проекте, с помощью параметров определения сборки. Настройки определения сборки включают:

Автоматическая ссылка — ссылаются ли предопределенные сборки на сборку
Ссылки на определение сборки — ссылки на другие сборки проекта, созданные с помощью определений сборки
Переопределить ссылки + Ссылки на сборки – ссылки на предварительно скомпилированные сборки (плагины)
Нет ссылок на Engine — ссылки на сборки UnityEngine

Примечание. Классы в сборках, созданные с помощью определения сборки, не могут использовать типы, определенные в предопределенных сборках.

Ссылки по умолчанию

По умолчанию предопределенные сборки ссылаются на все остальные сборки, в том числе созданные с помощью определений сборки (1) и предварительно скомпилированные сборки, добавленные в проект в качестве подключаемых модулей (2). Кроме того, сборки, которые вы создаете с помощью ресурса определения сборки, автоматически ссылаются на все предварительно скомпилированные сборки (3):

В настройках по умолчанию классы в предопределенных сборках могут использовать все типы, определенные любыми другими сборками в проекте. Точно так же сборки, которые вы создаете с помощью ресурса определения сборки, могут использовать все типы, определенные в любых предварительно скомпилированных сборках (подключаемых модулях).

Вы можете предотвратить ссылки на сборку из предопределенных сборок, отключив параметр Автоматическая ссылка в Инспекторе для ресурса определения сборки. Отключение автоматических ссылок означает, что предопределенные сборки не перекомпилируются при изменении кода в сборке, но также означает, что предопределенные сборки не могут напрямую использовать код в этой сборке. См. раздел Свойства определения сборки.

Точно так же вы можете запретить автоматическую ссылку на сборку подключаемого модуля, отключив свойство Автоссылка в Инспекторе подключаемых модулей. для актива плагина. Это влияет как на предопределенные сборки, так и на те, которые вы создаете с помощью определения сборки. Дополнительную информацию см. в разделе Инспектор подключаемых модулей.

При отключении Автоматически ссылаться для плагинаНабор кода, созданный вне Unity, который создает функциональность в Unity. В Unity можно использовать два типа подключаемых модулей: управляемые подключаемые модули (управляемые сборки .NET, созданные с помощью таких инструментов, как Visual Studio) и собственные подключаемые модули (библиотеки собственного кода для конкретной платформы). Подробнее
См. в Словарь, вы можете явно сослаться на него в Инспекторе для Ресурс определения сборки. Включите параметр ресурса Переопределить ссылки и добавьте ссылку на плагин. См. раздел Свойства определения сборки.

Примечание. Нельзя объявлять явные ссылки на предварительно скомпилированные сборки. Предопределенные сборки могут использовать код только в сборках с автоматическими ссылками.

Циклические ссылки

Ссылка на циклическую сборку существует, когда одна сборка ссылается на вторую сборку, которая, в свою очередь, ссылается на первую сборку. Такие циклические ссылки между сборками не допускаются и отображаются как ошибка с сообщением «Обнаружена сборка с циклическими ссылками».

Обычно такие циклические ссылки между сборками возникают из-за циклических ссылок внутри классов, определенных в сборках. Хотя в циклических ссылках между классами в одной сборке нет ничего технически недопустимого, циклические ссылки между классами в разных сборках не допускаются. Если вы столкнулись с ошибкой циклической ссылки, вы должны реорганизовать свой код, чтобы удалить циклическую ссылку или поместить взаимно ссылающиеся классы в одну сборку.

Создание ресурса определения сборки

Чтобы создать ресурс определения сборки:

В Проектев Unity вы используете проект для проектирования и разработки игры. В проекте хранятся все файлы, связанные с игрой, такие как ресурсы и файлы сцен. Подробнее
В окне Словарь найдите папку, содержащую сценарии, которые вы хотите включить в сборка.
Создайте ресурс определения сборки в папке (меню: АктивыЛюбой носитель или данные, которые можно использовать в вашей игре или Ресурс может исходить из файла, созданного вне Unity, например, 3D-модели, аудиофайла или изображения. Вы также можете создавать некоторые типы ресурсов в Unity, такие как Animator Controller, Audio Mixer или Render Texture. . Подробнее
См. в Словарь > Создать > Определение сборки).
Назначьте название объекту. По умолчанию файл сборки использует имя, которое вы присвоили ресурсу, но вы можете изменить это имя в Инспектореокне Unity который отображает информацию о текущем выбранном игровом объекте, активе или настройках проекта, позволяя вам проверять и редактировать значения. Дополнительная информация
См. в окне Словарь.

Unity перекомпилирует скрипты в проекте для создания новой сборки. После завершения вы можете изменить настройки для нового определения сборки.

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

Создание исходного ресурса определения сборки

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

В окне Проект найдите папку, содержащую сценарии, которые вы хотите включить в указанную сборку.
Создайте ресурс ссылки на сборку в папке (меню: Ресурсы > Создать > Ссылка на определение сборки).
Назначьте название объекту.

Unity перекомпилирует скрипты в проекте для создания новой сборки. По завершении вы можете изменить настройки для нового справочника по определению сборки.
Выберите новый ресурс Справочник определения сборки, чтобы просмотреть его свойства в Инспекторе.
Задайте для свойства определения сборки ссылку на целевой ресурс определения сборки.
Нажмите Применить.

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

Создание сборки для конкретной платформы

Чтобы создать сборку для определенной платформы:

Создайте ресурс определения сборки.
Выберите новый ресурс Справочник определения сборки, чтобы просмотреть его свойства в Инспекторе.
Отметьте параметр Любая платформа и выберите определенные платформы для исключения. Кроме того, вы можете снять флажок «Любая платформа» и выбрать определенные платформы для включения.
Нажмите Применить.

Сборка будет включена (или исключена) в соответствии с выбранными платформами при сборке проекта для платформы.

Создание сборки для кода редактора

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

Чтобы создать сборку, содержащую код редактора в вашем проекте:

Создайте сборку для конкретной платформы в папке, содержащей сценарии редактора.
Включить ТОЛЬКО платформу редактора.
Если у вас есть дополнительные папки, содержащие сценарии редактора, создайте ресурсы-ссылки на определение сборки в этих папках и установите для них ссылки на это определение сборки.

Создание тестовой сборки

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

Ссылка на другую сборку

Чтобы использовать типы и функции C#, являющиеся частью другой сборки, необходимо создать ссылку на эту сборку в ресурсе определения сборки.

Чтобы создать ссылку на сборку:

Выберите определение сборки для сборки, для которой требуется ссылка для просмотра ее свойств в Инспекторе.
В разделе Ссылки на определение сборки нажмите кнопку +, чтобы добавить новую ссылку.
Назначьте ресурс определения сборки вновь созданному слоту в списке ссылок.

Включение параметра Использовать идентификаторы GUID позволяет изменить имя файла связанного ресурса определения сборки без обновления ссылок в других определениях сборки для отражения нового имени. (Обратите внимание, что идентификаторы GUID необходимо сбросить, если файлы метаданных для файлов активов удалены или вы перемещаете файлы за пределы редактора Unity, не перемещая вместе с ними файлы метаданных.)

Ссылка на предварительно скомпилированную сборку плагина

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

Выберите определение сборки для сборки, для которой требуется ссылка для просмотра ее свойств в Инспекторе.
В разделе Общие включите параметр Переопределить ссылки.

Раздел Ссылки на сборку в Инспекторе становится доступным, когда установлен флажок Переопределить ссылки.
В разделе Ссылки на сборку нажмите кнопку +, чтобы добавить новую ссылку.
Используйте раскрывающийся список в пустом слоте, чтобы назначить ссылку на предварительно скомпилированную сборку. В списке показаны все предварительно скомпилированные сборки в проекте для платформы, установленной в данный момент в проекте Настройки сборки. (Установите совместимость платформы для предварительно скомпилированной сборки в Инспекторе подключаемых модулей.)
Нажмите Apply.
Повторите для каждой платформы, для которой вы создаете свой проект.

Условное включение сборки

Вы можете использовать символы препроцессора, чтобы контролировать, компилируется ли сборка и включается ли она в сборки вашей игры или приложения (включая режим воспроизведения в редакторе). Вы можете указать, какие символы должны быть определены для использования сборки, с помощью списка Определить ограничения в параметрах определения сборки:

Выберите определение сборки для просмотра ее свойств в Инспекторе.
В разделе Определить ограничения нажмите кнопку +, чтобы добавить новый символ в список ограничений.
Введите имя символа.

Вы можете «отменить» символ, поставив восклицательный знак перед названием. Например, ограничение !UNITY_WEBGL будет включать сборку, когда UNITY_WEBGL НЕ определен.
Нажмите Применить.

Вы можете использовать следующие символы в качестве ограничений:

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

Символы, определенные в сценариях, не учитываются при определении того, было ли выполнено ограничение.

Дополнительную информацию см. в разделе Определение ограничений.

Определение символов на основе пакетов проектов

Если вам нужно скомпилировать другой код в сборке в зависимости от того, используются ли в проекте определенные пакеты или версии пакета, вы можете добавить записи в список Определения версий. В этом списке указаны правила определения символа. Для номеров версий можно указать логическое выражение, оценивающее конкретную версию или диапазон версий.

Чтобы условно определить символ:

Выберите определение сборки для просмотра ее свойств в Инспекторе.
В разделе Определения версии нажмите кнопку +, чтобы добавить запись в список.
Установите свойства:
- Ресурс: выберите пакет или модуль, который необходимо установить для определения этого символа
- Определить: имя символа
- Выражение: выражение, результатом которого является конкретная версия или диапазон версий. Правила см. в разделе Выражения определения версии.
Результат выражения показывает, какие версии оценивает выражение.

В следующем примере определяется символ USE_TIMELINE, если в проекте используется временная шкала 1.3.0 или более поздней версии:
Click Apply.

Символы, определенные в определении сборки, относятся только к скриптам в сборке, созданной для этого определения.

Обратите внимание, что вы можете использовать символы, определенные с помощью списка Определения версии, как Определить ограничения. Таким образом, вы можете указать, что сборка должна использоваться только в том случае, если в проекте установлены определенные версии данного пакета.

Выражения определения версии

Вы можете использовать выражения, чтобы указать точную версию или диапазон версий. В выражении Определение версии используется математическое обозначение диапазона. Квадратная скобка «[]» означает, что диапазон включает конечную точку:

[1.3,3.4.1] оценивается как 1.3.0 <= x <= 3.4.1

Скоба "()" означает, что диапазон не включает конечную точку:

(1.3.0,3.4) оценивается как 1.3.0 < x < 3.4.0

Вы можете смешивать оба типа диапазонов в одном выражении:

[1.1,3.4) оценивается как 1.1.0 <= x < 3.4.0

(0.2.4,5.6.2-preview.2] оценивается как 0.2.4 < x <= 5.6.2.- предварительный просмотр.2

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

[2.4.5] оценивается как x = 2.4.5

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

2.1.0-preview.7 оценивается как x >= 2.1.0-preview.7

Обозначения версий состоят из четырех частей в соответствии с форматом Semantic Versioning: MAJOR.MINOR.PATCH-LABEL. Первые три части всегда являются числами, а метка — строкой. Пакеты Unity в предварительной версии используют строку preview или preview.n, где n > 0 . В выражении необходимо использовать по крайней мере основной и дополнительный компоненты версии.

Примечание. В выражении не допускаются пробелы.

Поиск сборки, которой принадлежит скрипт

Чтобы определить, в какую сборку скомпилирован один из ваших сценариев C#:

Выберите файл сценария C# в окне Проект Unity, чтобы просмотреть его свойства в окне Инспектора.
Имя файла сборки и определение сборки, если оно существует, отображаются в разделе Информация о сборке в Инспекторе.

В этом примере выбранный сценарий компилируется в файл библиотеки Unity.Timeline.Editor.dll, который определяется ресурсом определения сборки Unity.Timeline.Editor.

Специальные папки

Unity обрабатывает сценарии в папках с определенными специальными именами иначе, чем сценарии в других папках. Однако одна из этих папок теряет свою особую обработку, когда вы создаете ресурс определения сборки внутри нее или в папке над ней. Вы можете заметить это изменение при использовании папок редактора, которые могут быть разбросаны по всему проекту (в зависимости от того, как вы организуете свой код и от используемых вами пакетов Asset Store).

Unity обычно компилирует любые скрипты в папках с именем Editor в предопределенную сборку Assembly-CSharp-Editor независимо от того, где находятся эти скрипты. Однако если вы создаете ресурс определения сборки в папке, под которой находится папка редактора, Unity больше не помещает эти сценарии редактора в предопределенную сборку редактора. Вместо этого они попадают в новую сборку, созданную вашим определением сборки, где им может не быть места. Для управления папками редактора вы можете создать определение сборки или эталонные активы в каждой папке редактора, чтобы поместить эти сценарии в одну или несколько сборок редактора. См. раздел Создание сборки для кода редактора.

Настройка атрибутов сборки

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

Например, следующие атрибуты сборки указывают несколько .NET значения метаданных сборки, InternalsVisibleTo, который может быть полезен для тестирования, и определяемый Unity атрибут Preserve, который влияет на то, как неиспользуемый код удаляется из сборки при сборке. ваш проект:

[assembly: System.Reflection.AssemblyCompany("Bee Corp.")]
[assembly: System.Reflection.AssemblyTitle("Bee's Assembly")]
[assembly: System.Reflection.AssemblyCopyright("Copyright 2020.")]
[assembly: System.Runtime.CompilerServices.InternalsVisibleTo("UnitTestAssembly")]
[assembly: UnityEngine.Scripting.Preserve]

Получение информации о сборке в скриптах сборки

Используйте класс CompilationPipeline в пространстве имен UnityEditor.Compilation для получения информации обо всех сборках, созданных Unity для проекта, включая сборки, созданные на основе ресурсов определения сборки.

Например, в следующем сценарии класс CompilationPipeline используется для вывода списка всех текущих сборок Player в проекте:

using UnityEditor;
using UnityEditor.Compilation;
public static class AssemblyLister
{
    [MenuItem("Tools/List Player Assemblies in Console")]
    public static void PrintAssemblyNames()
    {
        UnityEngine.Debug.Log("== Player Assemblies ==");
        Assembly[] playerAssemblies =
            CompilationPipeline.GetAssemblies(AssembliesType.Player);

        foreach (var assembly in playerAssemblies)
        {
            UnityEngine.Debug.Log(assembly.name);
        }
    }
}

Вы можете отблагодарить автора, за перевод документации на русский язык. ₽ Спасибо