← Руководство

API обновитель

Чтобы улучшить удобство использования и производительность, Unity может изменить способ работы классов, функций и свойств (API). Иногда эти улучшения могут ввести разрушительные изменения при переходе от одной основной версии Unity к другой.

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

Обновитель API состоит из ScriptUpdater и AssemblyUpdater, которые отвечают за обновление исходного кода (скриптов) и сборок (файлов dll) соответственно.

Примечание: API Updater может исправить только некоторые ошибки и предупреждения в API. Они обозначены как UnityUpgradable в сообщении консоли. Вы должны вручную устранить другие ошибки или предупреждения, которые API Updater не может обработать.

Использование обновителя API

Когда компиляция сценариев срабатывает, API обновитель запускается автоматически. Например, это происходит, когда вы:

Откройте проект.
Импорт пакета.
Сохранение изменений в сценарии.

Обновитель API предлагает обновить любой устаревший код, который он обнаружит. Если вы согласитесь, он перепишет любой устаревший код с рекомендуемой обновленной версией API.

Например, обновитель API преобразует следующее устаревшее заявление из:

light.color = Color.red;

к:

GetComponent<Light>().color = Color.red;

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

Unity запускает компиляцию скрипта.
Обновитель API проверяет обновляемые ошибки компилятора или предупреждения, которые он может обрабатывать.
- Если не обнаружено никаких ошибок или предупреждений, процесс завершается.
- Закройте Редактор и создайте резервную копию проекта, прежде чем позволить обновителю API обновить ваши скрипты или сборки. При повторном открытии проекта, Unity компилирует ваши скрипты и запускает обновитель API.
Если вы принимаете обновление, обновитель API обновляет все скрипты в одном и том же блоке компиляции.
Обновитель API повторяет этот процесс до тех пор, пока не обнаружит больше ошибок или предупреждений, с которыми он может справиться.

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

Если вы не разрешаете обновителю API обновлять ваши скрипты, консоль отображает любые ошибки скрипта или предупреждения. Ошибки или предупреждения, которые обновитель API мог бы устранить, отображаются (UnityUpgradable) в сообщении.

Если в вашем скрипте есть другие ошибки, которые мешают успешному запуску обновителя API, Консоль отобразит сообщение, информирующее вас об этом. Вы должны устранить эти ошибки, прежде чем обновление будет завершено обновителем API.

Аргументы командной строки, относящиеся к обновителю API

При беге Unity в пакетном режиме из командной строки, используйте -accept-apiupdate возможность запустить API Дополнительные сведения см. в Аргументы командной строки.

Лесозаготовки

Средство обновления API записывает изменения, внесённые в сборки, в журнал Editor. Чтобы управлять объёмом записываемых сведений, задайте переменной среды UNITY_APIUPDATER_LOG_THRESHOLD нужный порог журналирования и запустите Unity. Например:

На Windows:

c:> set UNITY_APIUPDATER_LOG_THRESHOLD=Debug
c:> \path\to\unity\Unity.exe

На Linux:

$ export UNITY_APIUPDATER_LOG_THRESHOLD=Debug
$ /path/to/unity/Unity

На Mac:

$ export UNITY_APIUPDATER_LOG_THRESHOLD=Debug
$ /path/to/unity/Unity

Примечание: Вы также можете использовать управление версиями изменения API updater делает для скриптов проекта.

Когда AssemblyUpdater закончится, Editor.log покажет изменения. Например:

[AssemblyUpdater] Property access to 'UnityEngine.Rigidbody
UnityEngine.GameObject::get_rigidbody()' in 'System.Void
Test.ClassReferencingObsoleteUnityAPIThroughEditorAssembly::Run()' replaced with 'T
UnityEngine.GameObject::GetComponent<UnityEngine.Rigidbody>()'.

В таблице ниже описаны значения переменной среды UNITY_APIUPDATER_LOG_THRESHOLD:

Логический порог	Описание
Ошибка (значение по умолчанию)	Средство обновления API регистрирует только сообщения об ошибках и. Сообщения об ошибках регистрируются, когда средство обновления API не может применить определенное обновление, что требует принятия корректирующих мер (обычно обращение к первоначальному автору сборки с просьбой предоставить обновленную версию сборки).
Предупреждение	Обновитель API регистрирует сообщения Предупреждение и Ошибка. Сообщения предупреждения регистрируются, когда обновитель API применяет изменение, которое пользователю может потребоваться просмотреть.
Информация	Обновитель API регистрирует сообщения Информационное, Предупреждение и Ошибка. Информационные сообщения включают обновления, примененные AssemblyUpdater.
Отладка	Обновитель API регистрирует все сообщения. Это полезно для устранения неполадок, например, если у вас возникли проблемы с обновителем API, о которых вы хотите сообщить Unity.

Устранение неполадок

API Обновление не удалось. Проверьте предыдущие сообщения консоли.

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

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