Using the API Updater

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

Мы стараемся вводить такие крупные “ломающие что-либо” изменения только при переходе с одной значимой версии Unity к другой, и только в случаях, в которых это делает Unity более простой в использовании (пользователи столкнутся с меньшим количеством ошибок) или в случае значительного выигрыша в производительности и только полсле тщательного рассмотрения альтернатив. Однако, в результате этого, когда вы, например, открываете проект Unity 4 в Unity 5, вы можете обнаружить, что некоторые команды скриптов, которые вы использовали, изменились, исчезли или работают несколько иначе.

Один явный пример этого - это то, что в Unity 5 мы удалили “быстрый доступ”, который позволял вам прямо ссылаться на общие типы компонентов в GameObject, как например, gameObject.light, gameObject.camera, gameObject.audioSource и т.д.

Теперь в Unity 5 вам нужно использовать команду GetComponent для всех типов, кроме Transform. Поэтому, если вы открыли проект Unity 4, который использует gameObject.light в Unity 5, вы обнаружите, что определенные участки кода обозначены, как obsolete и должны быть обновлены.

Автоматическое обновление

Unity has an API Updater which will detect uses of obsolete code in your scripts, and can offer to automatically update them. If you accept, it will rewrite your code using the updated version of the API.

Как всегда очевидно, важно делать резервную копию вашей работы на случай, если что-либо пойдет не так, особенно в случаях, когда вы разрешаете программному обеспечению переписывать ваш код! После того, как вы убедитесь, что сделали резервную копию и нажмете кнопку “Продолжить”, Unity перепишет все участки устаревшего кода в соответствии с рекомендуемой новой версией.

For example you had a script which did this:

light.color = Color.red;

Unity API updater преобразует это для вас, чтобы:

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

Общий процесс обновления следующий:

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

2. Unity компилирует скрипты

3. Обновление API проверяет наличие ошибок компилятора, которые известны, как “обновляемые”

4. If any occurrence is found in the previous step, show a dialog to user offering automatic update, otherwise, we’ve finished.

5. Если пользователь принимает обновление, то запускается обновление API (который обновит все скрипты, написанные на том же языке, что и скомпилированные в шаге 2)

6. Переход к шагу 2 (чтобы учесть весь обновленный код) до тех пор, пока не останется никаких обновленных скриптов в шаге 5.

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

When the API Updater successfully finishes, the console displays the following notification:

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

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

“Некоторые скрипты имеют ошибки компиляции, которые могут не позволить обновить устаревшее использование API. Обновление устаревшего API будет продолжено автоматически после того, как эти ошибки будет исправлены.”

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

Command line mode

When running Unity in batch mode from the command line, use the -accept-apiupdate option to allow the API Updater to run. For more information, see Command Line Arguments.

Logging

A Version control system helps you see which changes the APIUpdater applies to a Project’s scripts. However, this can be difficult when dealing with pre-compiled assemblies. To see the list of changes made by the AssemblyUpdater (the APIUpdater component responsible for updating assemblies), set the UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD environment variable to the desirable log threshold and start Unity. For example, on Windows you can enter:

c:> set UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD=Debug

c:> \path\to\unity\Unity.exe

After AssemblyUpdater has finished, you can see the updates that have been applied in the 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>()'.

The valid values for the UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD environment variable are, in increasing order of detail:

• Error: The AssemblyUpdater only logs Error messages. Error messages are logged when the AssemblyUpdater fails to apply a specific update, which requires you to take corrective action (usually requesting the original assembly author to provide an updated version of the assembly).

• Warning: The AssemblyUpdater only logs Warning, and Error messages. Warning messages usually indicate that the AssemblyUpdater has reached a state that could be a potential problem. These problems can depend on conditions not known to the AssemblyUpdater at the point the message was logged.

• Info: The AssemblyUpdater only logs Informational, Warning, and Error messages. Info messages include updates applied by the AssemblyUpdater.

• Debug: The AssemblyUpdater logs all messages. Debug help with troubleshooting. You may want to set the threshold to this level if you are having issues with the AssemblyUpdater and you want to report them to Unity.

Error is the default value when UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD is not set.

Выявление ошибок

Если вы получили сообщение “Ошибка обновления API. Проверьте предыдущие сообщения в консоли.” это значит, что обновление API столкнулось с проблемой, которая не позволила закончить его работу.

A common cause of this is if the updater was unable to save its changes - For example - the user may not have rights to modify the updated script because it is write protected.

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

Ограничения

The API updater cannot automatically fix every API change. Generally, API that is upgradable is marked with (UnityUpgradable) in the obsolete message. For example:

[Obsolete("Foo property has been deprecated. Please use Bar (UnityUpgradable)")]

The API updater only handles APIs marked as (UnityUpgradable).

The API updater might not run if the only updatable API in your scripts include component or GameObject common properties, and those scripts only access members of those properties. Examples of common properties are renderer and rigidbody, and example members of those properties are rigidbody.mass and renderer.bounds. To workaround this, add a dummy method to any of your scripts to trigger the API updater. For example:

private object Dummy(GameObject o) { return o.rigidbody;}.

• 2018–07–31 Page amended

• “accept-apiupdate” command line option added in Unity 2017.2

• AssemblyUpdater logging improved in Unity 2018.3 NewIn20183