Der AGP-Upgrade-Assistent (Android Gradle-Plug-in) ist ein Tool in Android Studio, mit dem Sie die Version des AGP, die von Ihrem Projekt verwendet wird, aktualisieren können.
Es gibt häufig Releases für AGP-Änderungen im Zusammenhang mit neuen Funktionen zum Konfigurieren Ihres Builds, neuen APIs zur Verwendung durch andere Gradle-Plug-ins und Verbesserungen bei der Integration des Projekt-Builds in Android Studio. Wenn Sie die von Ihrem Projekt verwendete Version von AGP aktualisieren, können Sie die neuesten Funktionen nutzen.
Weitere Informationen zur empfohlenen Projektstruktur für den Upgrade Assistant finden Sie auf dieser Seite unter Einrichtung.
Anwendungsfälle für den AGP Upgrade Assistant
Der AGP Upgrade Assistant führt Sie durch die Änderungen, die für ein Upgrade von AGP-Versionen erforderlich sind. Im Folgenden sind die häufigsten Anwendungsfälle für den Upgrade Assistant aufgeführt:
Syntaxänderungen: Der Upgrade Assistant versucht, Ihre Build-Dateien für eine ältere Version von AGP in die für eine neuere Version von AGP erforderlichen Dateien zu übersetzen. Im Laufe der Entwicklung von AGP werden Build-Dateien aktualisiert, um Schnittstellen zu unterstützen, wenn sie im Laufe der Zeit ersetzt, eingestellt oder nicht mehr unterstützt werden.
Kompatibilitätsanforderungen zwischen AGP und Gradle: Der Upgrade Assistant berücksichtigt die Kompatibilitätsanforderungen zwischen AGP und Gradle und sorgt dafür, dass Sie die für Ihre AGP-Version erforderliche Gradle-Version verwenden.
Kompatibilitätsanforderungen zwischen AGP und Gradle-Plug-ins von Drittanbietern: Der Upgrade Assistant berücksichtigt die Kompatibilitätsanforderungen zwischen AGP und einigen Gradle-Plug-ins von Drittanbietern und sorgt dafür, dass Sie die Versionen von Gradle-Plug-ins von Drittanbietern verwenden, die für Ihre AGP-Version erforderlich sind.
Im Allgemeinen erleichtert der Upgrade Assistant das Aktualisieren von Build-Dateien und das Verstehen zugehöriger Fehlermeldungen nach einem AGP-Upgrade. Der Upgrade Assistant erklärt auch, warum die vorgeschlagenen Änderungen erforderlich sind.
AGP Upgrade Assistant verwenden
Damit Sie den Upgrade Assistant verwenden können, muss Ihre Projektstruktur für das Tool geeignet sein. Führen Sie es dann in Android Studio aus, wie unter Upgrade Assistant ausführen beschrieben.
Projekt einrichten
Bevor Sie den Upgrade Assistant ausführen, sollten Sie sicherstellen, dass Ihr Projekt richtig formatiert und gesichert ist. In den folgenden Abschnitten erfahren Sie, wie Sie den AGP Upgrade Assistant richtig einrichten.
Projekt mit den Gradle-Build-Dateien und der domänenspezifischen Sprache strukturieren
So nutzen Sie den AGP Upgrade Assistant optimal:
- Build mit den Gradle-Build-Dateien konfigurieren: Der Upgrade Assistant basiert auf der statischen Analyse der Gradle-Build-Dateien. Um den Upgrade Assistant optimal nutzen zu können, konfigurieren Sie Ihren Build mit diesen Build-Dateien. Verwenden Sie Gradle-Versionskataloge, um auf Abhängigkeiten und Plug-ins zu verweisen, die in einer
libs.versions.toml-Datei im UnterverzeichnisgradleIhres Projekts definiert sind.
- Deklarative domainspezifische Sprache für Builds verwenden: Gradle-Build-Dateien werden in Groovy oder Kotlin ausgedrückt. Je deklarativer die Projektkonfiguration ist, desto wahrscheinlicher ist es, dass der Upgrade Assistant alle Stellen findet, die für ein Upgrade angepasst werden müssen.
Auch wenn ein Projekt diesen Einschränkungen entspricht, kann es sein, dass der Upgrade Assistant kein sauberes Upgrade durchführen kann. Informationen zum Beheben oder Melden von Fehlern finden Sie unter Fehlerbehebung.
Projekt sichern
Bevor Sie den Upgrade Assistant verwenden, empfehlen wir, dass Ihr Projekt keine nicht übergebenen Änderungen enthält, wie von Ihrem Versionsverwaltungssystem angezeigt. Wenn Sie keine Versionskontrolle verwenden, sollten Sie an dieser Stelle ein Backup einer zuletzt funktionierenden Version verwenden.
Nachdem der Upgrade Assistant ausgeführt wurde und das Projekt erfolgreich erstellt und getestet wurde, können Sie die neue Version des Projekts in Ihrem Versionsverwaltungssystem committen.
Upgrade Assistant ausführen
So führen Sie den Upgrade-Assistenten aus:
Rufen Sie den Upgrade Assistant auf, indem Sie zu Tools > AGP Upgrade Assistant navigieren oder auf die Benachrichtigung tippen (siehe Abbildung 1).
Im angezeigten Toolfenster werden die Details des Standardupgrades angezeigt, einschließlich der aktuellen AGP-Version des Projekts und der neuesten Version, die von dieser Version von Android Studio unterstützt wird.
Abbildung 1. Das Toolfenster „AGP Upgrade Assistant“ wird über die Benachrichtigung gestartet. Prüfen Sie die erforderlichen und empfohlenen Schritte.
Im linken Bereich wird der Baum mit Kästchen angezeigt, in dem die einzelnen Schritte des Upgrades aufgeführt sind. Sie sind danach kategorisiert, ob sie für die Aktualisierung erforderlich oder empfohlen sind und ob sie Voraussetzungen für andere Schritte sind. Wählen Sie einzelne Elemente im Baum aus, um weitere Informationen zu den einzelnen Schritten im Hauptbereich aufzurufen.
Wählen Sie die erforderlichen und gewünschten Schritte aus und klicken Sie auf Ausgewählte Schritte ausführen, um das Upgrade auszuführen.
Der Upgrade Assistant ändert die Build-Dateien des Projekts und versucht, den neuen Projekt-Build mit Android Studio zu synchronisieren. Wenn Sie viele Module haben, kann das eine Weile dauern, da möglicherweise neue Versionen von Plug-ins und Bibliotheken heruntergeladen werden müssen.
Sehen Sie sich den Bericht nach dem Upgrade an. In diesem Bericht werden die ausgeführten Schritte beschrieben und es wird angegeben, ob das Upgrade erfolgreich war. Außerdem ist eine Aktion enthalten, mit der Änderungen rückgängig gemacht werden können, die vom Upgrade-Assistenten vorgenommen wurden, wenn nach dem Upgrade Probleme beim Erstellen oder Testen des Projekts auftreten.
Nachdem das Projekt erfolgreich mit Android Studio synchronisiert wurde, erstellen Sie das Projekt und führen Sie Testläufe aus, um zu prüfen, ob durch das Upgrade Funktionen geändert wurden.
Wenn Sie sich vergewissert haben, dass Ihr Projekt in einem guten Zustand ist, übertragen Sie die neue Version Ihres Projekts in Ihr Versionskontrollsystem.
Fehlerbehebung
Wenn der Upgrade Assistant ein Upgrade vorschlägt, das dann aber fehlschlägt, liegt das in der Regel daran, dass Änderungen an den Build-Dateien vorgenommen wurden, was zu einem Synchronisierungsfehler führt. So können Sie den Fehler eingrenzen und beheben:
Sehen Sie sich zuerst den Fehler an, der zum Synchronisierungsfehler geführt hat. Manchmal hat der Fehler eine klare Ursache, die Sie in den Build-Dateien des Projekts beheben können.
Wenn die Fehlermeldung nicht eindeutig ist oder nicht klar ist, was das Problem verursacht, setzen Sie das Projekt in den ursprünglichen Zustand zurück, um das Upgrade in kleinere Schritte zu unterteilen. Stellen Sie den ursprünglichen Zustand aus der Versionsverwaltung oder aus Sicherungen wieder her und sorgen Sie dafür, dass sich das Projekt im ursprünglichen Zustand befindet und mit Android Studio synchronisiert wird.
Untersuchen Sie den Fehler anhand von zwei Arten von Upgrade-Aufschlüsselungen:
Führen Sie ein Upgrade auf eine andere Version von AGP durch, die nicht die neueste Version ist. Wenn das fehlgeschlagene Upgrade ein Upgrade einer großen Anzahl von Versionen war, ist es am besten, das Problem durch eine Reihe kleinerer Upgrades von Version zu Version zu isolieren, um das erste Upgrade zu finden, das das Problem auslöst.
Führen Sie bei einem Upgrade die einzelnen Schritte nacheinander aus. Sobald Sie das Upgrade ermittelt haben, das das Problem auslöst, können Sie möglicherweise einzelne Schritte im Upgrade deaktivieren. Wenn das möglich ist, führen Sie die einzelnen Schritte nacheinander aus, um herauszufinden, welcher Schritt für den Fehler verantwortlich ist. Wenn Sie den verantwortlichen Schritt nicht finden können, prüfen Sie die Versionshinweise aller anderen Gradle-Plug-ins, die Sie verwenden, auf Kompatibilitätsprobleme mit Gradle oder AGP. Manchmal wird mit einer neuen Version die Verwendung von eingestellten oder internen APIs behoben.
Fehler melden Manchmal sind alle Vorbereitungsschritte und die Synchronisierung erfolgreich, aber der letzte Upgradeschritt schlägt trotzdem fehl. Melden Sie in diesem Fall bitte einen Fehler. Auch wenn Sie den Fehler selbst beheben können, melden Sie den ursprünglichen Fehler im Bugtracker, damit das Entwicklungsteam das Problem beheben kann.