El Asistente de actualización del complemento de Android para Gradle (AGP) es una herramienta de Android Studio que te ayuda a actualizar la versión de AGP que usa tu proyecto.
De manera regular, se hacen actualizaciones a los cambios del AGP relacionados con funciones nuevas para configurar compilaciones, nuevas APIs para usar con otros complementos para Gradle y ajustes a la integración de la compilación del proyecto con Android Studio. La actualización de la versión de AGP que usa tu proyecto te permite beneficiarte con las funciones más recientes.
Para obtener más información sobre la estructura de proyecto recomendada para el Asistente de actualización, consulta Configuración en esta página.
Casos de uso del Asistente de actualización del AGP
El Asistente de actualización del AGP te ayuda a realizar los cambios necesarios para actualizar las versiones del AGP. Estos son sus casos de uso más comunes:
Cambios de sintaxis: El Asistente de actualización intenta traducir los archivos de tu compilación de una versión anterior del AGP a aquellos que requiere una versión posterior. A medida que se desarrolla el AGP, los archivos de compilación se actualizan para admitir interfaces mientras se reemplazan, se vuelven obsoletos o no se admiten.
Requisitos de compatibilidad entre el AGP y Gradle: El Asistente de actualización conoce los requisitos de compatibilidad entre el AGP y Gradle, y ayuda a garantizar que uses la versión de Gradle que requiere tu versión del AGP.
Requisitos de compatibilidad entre el AGP y los complementos para Gradle de terceros: El Asistente de actualización conoce los requisitos de compatibilidad entre el AGP y algunos complementos para Gradle de terceros, y ayuda a garantizar que uses las versiones de complementos para Gradle de terceros que requiere tu versión del AGP.
En general, el Asistente de actualización facilita la actualización de archivos de compilación y la comprensión de los mensajes de error que puede generarse después de una actualización del AGP. El Asistente de actualización también explica los motivos por los que son necesarios los cambios propuestos.
Cómo usar el Asistente de actualización del AGP
Para usar el Asistente de actualización, asegúrate de que la estructura de tu proyecto sea compatible con la herramienta y, luego, ejecútala desde Android Studio, como se describe en la sección sobre ejecución del Asistente de actualización.
Configura tu proyecto
Antes de ejecutar el Asistente de actualización, asegúrate de que tu proyecto tenga el formato correcto y realiza una copia de seguridad. Para asegurarte de que el Asistente de actualización del AGP esté configurado correctamente, lee las siguientes secciones.
Estructura tu proyecto con archivos de compilación de Gradle y lenguaje específico del dominio
Para aprovechar al máximo el Asistente de actualización del AGP, haz lo siguiente:
- Configurar la compilación con los archivos de compilación de Gradle: El Asistente de actualización se basa en el análisis estático de los archivos de compilación de Gradle. Para aprovechar al máximo el Asistente de actualización, configura tu compilación con estos archivos de compilación.
- Usa el lenguaje de compilación declarativo específico del dominio: Los archivos de compilación de Gradle se expresan en Groovy o Kotlin. Sin embargo, cuanto más declarativa sea la expresión de la configuración del proyecto, más probable será que el Asistente de actualización encuentre con éxito todos los lugares que necesitan ajustes para una actualización.
Incluso si un proyecto cumple con estas limitaciones, es posible que el Asistente de actualización muestre errores durante el proceso. Consulta la sección de Solución de problemas a fin de obtener instrucciones para resolver o informar errores.
Crea una copia de seguridad de tu proyecto
Antes de comenzar a usar el Asistente de actualización, te recomendamos que tu proyecto no tenga cambios sin confirmar tal como los ve tu sistema de control de versión. Si no usas el control de versiones, usa una copia de seguridad de una última versión buena conocida en ese momento.
Una vez que ejecutes el Asistente de actualización y se compile y pruebe correctamente el proyecto, podrás confirmar la versión nueva del proyecto en tu sistema de control de versión.
Ejecuta el Asistente de actualización
Para ejecutar el Asistente de actualización, sigue estos pasos:
Para iniciar el Asistente de actualización, navega a Tools > AGP Upgrade Assistant o haz clic en el mensaje de notificación, como se muestra en la figura 1.
En la ventana de herramientas que aparece, se muestran los detalles de la actualización predeterminada, incluida la versión actual del AGP del proyecto y la versión más reciente compatible con esta versión de Android Studio.
Figura 1: Ventana de herramientas del Asistente de actualización del AGP durante el inicio y el mensaje notificación. Verifica los pasos obligatorios y los recomendados.
En el panel izquierdo, el árbol con casillas de verificación detalla los pasos individuales de la actualización. Estos están clasificados según si son necesarios o recomendados para la actualización y si son requisitos previos de otros pasos. Selecciona elementos individuales en el árbol para ver más detalles sobre cada paso en el panel principal.
Para ejecutar la actualización, selecciona los pasos necesarios y deseados, y haz clic en Run selected steps.
El Asistente de actualización cambia los archivos de compilación del proyecto y trata de sincronizar la nueva compilación con Android Studio. Esto puede demorar un tiempo si tienes muchos módulos, ya que es posible que debas descargar nuevas versiones de complementos y bibliotecas.
Revisa el informe posterior a la actualización. Este informe describe los pasos que se completaron y si la actualización fue exitosa o no. También incluye una acción para revertir los cambios que realizó el Asistente de actualización si hay problemas de compilación o prueba del proyecto después de la actualización.
Una vez que el proyecto se sincronice correctamente con Android Studio, compílalo y ejecuta conjuntos de pruebas para verificar que la operación de actualización no haya cambiado ninguna funcionalidad.
Una vez que hayas verificado que tu proyecto se encuentra en buen estado, confirma la versión nueva del proyecto en tu sistema de control de versión.
Solución de errores
Si el Asistente de actualización sugiere una actualización, pero esta falla, por lo general, es el resultado de realizar cambios en los archivos de compilación y provocar una falla de sincronización. Sigue estos pasos para aislar y corregir el error:
Primero, inspecciona el error que produjo la falla de sincronización. A veces, el error tiene una causa clara, que puedes solucionar en los archivos de compilación del proyecto.
Si el mensaje de error no es claro o no es evidente la causa del problema, regresa el proyecto a su estado original para dividir la actualización en pasos más pequeños. Restablece el estado original del control de versión o de las copias de seguridad, y asegúrate de que el proyecto esté en su estado original y sincronizado con Android Studio.
Para investigar el error, sigue dos tipos de desgloses de actualización:
Actualiza a una versión del AGP que no sea la más reciente. Si la actualización que salió mal fue de una gran cantidad de versiones, la mejor manera de aislar el problema es realizar una serie de actualizaciones más pequeñas, de una versión a otra, para encontrar la primera que activa el problema.
Dentro de una actualización, realiza los pasos individuales. Una vez que determines la actualización que activa el problema, es posible desactivar los pasos individuales en la actualización. En ese caso, intenta realizar cada paso, uno a la vez, para ver cuál es el responsable del error. Si no encuentras el paso responsable del error, consulta las notas de la versión de los complementos de Gradle que usas para solucionar problemas de compatibilidad con Gradle o AGP. A veces, una versión nueva aborda el uso de APIs internas, o bien obsoletas.
Informa un error. A veces, todos los pasos preparatorios y la sincronización se ejecutan de forma correcta, pero falla el paso de actualización final. En ese caso, informa un error. Incluso si logras corregir el error por tu cuenta, informa el error original en la herramienta de seguimiento de errores para que el equipo de desarrollo pueda solucionarlo.