Das Android Gradle-Plug-in (AGP) Upgrade Assistant ist ein Tool in Android Studio, mit dem Sie die von Ihrem Projekt verwendete AGP-Version aktualisieren können.
Es gibt regelmäßig Releases für AGP-Änderungen im Zusammenhang mit neuen Funktionen zum Konfigurieren des Builds, neuen APIs zur Verwendung durch andere Gradle-Plug-ins und Verbesserungen der Integration des Projekt-Builds in Android Studio. Durch ein Upgrade der von Ihrem Projekt verwendeten AGP-Version können Sie die neuesten Features nutzen.
Weitere Informationen zur empfohlenen Projektstruktur für den Upgrade-Assistenten finden Sie unter Einrichtung auf dieser Seite.
Anwendungsfälle für AGP Upgrade Assistant
Der AGP-Upgradeassistent führt Sie durch die Änderungen, die für das Upgrade von AGP-Versionen erforderlich sind. Im Folgenden sind die häufigsten Anwendungsfälle für Upgrade Assistant aufgeführt:
Syntaxänderungen: Der Upgrade-Assistent versucht, Ihre Build-Dateien für eine ältere AGP-Version in eine neuere Version von AGP zu übersetzen. Bei der Entwicklung von AGP werden Build-Dateien aktualisiert, um Schnittstellen zu unterstützen, sobald sie ersetzt, verworfen oder nicht mehr unterstützt werden.
Kompatibilitätsanforderungen zwischen AGP und Gradle: Der Upgrade-Assistent kennt die Kompatibilitätsanforderungen zwischen AGP und Gradle und sorgt dafür, dass Sie die für Ihre AGP-Version erforderliche Version von Gradle verwenden.
Kompatibilitätsanforderungen zwischen AGP und Gradle-Plug-ins von Drittanbietern: Der Upgrade-Assistent kennt die Kompatibilitätsanforderungen zwischen AGP und einigen Gradle-Plug-ins von Drittanbietern und sorgt dafür, dass Sie die Versionen der Gradle-Plug-ins von Drittanbietern verwenden, die für Ihre AGP-Version erforderlich sind.
Im Allgemeinen erleichtert der Upgrade-Assistent die Aktualisierung von Build-Dateien und die Interpretation zugehöriger Fehlermeldungen nach einem AGP-Upgrade. Der Upgrade-Assistent erklärt auch, warum die vorgeschlagenen Änderungen notwendig sind.
AGP-Upgradeassistent verwenden
Wenn Sie den Upgrade-Assistenten verwenden möchten, muss das Tool in Ihrer Projektstruktur vorhanden sein. Führen Sie es dann wie unter Upgrade-Assistent ausführen beschrieben aus.
Projekt einrichten
Prüfen Sie vor dem Ausführen des Upgrade-Assistenten, ob Ihr Projekt ordnungsgemäß formatiert und gesichert ist. In den folgenden Abschnitten erfahren Sie, ob der AGP-Upgradeassistent korrekt eingerichtet ist.
Projekt mit den Gradle-Build-Dateien und der domainspezifischen Sprache strukturieren
So nutzen Sie den AGP-Upgradeassistenten optimal:
- Build mit den Gradle-Build-Dateien konfigurieren: Der Upgrade-Assistent benötigt die statische Analyse der Gradle-Build-Dateien. Konfigurieren Sie Ihren Build mit diesen Build-Dateien, um den Upgrade-Assistenten optimal zu nutzen.
- Deklarative, domainspezifische Build-Sprache verwenden: Gradle-Build-Dateien werden in Groovy oder Kotlin angegeben. Je deklarativer der Ausdruck der Projektkonfiguration jedoch ist, desto wahrscheinlicher ist es, dass der Upgrade-Assistent alle Stellen findet, die für ein Upgrade angepasst werden müssen.
Auch wenn ein Projekt diesen Einschränkungen entspricht, führt der Upgrade-Assistent möglicherweise trotzdem kein sauberes Upgrade aus. Informationen zum Beheben oder Melden von Fehlern finden Sie unter Fehler beheben.
Projekt sichern
Bevor Sie den Upgrade-Assistenten verwenden, sollten Sie in Ihrem Projekt keine Änderungen ohne Commit vornehmen, wie von Ihrem Versionskontrollsystem erkannt wird. Wenn Sie keine Versionsverwaltung verwenden, nutzen Sie zu diesem Zeitpunkt eine Sicherung einer letzten als fehlerfrei bekannten Version.
Nachdem der Upgrade-Assistent ausgeführt wurde und das Projekt erfolgreich erstellt und getestet wurde, können Sie die neue Version des Projekts an Ihr Versionsverwaltungssystem übertragen.
Upgrade-Assistenten ausführen
So führen Sie den Upgrade-Assistenten aus:
Rufen Sie zum Starten des Upgrade-Assistenten Tools > AGP-Upgrade-Assistent auf oder klicken Sie auf die Benachrichtigungsaufforderung (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 Fenster des AGP-Upgradeassistenten, wenn das Tool mit einer Benachrichtigungsaufforderung gestartet wird. Überprüfen Sie die erforderlichen und empfohlenen Schritte.
Im linken Bereich sind in der Baumstruktur mit Kästchen die einzelnen Schritte im Upgrade aufgeführt. Sie sind danach kategorisiert, ob sie für das Update erforderlich oder empfohlen werden und ob sie eine Voraussetzung für andere Schritte sind. Wählen Sie einzelne Elemente in der Struktur aus, um weitere Details zu den einzelnen Schritten im Hauptsteuerfeld aufzurufen.
Wählen Sie zum Ausführen des Upgrades die erforderlichen und gewünschten Schritte aus und klicken Sie auf Ausgewählte Schritte ausführen.
Der Upgrade-Assistent ändert die Build-Dateien des Projekts und versucht, das neue Projekt mit Android Studio zu synchronisieren. Dies kann bei einer Vielzahl von Modulen einige Zeit dauern, da neue Versionen von Plug-ins und Bibliotheken möglicherweise heruntergeladen werden müssen.
Lesen Sie den Bericht nach der Umstellung. In diesem Bericht werden die Schritte beschrieben, die durchgeführt wurden und ob das Upgrade erfolgreich oder nicht erfolgreich war. Sie umfasst auch eine Aktion zum Rückgängigmachen von Änderungen, die vom Upgrade-Assistenten vorgenommen wurden, wenn nach dem Upgrade Probleme beim Erstellen oder Testen des Projekts auftreten.
Sobald das Projekt erfolgreich mit Android Studio synchronisiert wurde, erstellen Sie das Projekt und führen Sie Testsuiten aus, um zu prüfen, ob sich durch den Upgradevorgang keine Änderungen an der Funktionalität vorgenommen haben.
Nachdem Sie den einwandfreien Zustand Ihres Projekts überprüft haben, übertragen Sie die neue Version Ihres Projekts an Ihr Versionskontrollsystem.
Fehler beheben
Wenn der Upgrade-Assistent ein Upgrade vorschlägt, das Upgrade jedoch fehlschlägt, liegt dies in der Regel an Änderungen an den Build-Dateien, die zu einem Synchronisierungsfehler führen. Führen Sie die folgenden Schritte aus, um den Fehler zu isolieren und zu beheben:
Untersuchen Sie zuerst den Fehler, der zum Synchronisierungsfehler geführt hat. Manchmal hat der Fehler eine eindeutige Ursache, die Sie in den Build-Dateien des Projekts beheben können.
Wenn die Fehlermeldung nicht eindeutig ist oder nicht offensichtlich ist, was das Problem verursacht, setzen Sie das Projekt in seinen ursprünglichen Zustand zurück, um das Upgrade in kleinere Schritte aufzuteilen. Stellen Sie den ursprünglichen Zustand aus der Versionsverwaltung oder aus Sicherungen wieder her und achten Sie darauf, dass sich das Projekt in seinem ursprünglichen Zustand befindet und mit Android Studio synchronisiert ist.
Überprüfen Sie den Fehler anhand der folgenden zwei Arten von Upgradeaufschlüsselungen:
Führen Sie ein Upgrade auf eine andere AGP-Version durch, die nicht die aktuelle Version ist. Wenn das schiefgelaufene Upgrade ein Upgrade einer großen Anzahl von Versionen war, lässt sich das Problem am besten isolieren, indem Sie eine Reihe kleinerer Upgrades von Version zu Version durchführen, um das erste Upgrade zu finden, das das Problem auslöst.
Führen Sie bei einem Upgrade die einzelnen Schritte nacheinander aus. Nachdem Sie das Upgrade ermittelt haben, das das Problem auslöst, können Sie möglicherweise einzelne Schritte im Upgrade deaktivieren. Wenn möglich, führen Sie jeden Schritt nacheinander aus, um herauszufinden, welcher dieser Schritte für den Fehler verantwortlich ist. Wenn Sie den entsprechenden Schritt nicht finden, sehen Sie in den Versionshinweisen der anderen von Ihnen verwendeten Gradle-Plug-ins nach, ob Kompatibilitätsprobleme mit Gradle oder AGP vorliegen. Manchmal wird mit einem neuen Release die Verwendung verworfener oder interner APIs behoben.
Fehler melden Manchmal sind alle vorbereitenden Schritte und die Synchronisierung erfolgreich, aber der letzte Upgradeschritt schlägt immer noch fehl. Melden Sie in diesem Fall bitte einen Fehler. Auch wenn Sie den Fehler selbst beheben konnten, sollten Sie dem Fehler-Tracker den ursprünglichen Fehler melden, damit das Problem vom Entwicklungsteam behoben werden kann.