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.
Vengono rilasciati frequentemente aggiornamenti per le modifiche di AGP relative alle nuove funzionalità per la configurazione della build, alle nuove API da utilizzare da altri plug-in Gradle e ai 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 del progetto consigliata per l'assistente per l'upgrade, consulta la sezione Configurazione in questa pagina.
Casi d'uso dell'assistente per l'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 tenta di tradurre 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 per l'upgrade è a conoscenza dei requisiti di compatibilità tra AGP e Gradle e ti aiuta ad assicurarti di 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 per l'upgrade è a conoscenza dei requisiti di compatibilità tra AGP e alcuni plug-in Gradle di terze parti e ti aiuta ad assicurarti di utilizzare le versioni dei plug-in Gradle di terze parti richieste per la tua versione di AGP.
In generale, l'assistente per l'upgrade 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 per l'upgrade di AGP
Per utilizzare l'assistente per l'upgrade, assicurati che la struttura del progetto sia compatibile con lo strumento, quindi eseguilo da Android Studio, come descritto in 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 l'assistente per l'upgrade di 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 per l'upgrade di AGP:
- Configura la build utilizzando i file di build Gradle: l'assistente per l'upgrade
si basa sull'analisi statica dei file di build Gradle. Per sfruttare al meglio l'assistente per l'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 build dichiarativo: i file di build Gradle sono espressi in Groovy o Kotlin. Tuttavia, più dichiarativa è l'espressione della configurazione del progetto, maggiore è la probabilità che l'assistente per l'upgrade trovi correttamente tutti i punti che richiedono una modifica 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. Consulta Risolvere i problemi per indicazioni su come risolvere o segnalare i bug.
Esegui il backup del progetto
Prima di utilizzare l'assistente per l'upgrade, ti consigliamo di assicurarti 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, a questo punto utilizza un backup dell'ultima versione funzionante.
Dopo aver eseguito l'assistente per l'upgrade e aver creato e testato correttamente il progetto, puoi eseguire il commit della nuova versione del progetto nel sistema di controllo della versione.
Esegui l'assistente per l'upgrade
Per eseguire l'assistente per l'upgrade:
Per avviare l'assistente per l'upgrade, vai a Strumenti > Assistente per l'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, inclusa la versione attuale di AGP del progetto e la versione più recente supportata da questa versione di Android Studio.
Figura 1. La finestra degli strumenti dell'assistente per l'upgrade di AGP quando viene avviata con il prompt 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 obbligatori 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. Questa operazione potrebbe richiedere un po' di tempo se hai numerosi 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 se l'upgrade è riuscito o meno. Include anche 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.
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 uno stato ottimale, esegui il commit della nuova versione del progetto nel sistema di controllo della versione.
Risolvere i problemi
Se l'assistente per l'upgrade suggerisce un upgrade, ma l'upgrade non riesce, in genere è dovuto a modifiche apportate ai file di build, che comportano un errore di sincronizzazione. Segui questi passaggi per isolare e correggere l'errore:
Innanzitutto, esamina 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 non è ovvio quale sia la causa del problema, ripristina lo stato originale del progetto 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 nello stato originale e sincronizzato con Android Studio.
Esamina l'errore seguendo due tipi di suddivisioni dell'upgrade:
Esegui l'upgrade a una versione di AGP diversa dalla versione più recente. Se l'upgrade non riuscito riguardava un upgrade di un numero elevato di versioni, il modo migliore per isolare il problema è eseguire una serie di upgrade più piccoli, di versione in versione, per trovare il primo upgrade che attiva il problema.
Durante un upgrade, esegui i singoli passaggi uno alla volta. Una volta determinato l'upgrade che attiva il problema, potrebbe essere possibile disattivare i singoli passaggi dell'upgrade. Se possibile, prova a eseguire ogni passaggio uno alla volta per trovare quello responsabile dell'errore. Se non riesci a trovare il passaggio responsabile, controlla le note di rilascio di eventuali altri plug-in Gradle che utilizzi per verificare la presenza di problemi di compatibilità con Gradle o AGP. A volte, una nuova uscita risolve l'utilizzo di API ritirate o interne.
Segnala un bug. A volte tutti i passaggi preparatori e la sincronizzazione vanno a buon fine, ma il passaggio di upgrade finale non riesce. In questo caso, segnala un bug. Anche se riesci a correggere l'errore da solo, segnala l'errore originale al tracker dei bug, in modo che il problema possa essere risolto dal team di sviluppo.