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.

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'assistente per l'upgrade, 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'Upgrade Assistant 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 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'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 all'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'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.

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 tuo progetto.
  • Utilizza il linguaggio specifico di dominio di build dichiarativo: i file di build Gradle sono espressi in Groovy o Kotlin. Tuttavia, più l'espressione della configurazione del progetto è dichiarativa, 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'Upgrade Assistant 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'assistente per l'upgrade e la corretta creazione e verifica 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 eseguire l'assistente per l'upgrade, segui questi passaggi:

  1. 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, tra cui la versione corrente di AGP del progetto e l'ultima versione supportata da questa versione di Android Studio.

    La finestra degli strumenti dell'assistente per l'upgrade di AGP quando viene avviata e la richiesta di notifica.
    Figura 1. La finestra degli strumenti dell'assistente per l'upgrade di AGP quando viene avviata con il prompt di notifica.

  2. Controlla i passaggi obbligatori e consigliati.

    Nel riquadro a sinistra, l'albero con le caselle di controllo mostra 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 gli eventuali passaggi aggiuntivi che vuoi eseguire, quindi 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. Se hai molti moduli, l'operazione potrebbe richiedere un po' di tempo, 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 se si verificano problemi durante la creazione o il 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. Dopo aver 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'assistente per l'upgrade suggerisce un upgrade, ma questo non va a buon fine, in genere il problema è 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 non riuscito 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 individuato 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 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.