L'Assistente per l'upgrade del plug-in Android per Gradle (AGP) è uno strumento di Android Studio che ti aiuta a eseguire l'upgrade della versione di AGP utilizzata dal tuo progetto.
Esistono release frequenti per modifiche AGP relative a nuove funzionalità per la configurazione della build, nuove API per l'utilizzo da parte di altri plug-in Gradle e perfezionamenti all'integrazione della build del progetto con Android Studio. L'upgrade della versione di AGP utilizzata dal tuo progetto ti consente di usufruire delle funzionalità più recenti.
Per ulteriori informazioni sulla struttura del progetto consigliata per l'Assistente per l'upgrade, consulta Configurazione in questa pagina.
Casi d'uso dell'assistente con upgrade di AGP
L'Assistente per l'upgrade di AGP ti guida attraverso le modifiche necessarie per eseguire l'upgrade delle versioni di AGP. Di seguito sono riportati i casi d'uso più comuni dell'Assistente per l'upgrade:
Modifiche alla sintassi: l'Assistente per l'upgrade cerca di tradurre i file della build di una versione precedente di AGP in quelli necessari per una versione più recente di AGP. Man mano che AGP viene sviluppata, i file di build vengono aggiornati per supportare le interfacce quando vengono sostituite, deprecate o non supportate nel tempo.
Requisiti di compatibilità tra AGP e Gradle: l'Assistente upgrade è consapevole dei requisiti di compatibilità tra AGP e Gradle e aiuta ad assicurarsi di utilizzare la versione di Gradle richiesta per la propria versione di AGP.
Requisiti di compatibilità tra AGP e plug-in Gradle di terze parti: Upgrade Assistant è consapevole dei requisiti di compatibilità tra AGP e alcuni plug-in Gradle di terze parti e aiuta a garantire che stai utilizzando le versioni dei plug-in Gradle di terze parti necessarie per la tua versione di AGP.
In generale, Upgrade Assistant semplifica l'aggiornamento dei file di build e la comprensione dei messaggi di errore correlati dopo un upgrade di AGP. L'Assistente per l'upgrade spiega anche perché le modifiche proposte sono necessarie.
Come utilizzare l'Assistente di upgrade AGP
Per utilizzare l'Assistente per l'upgrade, assicurati che la struttura del progetto supporti lo strumento, quindi eseguilo da Android Studio, come descritto nella sezione Eseguire l'Assistente per l'upgrade.
Configura il progetto
Prima di eseguire l'Assistente per l'upgrade, assicurati che il progetto sia formattato correttamente e che sia stato eseguito il backup. Per assicurarti che AGP Upgrade Assistant sia configurato correttamente, leggi le sezioni seguenti.
Strutturare il progetto utilizzando i file di build Gradle e il linguaggio specifico del dominio
Per utilizzare al meglio l'Assistente di upgrade AGP, procedi nel seguente modo:
- Configura la build utilizzando i file di build Gradle: l'Assistente per gli upgrade si basa sull'analisi statica dei file di build di Gradle. Per ottenere il massimo da Upgrade Assistant, configura la tua build utilizzando questi file di build.
- Utilizza il linguaggio specifico per il dominio della build dichiarativo: i file di build Gradle sono espressi in Groovy o Kotlin. Tuttavia, più l'espressione della configurazione del progetto è dichiarativa, maggiori sono le probabilità che l'Assistente per l'upgrade trovi correttamente tutte le posizioni che necessitano di modifiche per un upgrade.
Anche se un progetto è conforme a queste limitazioni, l'Assistente per l'upgrade potrebbe comunque non riuscire a eseguire un upgrade pulito. Per indicazioni su come risolvere o segnalare bug, consulta la sezione Risoluzione degli errori.
Esegui il backup del progetto
Prima di utilizzare Upgrade Assistant, ti consigliamo di fare in modo che il progetto non abbia modifiche di cui non è stato eseguito il commit, come indicato dal sistema di controllo della versione. Se non utilizzi il controllo della versione, utilizza il backup dell'ultima versione non funzionante nota che è stata aggiornata.
Dopo l'esecuzione dell'Assistente per l'upgrade e la creazione e il test del progetto, puoi eseguire il commit della nuova versione del progetto nel tuo sistema di controllo della versione.
Esegui l'Assistente per l'upgrade
Per utilizzare l'Assistente per l'upgrade, procedi nel seguente modo:
Per avviare l'Assistente per l'upgrade, vai a Strumenti > AGP Upgrade Assistant o fai clic sulla richiesta di notifica, come mostrato nella figura 1.
Nella finestra dello strumento visualizzata sono visualizzati i dettagli dell'upgrade predefinito, tra cui la versione attuale di AGP del progetto e l'ultima versione supportata da questa versione di Android Studio.
Figura 1. La finestra dello strumento Assistente di upgrade AGP quando viene avviata con la richiesta di notifica. Controlla i passaggi obbligatori e consigliati.
Nel riquadro a sinistra, la struttura ad albero con le caselle di controllo descrive in dettaglio i singoli passaggi dell'upgrade, classificati in base al fatto che l'aggiornamento è obbligatorio o consigliato e se sono prerequisiti di altri passaggi. Seleziona i singoli elementi nell'albero per visualizzare ulteriori dettagli su ogni passaggio nel riquadro principale.
Per eseguire l'upgrade, seleziona i passaggi necessari e desiderati e fai clic su Esegui i passaggi selezionati.
L'Assistente per l'upgrade modifica i file di build del progetto e tenta di sincronizzare la nuova build del progetto con Android Studio. Se sono presenti numerosi moduli, questa operazione potrebbe richiedere del tempo, poiché potrebbe essere necessario scaricare nuove versioni di plug-in e librerie.
Esamina il report successivo all'upgrade. Questo report descrive i passaggi completati e se l'upgrade è riuscito o meno. Include inoltre un'azione per ripristinare le modifiche apportate dall'assistente per l'upgrade in caso di problemi di creazione o test del progetto dopo l'upgrade.
Dopo aver sincronizzato il progetto con Android Studio, crea il progetto ed esegui suite di test per verificare che l'operazione di upgrade non abbia cambiato alcuna funzionalità.
Dopo aver verificato che il progetto sia in buono stato, esegui il commit della nuova versione del progetto nel sistema di controllo della versione.
Risolvere gli errori
Se l'Assistente per l'upgrade suggerisce un upgrade ma l'upgrade non riesce, in genere ciò è dovuto all'apporto di modifiche ai file di build, con conseguente errore di sincronizzazione. Segui questi passaggi per isolare e correggere l'errore:
Innanzitutto, controlla l'errore che ha causato l'errore di sincronizzazione. A volte l'errore ha una causa chiara, che puoi risolvere nei file di build del progetto.
Se il messaggio di errore non è chiaro o la causa del problema non è chiara, ripristina il progetto allo stato originale per suddividere l'upgrade in passaggi più piccoli. Ripristina lo stato originale dal controllo della versione o dai backup e assicurati che il progetto sia nel suo stato originale e che sia sincronizzato con Android Studio.
Esamina l'errore seguendo due tipi di suddivisione dell'upgrade:
Esegui l'upgrade a una versione diversa di AGP diversa da quella più recente. Se l'upgrade sbagliato riguarda un numero elevato di versioni, il modo migliore per isolare il problema consiste nell'eseguire una serie di upgrade più piccoli, da una versione all'altra, in modo da individuare il primo upgrade che attiva il problema.
All'interno di un upgrade, esegui i singoli passaggi uno alla volta. Una volta stabilito l'upgrade che attiva il problema, potrebbe essere possibile disattivare i singoli passaggi dell'upgrade. Se possibile, prova a eseguire ciascun passaggio uno alla volta per scoprire quale di questi è responsabile dell'errore. Se non riesci a trovare il passaggio responsabile, consulta le note di rilascio di eventuali altri plug-in Gradle che stai utilizzando per verificare la presenza di problemi di compatibilità con Gradle o AGP. A volte, una nuova release riguarda l'uso di API deprecate o interne.
Segnala un bug. A volte tutti i passaggi preparatori e la sincronizzazione hanno esito positivo, ma l'upgrade finale non va a buon fine. In questo caso, segnala un bug. Anche se riesci a correggere l'errore autonomamente, segnala l'errore originale al tracker dei bug, in modo che il problema possa essere risolto dal team di sviluppo.