L'assistente per l'upgrade del plug-in Android Gradle (AGP) è uno strumento di Android Studio che ti aiuta a eseguire l'upgrade della versione di AGP utilizzata dal tuo progetto.
Vengono rilasciati spesso aggiornamenti per le modifiche di AGP relative a nuove funzionalità per la configurazione della build, nuove API da utilizzare con altri plug-in Gradle e perfezionamenti dell'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 di progetto consigliata per l'assistente all'upgrade, consulta Configurazione in questa pagina.
Casi d'uso dell'assistente per l'upgrade di AGP
L'assistente all'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 per l'assistente all'upgrade:
Modifiche alla sintassi: l'assistente all'upgrade tenta di convertire i file di build per una versione precedente di AGP in quelli necessari per una versione più recente di AGP. Man mano che AGP viene sviluppato, i file di build vengono aggiornati per supportare le interfacce man mano che vengono sostituite, ritirate o non supportate nel tempo.
Requisiti di compatibilità tra AGP e Gradle: l'assistente all'upgrade è a conoscenza dei requisiti di compatibilità tra AGP e Gradle e ti aiuta a utilizzare la versione di Gradle richiesta per la tua versione di AGP.
Requisiti di compatibilità tra AGP e plug-in Gradle di terze parti: l'assistente all'upgrade è a conoscenza dei requisiti di compatibilità tra AGP e alcuni plug-in Gradle di terze parti e ti aiuta a utilizzare le versioni dei plug-in Gradle di terze parti richieste 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 all'upgrade spiega anche perché le modifiche proposte sono necessarie.
Come utilizzare l'assistente per l'upgrade di AGP
Per utilizzare l'assistente all'upgrade, assicurati che la struttura del progetto sia compatibile con lo strumento, quindi eseguilo da Android Studio, come descritto in Eseguire l'assistente all'upgrade.
Configura il progetto
Prima di eseguire l'assistente all'upgrade, assicurati che il progetto sia formattato e di cui sia stato eseguito il backup correttamente. Per assicurarti che l'Assistente all'upgrade AGP 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 all'upgrade AGP:
- Configura la build utilizzando i file di build Gradle: Upgrade Assistant
si basa sull'analisi statica dei file di build Gradle. Per ottenere il massimo dall'assistente all'upgrade, configura la build utilizzando questi file di build. Utilizza i
cataloghi delle versioni di Gradle
per fare riferimento a dipendenze e plug-in definiti in un file
libs.versions.tomlnella sottodirectorygradledel tuo progetto.
- Utilizza il linguaggio specifico del dominio di compilazione dichiarativa: i file di build Gradle sono espressi in Groovy o Kotlin. Tuttavia, più è dichiarativa l'espressione della configurazione del progetto, più è probabile che l'assistente all'upgrade trovi correttamente tutti i punti che devono essere modificati per un upgrade.
Anche se un progetto rispetta queste limitazioni, l'assistente all'upgrade potrebbe comunque non riuscire a eseguire un upgrade pulito. Consulta Risoluzione dei problemi relativi agli errori per indicazioni su come risolvere o segnalare i bug.
Eseguire il backup del progetto
Prima di utilizzare Upgrade Assistant, ti consigliamo di assicurarti che il progetto non abbia modifiche non commit, come visualizzato dal sistema di controllo delle versioni. Se non utilizzi il controllo delle versioni, utilizza un backup dell'ultima versione funzionante a questo punto.
Dopo l'esecuzione dell'assistente all'upgrade e la creazione e il test del progetto, puoi eseguire il commit della nuova versione del progetto nel sistema di controllo delle versioni.
Esegui l'assistente all'upgrade
Per eseguire l'assistente all'upgrade:
Per avviare l'assistente all'upgrade, vai a Strumenti > Assistente all'upgrade di AGP o fai clic sul prompt di notifica, come mostrato nella figura 1.
La finestra degli strumenti visualizzata mostra i dettagli dell'upgrade predefinito, inclusi la versione corrente di AGP del progetto e l'ultima versione supportata da questa versione di Android Studio.
Figura 1. La finestra dello strumento Assistente upgrade AGP quando viene avviato con la richiesta di notifica. Controlla i passaggi obbligatori e consigliati.
Nel riquadro a sinistra, l'albero con le caselle di controllo mostra i singoli passaggi dell'upgrade, suddivisi in base al fatto che siano obbligatori o consigliati per l'aggiornamento e se siano 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 richiesti e desiderati e fai clic su Esegui i passaggi selezionati.
L'assistente all'upgrade modifica i file di build del progetto e tenta di sincronizzare la nuova build del progetto con Android Studio. L'operazione potrebbe richiedere un po' di tempo se hai molti moduli, poiché potrebbe essere necessario scaricare nuove versioni di plug-in e librerie.
Esamina il report post-upgrade. Questo report descrive i passaggi completati e indica se l'upgrade è stato eseguito correttamente o meno. Include anche un'azione per ripristinare le modifiche apportate dall'assistente all'upgrade se si verificano problemi di compilazione o test del progetto dopo l'upgrade.
Una volta sincronizzato correttamente il progetto con Android Studio, crea il progetto ed esegui le suite di test per verificare che l'operazione di upgrade non abbia modificato alcuna funzionalità.
Dopo aver verificato che il progetto sia in buono stato, esegui il commit della nuova versione del progetto nel sistema di controllo delle versioni.
Risolvere gli errori
Se l'assistente all'upgrade suggerisce un upgrade, ma questo non va a buon fine, in genere il problema è dovuto a modifiche apportate ai file di build, che causano un errore di sincronizzazione. Per isolare e correggere l'errore, segui questi passaggi:
Innanzitutto, esamina l'errore che ha causato il mancato funzionamento della 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 non è ovvio cosa stia causando il problema, ripristina lo stato originale del progetto per suddividere l'upgrade in passaggi più piccoli. Ripristina lo stato originale dal controllo delle versioni o dai backup e assicurati che il progetto sia nel suo stato originale e sincronizzato con Android Studio.
Esamina l'errore seguendo due tipi di suddivisione dell'upgrade:
Esegui l'upgrade a una versione diversa di AGP che non sia l'ultima. Se l'aggiornamento che non è andato a buon fine riguardava un numero elevato di versioni, il modo migliore per isolare il problema è eseguire una serie di aggiornamenti più piccoli, di versione in versione, per trovare il primo aggiornamento che attiva il problema.
Durante un upgrade, esegui i singoli passaggi uno alla volta. Una volta determinato l'upgrade che causa il problema, potrebbe essere possibile disattivare i singoli passaggi dell'upgrade. Se è possibile, prova a eseguire ogni passaggio uno alla volta per scoprire quale di questi è responsabile dell'errore. Se non riesci a trovare il passaggio responsabile, controlla le note di rilascio di altri plug-in Gradle che utilizzi per verificare la presenza di problemi di compatibilità con Gradle o AGP. A volte, una nuova release riguarda l'utilizzo di API interne o ritirate.
Segnala un bug. A volte tutti i passaggi preparatori e la sincronizzazione vanno a buon fine, ma l'ultimo passaggio di upgrade non riesce. In questo caso, segnala un bug. Anche se riesci a correggere l'errore autonomamente, segnala l'errore originale al bug tracker, in modo che il problema possa essere risolto dal team di sviluppo.