Utilizzare l'upgrade dell'assistente per il plug-in Android per Gradle

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.

android skills add agp-9-upgrade

Le release per le modifiche di AGP relative alle nuove funzionalità per la configurazione della build, alle nuove API per l'utilizzo da parte di altri plug-in Gradle e ai perfezionamenti dell'integrazione della build del progetto con Android Studio sono frequenti. L'upgrade della versione di AGP utilizzata dal tuo progetto ti consente di usufruire delle funzionalità più recenti.

Per saperne di più sulla struttura del progetto consigliata per l'Upgrade Assistant, consulta 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 all'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 a verificare che tu stia utilizzando 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 a verificare che tu stia utilizzando le versioni dei plug-in Gradle di terze parti richieste per la tua versione di AGP.

In generale, l'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 per l'upgrade di AGP

Per utilizzare l'Upgrade Assistant, assicurati che la struttura del progetto sia compatibile con lo strumento, quindi eseguilo da Android Studio, come descritto in Esegui l'Upgrade Assistant.

Configura il progetto

Prima di eseguire l'Upgrade Assistant, 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.

Struttura 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, segui questi passaggi:

• Configura la build utilizzando i file di build di Gradle: l'assistente per l'upgrade si basa sull'analisi statica dei file di build di Gradle. Per ottenere il massimo dall'assistente per l'upgrade, configura la build utilizzando questi file di build. Utilizza i cataloghi delle versioni di Gradle per fare riferimento alle dipendenze e ai plug-in definiti in un file libs.versions.toml nella sottodirectory gradle del progetto.

• Utilizza il linguaggio specifico del dominio di build dichiarativo: i file di build di Gradle sono espressi in Groovy o Kotlin. Tuttavia, più è dichiarativa l'espressione della configurazione del progetto, più è probabile che l'assistente per l'upgrade trovi correttamente tutti i punti che devono essere modificati per un upgrade.

Anche se un progetto rispetta queste limitazioni, l'assistente per l'upgrade potrebbe comunque non riuscire a eseguire un upgrade pulito. Consulta Risolvi gli errori 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 tuo progetto non contenga modifiche di cui non è stato eseguito il commit, come indicato dal sistema di controllo della versione. Se non utilizzi il controllo della versione, utilizza un backup dell'ultima versione valida nota a questo punto.

Dopo l'esecuzione dell'Upgrade Assistant e la corretta creazione e verifica del 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, segui questi passaggi:

1. Per avviare l'Upgrade Assistant, vai a Tools > AGP Upgrade Assistant o fai clic sul prompt di notifica, come mostrato nella figura 1.

   La finestra degli strumenti visualizzata mostra i dettagli dell'upgrade predefinito, tra cui la versione corrente di AGP del progetto e l'ultima versione supportata da questa versione di Android Studio.

   

2. Controlla i passaggi obbligatori e consigliati.

   Nel riquadro a sinistra, l'albero con le caselle di controllo descrive i singoli passaggi dell'upgrade, classificati in base al fatto che siano obbligatori o consigliati per l'aggiornamento e se sono prerequisiti di altri passaggi. Seleziona i singoli elementi nell'albero per visualizzare ulteriori dettagli su ogni passaggio nel riquadro principale.

3. Per eseguire l'upgrade, seleziona i passaggi richiesti e desiderati e fai clic su Esegui i passaggi selezionati.

   L'Upgrade Assistant 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.

4. Esamina il report post-upgrade. Questo report descrive i passaggi completati e se l'upgrade è stato eseguito correttamente o meno. Include anche un'azione per annullare le modifiche apportate dall'assistente per l'upgrade in caso di problemi di creazione o test del progetto dopo l'upgrade.

5. Una volta sincronizzato 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à.

6. Una volta verificato che il progetto è in uno stato corretto, esegui il commit della nuova versione del progetto nel sistema di controllo della versione.

Risoluzione degli errori

Se l'Upgrade Assistant suggerisce un upgrade, ma questo non va a buon fine, in genere è dovuto a modifiche ai file di build, che causano 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 è evidente la causa del problema, riporta 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 nello stato originale e sincronizzato con Android Studio.

Esamina l'errore seguendo due tipi di analisi degli upgrade:

• Esegui l'upgrade a una versione diversa di AGP che non sia l'ultima versione. Se l'upgrade che ha causato problemi riguardava un numero elevato di versioni, il modo migliore per isolare il problema è eseguire una serie di upgrade più piccoli, da una versione all'altra, per trovare il primo upgrade che attiva il problema.

• All'interno di 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 scoprire quale di questi è 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 release risolve l'utilizzo di API deprecate o interne.

• Segnala un bug. A volte tutti i passaggi preparatori e la sincronizzazione vanno a buon fine, ma il passaggio finale dell'upgrade non riesce. 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.