Usando la Actualización Automática de API

Algunas veces, durante el desarrollo del software de Unity, tomamos la decisión de cambiar y mejorar la manera en que las clases, funciones y propiedades (el API) funcionan. Hacemos esto con un esfuerzo en causar el menor impacto sobre el código existente de los usuarios. Pero algunas veces, para hacer las cosas mejor, tenemos que romper cosas.

Generalmente introducimos estos “cambios importantes” cuando se cambia de una versión significativa de Unity a otra, y solamente en los casos que haga que Unity sea más fácil de usar (lo que significa que los usuarios tendrán menos errores) o traiga mejoras notables en rendimiento, y sólo después de considerar otras alternativas cuidadosamente. Sin embargo, la consecuencia de esto es que si - por ejemplo - se fuera a abrir un proyecto de Unity 4 en Unity 5, se podría encontrar que algunos de los comandos de scripting que se usaron han sido cambiados, eliminados, o funcionan un poco diferente.

Un ejemplo obvio de esto es que en Unity 5, hemos eliminado los “accesos rápidos” que permitían referenciar tipos comunes de componentes directamente en un GameObject, tales como ‘gameObject.light’, gameObject.camera’, ‘gameObject.audiosource’, etc.

En Unity 5, ahora se debe usar el comando GetComponent para todos los tipos, con la excepción de transform. Entonces si se abre un proyecto de Unity 4 que usa ‘gameObject.light’ en Unity 5, esa particular línea de código es obsoleta y es necesario que sea actualizada.

La Actualización Automática de API

Unity tiene un Sistema de Actualización de API Obsoleto que detectará usos de código obsoleto en los scripts, y puede ofrecer actualizarlos automáticamente. Al aceptar, reescribirá el código usando la versión actualizada del API.

Obviamente, y como siempre, es importante tener una copia de seguridad del trabajo en el caso de que algo salga mal, ¡pero esto es particularmente importante cuando se permite que un programa reescriba código! Una vez se halla realizado una copia de seguridad, y se haga click en el botón de “Go ahead” (Adelante), Unity reescribirá cualquier parte en donde halla código obsoleto con la versión actualizada recomendada.

For example you had a script which did this:

light.color = Color.red;

La Actualización Automática de API de Unity lo convertiría a esto:

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

El flujo de trabajo en general de la Actualización Automática es como sigue:

1. Al abrir un proyecto / importar un paquete que contenga scripts / assemblies con uso de API obsoleto

2. Unity activa una compilación de script

3. La Actualización Automática de API revisa por errores de compilación particulares que son conocidos como “actualizables”

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

5. Si el usuario acepta la Actualización Automática de API (el cual actualizará todos los scripts escritos en el mismo lenguaje que se halla compilado en el paso 2)

6. Ir al paso 2 (para tomar cualquier código actualizado en cuenta), hasta que no existan scripts actualizados en el paso 5

Entonces, a partir de la lista anterior se puede observar que la actualización puede ejecutarse varias veces si existen scripts que pertenezcan a las diferentes fases de compilación (por ejemplo, scripts en diferentes lenguajes, scripts de editor, etc.) que use código obsoleto.

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

Si se escoge no permitir que la Actualización Automática de API actualice los scripts, se verán errores de script en la consola normalmente. También se verá que los errores que la Actualización Automática podría actualizar estarán marcados como (UnityUpgradable) (Actualizable por Unity) en el mensaje de error.

Si el script tiene otros errores, en adición a los errores de API obsoleto, la Actualización Automática de API puede que no termine completamente su trabajo hasta que se hallan arreglado los otros errores. En este caso, se notificará en la ventana de consola con un mensaje como éste:

"Algunos scripts tienen errores de compilación que pueden impedir que los errores de API obsoleto se actualicen. La actualización de API obsoleto continuará automáticamente después de que estos errores sean corregidos.

Una vez se hallan corregido los otros errores en el script, se puede volver a iniciar la Actualización Automática de API. La Actualización Automática de API se ejecuta automáticamente cuando una compilación de script es activada, pero también se puede ejecutar manualmente desde el menú de Assets, aquí:

Modo de linea de comando

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.

Resolución de Problemas

Si es obtiene un mensaje diciendo “API Updating failed. Check previous console messages.” (“La actualización de API falló. Revise mensajes previos de la consola.”) esto significa que la Actualización Automática de API se encontró con un problema que le impide terminar su trabajo.

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.

Al revisar las lineas de error en la consola siguiendo la instrucción, es posible ver los problemas que ocurrieron durante el proceso de actualización.

Limitaciones

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 with limited editorial review

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

• AssemblyUpdater logging improved in Unity 2018.3 NewIn20183