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.

Entonces, si por ejemplo se tuviera un script que hiciera esto:

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. Si se encuentra cualquier ocurrencia en el paso anterior, se muestra un diálogo al usuario ofreciendo la actualización automática, en caso contrario, se termina.
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.

Cuando la Actualización Automática de API termine con éxito, se recibirá una notificación en la consola, como ésta:

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

Al ejecutar Unity desde la línea de comandos, puede usar la opción -accept-apiupdate para hacer que se ejecute el Actualizador de API. Consulte Argumentos de la línea de comando para más información.

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.

Una causa común de esto es cuando la actualización automática no pudo guardar sus cambios - por ejemplo - cuando el usuario no tiene permisos de modificar el script actualizado. Es posible que pueda estar protegido contra escritura.

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–06–02 Page amended with limited editorial review
  
• “accept-apiupdate” command line option added in Unity 2017.2